High-Level API

The API module provides high-level wrappers to simplify the training, evaluation, and management of HeteroSymNN models.

Model Wrapper

class HeteroSymNN.API.wrappers.Wraper(model: ConfigurableNN, work_type: Literal['class', 'reg'], normalize_inputs: bool = True, normalize_outputs: bool = True)[source]

Bases: object

A high-level wrapper for managing the lifecycle of a ConfigurableNN, FlexibleNN or SimpleNN

This class simplifies common tasks such as:

  • Data loading and normalization (Min-Max scaling).

  • Training execution and loss tracking.

  • Model evaluation (Classification metrics or Regression metrics).

  • Saving and loading the full model state (architecture, weights, optimizer state).

Parameters:

  • model (ConfigurableNN | FlexibleNN | SimpleNN or None) – The neural network instance to wrap. Can be None if loading a model from disk later.

  • work_type (Literal["class", "reg"]) –

    The type of problem the model solves:

    • "class": Classification (calculates Accuracy, F1, etc.).

    • "reg": Regression (calculates MSE, R2, etc.).

  • normalize_inputs (bool, optional) – If True, input data (X) will be automatically normalized to [0, 1] based on training data statistics. Defaults to True.

  • normalize_outputs (bool, optional) – If True, output data (Y) will be automatically normalized to [0, 1] during training and denormalized during prediction. Defaults to True.

The primary interface for interacting with neural networks.

It abstracts away the complexity of:

  • Data Normalization (Min-Max scaling).

  • Training loops.

  • Model persistence (Saving/Loading to .npz).

  • Accuracy testing (Regression and Classification metrics).

Example Usage:

agent = Wraper(model, work_type="reg")
agent.load_training(X_train, y_train)
agent.run_training(num_iterations=100)
prediction = agent.predict(X_new)
classification_test_accuracy(test_data: list, expected_results: list) → tuple[dict[str, float], dict[str, int]][source]

Calculates classification metrics (Accuracy, Precision, Recall/TPR, F1 Score).

Note: Currently assumes binary classification or multi-label where threshold is 0.5.

Returns:

A tuple containing:

  1. Dictionary of metrics (Acur, Press, TPR, F1).

  2. Dictionary of raw counts (TP, TN, FP, FN).

Return type:

tuple[dict[str, float], dict[str, int]]

fit(training_data: list, expected_results: list, epochs: int | None = None, training_mode: Literal['batch', 'mini-batch', 'stochastic'] | None = None, batch_size: int | None = None) → list[float][source]

Method like Scikit Learn for training the model.

Parameters:

  • training_data (list or np.ndarray) – Input features (X). Shape should be (n_samples, n_features).

  • expected_results (list or np.ndarray) – Target labels/values (Y). Shape should be (n_samples, n_outputs).

  • epochs (int, optional) – Number of epochs to train. If None, uses the model’s configured default.

  • training_mode (Literal["batch", "mini-batch", "stochastic"], optional) – Training strategy. If None, uses the model’s configured default.

  • batch_size (int, optional) – Size of the batch for “mini-batch” mode. If not pass, uses the model’s configured default.

Returns:

A list of loss values recorded during training.

Return type:

list[float]

Raises:

ValueError – If dimensions do not match the model’s expected input/output size.

load_model(path: str) → None[source]

Loads a model from a .npz file created by save_model().

Reconstructs the ConfigurableNN, restores weights, optimizer state, and normalization statistics.

Parameters:

path (str) – Path to the .npz file.

Raises:

IOError – If the file cannot be loaded or has an invalid format.

load_training(training_data: list, expected_results: list) → None[source]

Loads and prepares training data.

This method performs the following steps:

  1. Converts inputs to NumPy arrays.

  2. Checks dimensions against the model architecture (if a model is set).

  3. Calculates normalization statistics (min/max) if normalization is enabled.

  4. Stores the normalized data for training.

Parameters:

  • training_data (list or np.ndarray) – Input features (X). Shape should be (n_samples, n_features).

  • expected_results (list or np.ndarray) – Target labels/values (Y). Shape should be (n_samples, n_outputs).

Raises:

ValueError – If dimensions do not match the model’s expected input/output size.

property model: ConfigurableNN

The underlying neural network instance.

When setting this property, the wrapper validates that the new model’s input/output dimensions match any previously loaded training data.

predict(data: list) → numpy.ndarray[source]

Generates predictions for new data.

Handles input normalization and output denormalization automatically if configured.

Parameters:

data (list or np.ndarray) – Input features to predict.

Returns:

Predicted values (denormalized if normalize_outputs=True).

Return type:

np.ndarray

regreccion_test_accuracy(test_data: list, expected_results: list) → dict[str, float][source]

Calculates regression metrics (R2, MSE, RMSE, MAE, MAPE, AIC, BIC).

Returns:

Dictionary containing the calculated metrics.

Return type:

dict[str, float]

run_training(num_iterations: int | None = None, training_mode: Literal['batch', 'mini-batch', 'stochastic'] | None = None, batch_size: int | None = None) → list[float][source]

Executes the training loop on the loaded data.

Parameters:

  • num_iterations (int, optional) – Number of epochs to train. If None, uses the model’s configured default.

  • training_mode (Literal["batch", "mini-batch", "stochastic"], optional) – Training strategy. If None, uses the model’s configured default.

  • batch_size (int, optional) – Size of the batch for “mini-batch” mode. If not pass, uses the model’s configured default.

Returns:

A list of loss values recorded during training.

Return type:

list[float]

save_model(path: str, model_name: str, description: str | None = None) → None[source]

Saves the model architecture, parameters, optimizer state, and wrapper configuration to a file.

The file is saved as a compressed NumPy archive (.npz).

Parameters:

  • path (str) – Directory path to save the file.

  • model_name (str) – Name of the file (without extension).

  • description (str, optional) – Optional description to store in metadata.

test_accuracy(test_data: list, expected_results: list) → dict[str, float] | tuple[dict[str, float], dict[str, int]][source]

Evaluates the model on a test dataset.

Parameters:

  • test_data (list) – Input features for testing.

  • expected_results (list) – Ground truth values.

Returns:

Evaluation metrics depending on work_type.

Return type:

dict or tuple

Grid Search Wrapper

class HeteroSymNN.API.wrappers.GridSearchWraper(Model_class: Callable, work_type: Literal['class', 'reg'], validation_testing_split=0.2, normalize_inputs: bool = True, normalize_outputs: bool = True)[source]

Bases: Wraper

A wrapper that extends Wraper to perform Hyperparameter Grid Search.

Parameters:

  • Model_class (Callable) – The class constructor to use for creating models (e.g., SimpleNN).

  • work_type (Literal["class", "reg"]) – Type of problem (classification or regression).

  • validation_testing_split (float, optional) – Fraction of data to use for validation during grid search (default 0.2).

  • normalize_inputs (bool, optional) – Whether to normalize inputs.

  • normalize_outputs (bool, optional) – Whether to normalize outputs.

A tool for Hyperparameter Optimization.

It automatically splits training data into Train/Validation sets and tests combinations of parameters.

Key Features:

  • Automatic Splitting: Splits data into training and validation sets.

  • Metric Tracking: Tracks R2 (Regression) or Accuracy (Classification).

  • Best Model Retention: Automatically keeps the best performing model instance.

load_training(training_data: list, expected_results: list, shuffle: bool = True) → None[source]

Loads data and splits it into Training and Validation sets.

Parameters:

  • training_data (list) – All available input data.

  • expected_results (list) – All available target data.

  • shuffle (bool, optional) – Whether to shuffle data before splitting (default True).

run_training(static_params: dict[str, any] | None = None, param_grid: dict[str, list[any]] | None = None, metric_to_optimize: str = 'R2', higher_is_better: bool = True, num_iterations: int | None = None, training_mode: Literal['batch', 'mini-batch', 'stochastic'] | None = None, batch_size: int | None = None) → list[float] | tuple[ConfigurableNN, dict[str, any], list[dict[str, any]]][source]

Executes training. Can function in two modes:

  1. Grid Search Mode: If param_grid is provided. Iterates through all parameter combinations, trains a new model for each, evaluates on the validation set, and selects the best one.

  2. Standard Training Mode: If param_grid is None. Trains the currently active model (e.g., the best model found) for additional iterations.

Parameters:

  • static_params (dict[str, any], optional) – Parameters that remain constant across all grid search trials (e.g., input size).

  • param_grid (dict[str, list[any]], optional) – Dictionary where keys are parameter names and values are lists of possibilities to try.

  • metric_to_optimize (str, optional) – The metric name to use for selecting the best model (e.g., ‘R2’, ‘Acur’, ‘MSE’).

  • higher_is_better (bool, optional) – True if maximizing the metric (ejem. for Accuracy or R2), False if minimizing (ejem. for MSE).

  • num_iterations (int, optional) – Number of training iterations. If None, uses the model’s configured default.

  • training_mode (Literal["batch", "mini-batch", "stochastic"], optional) – Training strategy. If None, uses the model’s configured default.

  • batch_size (int, optional) – Size of the batch when using “mini-batch” mode. If not pass, uses the model’s configured default.

Returns:

In Grid Search mode: Returns (best_model, best_params, all_results). In Standard mode: Returns the loss history list.

Return type:

tuple or list