pyanno4rt.learning_model.frequentist._neural_network
Neural network model.
Overview
Neural network model class. |
Classes
- class pyanno4rt.learning_model.frequentist._neural_network.NeuralNetworkModel(model_label, model_folder_path, dataset, preprocessing_steps, architecture, max_hidden_layers, tune_space, tune_evaluations, tune_score, inspect_model, evaluate_model, display_options)[source]
Neural network model class.
This class enables building an individual preprocessing pipeline, fit the neural network model from the input data, inspect the model, make predictions with the model, and assess the predictive performance using multiple evaluation metrics.
The training process includes sequential model-based hyperparameter optimization with tree-structured Parzen estimators and stratified k-fold cross-validation for the objective function evaluation. Cross-validation is also applied to (optionally) inspect the validation feature importances and to generate out-of-folds predictions as a full reconstruction of the input labels for generalization assessment.
- Parameters:
model_label (string) – Label for the neural network model to be used for file naming.
dataset (dict) – Dictionary with the raw data set, the label viewpoint, the label bounds, the feature values and names, and the label values and names after modulation. In a compact way, this represents the input data for the neural network model.
preprocessing_steps (tuple) –
Sequence of labels associated with preprocessing algorithms which make up the preprocessing pipeline for the neural network model. Current available algorithm labels are:
transformers : ‘Equalizer’, ‘StandardScaler’, ‘Whitening’.
architecture ({'input-convex', 'standard'}) –
Type of architecture for the neural network model. Current available architectures are:
’input-convex’ : builds the input-convex network architecture;
’standard’ : builds the standard feed-forward network architecture.
max_hidden_layers (int) – Maximum number of hidden layers for the neural network model.
tune_space (dict) –
Search space for the Bayesian hyperparameter optimization, including
’input_neuron_number’ : number of neurons for the input layer;
’input_activation’ : activation function for the input layer (‘elu’, ‘exponential’, ‘gelu’, ‘linear’, ‘leaky_relu’, ‘relu’, ‘softmax’, ‘softplus’, ‘swish’);
’hidden_neuron_number’ : number of neurons for the hidden layer(s);
’hidden_activation’ : activation function for the hidden layer(s) (‘elu’, ‘gelu’, ‘linear’, ‘leaky_relu’, ‘relu’, ‘softmax’, ‘softplus’, ‘swish’);
’input_dropout_rate’ : dropout rate for the input layer;
’hidden_dropout_rate’ : dropout rate for the hidden layer(s);
’batch_size’ : batch size;
’learning_rate’ : learning rate
’optimizer’ : algorithm for the optimization of the network (‘Adam’, ‘Ftrl’, ‘SGD’);
’loss’ : loss function for the optimization of the network (‘BCE’, ‘FocalBCE’, ‘KLD’).
tune_evaluations (int) – Number of evaluation steps (trials) for the Bayesian hyperparameter optimization.
tune_score (string) –
Scoring function for the evaluation of the hyperparameter set candidates. Current available scorers are:
’log_loss’ : negative log-likelihood score;
’roc_auc_score’ : area under the ROC curve score.
tune_splits (int) – Number of splits for the stratified cross-validation within each hyperparameter optimization step.
inspect_model (bool) – Indicator for the inspection of the model, e.g. the feature importances.
inspect_model – Indicator for the inspection of the model, e.g. the feature importances.
evaluate_model (bool) – Indicator for the evaluation of the model, e.g. the model KPIs.
oof_splits (int) – Number of splits for the stratified cross-validation within the out-of-folds evaluation step of the logistic regression model.
- preprocessor
Instance of the class DataPreprocessor, which holds methods to build the preprocessing pipeline, fit with the input features, transform the features, and derive the gradient of the preprocessing algorithms w.r.t the features.
- Type:
object of class DataPreprocessor
- features
Values of the input features.
- Type:
ndarray
- labels
Values of the input labels.
- Type:
ndarray
- configuration
Dictionary with information for the modeling, i.e., the dataset, the preprocessing, and the hyperparameter search space.
- Type:
dict
- model_path
Path for storing and retrieving the neural network model.
- Type:
string
- configuration_path
Path for storing and retrieving the configuration dictionary.
- Type:
string
- hyperparameter_path
Path for storing and retrieving the hyperparameter dictionary.
- Type:
string
- updated_model
Indicator for the update status of the model, triggers recalculating the model inspection and model evaluation classes.
- Type:
bool
- prediction_model
Instance of the class Functional, which holds methods to make predictions from the neural network model.
- Type:
object of class Functional
- optimization_model
Instance of the class Functional, equivalent to
prediction_model, but skips the sigmoid output activation.- Type:
object of class Functional
- inspector
Instance of the class ModelInspector, which holds methods to compute model inspection values, e.g. feature importances.
- Type:
object of class ModelInspector
- training_prediction
Array with the label predictions on the input data.
- Type:
ndarray
- oof_prediction
Array with the out-of-folds predictions on the input data.
- Type:
ndarray
- evaluator
Instance of the class ModelEvaluator, which holds methods to compute the evaluation metrics for a given array with label predictions.
- Type:
object of class ModelEvaluator
Notes
Currently, the preprocessing pipeline for the model is restricted to transformations of the input feature values, e.g. scaling, dimensionality reduction or feature engineering. Transformations which affect the input labels in the same way, e.g. resampling or outlier removal, are not yet possible.
Overview
Methods preprocess(features)Preprocess the input feature vector with the built pipeline.
get_prediction_model(features, labels)Get the neural network outcome prediction model by reading from the model file path, the datahub, or by training.
get_optimization_model(features, labels)Get the neural network outcome optimization model.
build_network(input_shape, output_shape, hyperparameters, squash_output)Build the neural network architecture with the functional API.
compile_and_fit(prediction_model, features, labels, hyperparameters)Compile and fit the neural network outcome prediction model to the input data.
tune_hyperparameters(features, labels)Tune the hyperparameters of the neural network model via sequential model-based optimization using the tree-structured Parzen estimator. As a variation, the objective function is evaluated based on a stratified k-fold cross-validation.
train(features, labels)Train the neural network outcome prediction model.
predict(features, squash_output)Predict the label values from the feature values.
predict_oof(features, labels)Predict the out-of-folds (OOF) labels using a stratified k-fold cross-validation.
inspect(features, labels, oof_folds).
evaluate(features, labels).
set_file_paths(base_path)Set the paths for model, configuration and hyperparameter files.
Read the neural network outcome prediction model from the model file path.
write_model_to_file(prediction_model)Write the neural network outcome prediction model to the model file path.
Read the configuration dictionary from the configuration file path.
write_configuration_to_file(configuration)Write the configuration dictionary to the configuration file path.
Read the neural network outcome prediction model hyperparameters from the hyperparameter file path.
write_hyperparameters_to_file(hyperparameters)Write the hyperparameter dictionary to the hyperparameter file path.
Members
- preprocess(features)[source]
Preprocess the input feature vector with the built pipeline.
- Parameters:
features (ndarray) – Array of input feature values.
- Returns:
Array of transformed feature values.
- Return type:
ndarray
- get_prediction_model(features, labels)[source]
Get the neural network outcome prediction model by reading from the model file path, the datahub, or by training.
- Returns:
Instance of the class Functional, which holds methods to make predictions from the neural network model.
- Return type:
object of class Functional
- get_optimization_model(features, labels)[source]
Get the neural network outcome optimization model.
- Returns:
Instance of the class Functional, which holds methods to make predictions from the neural network model.
- Return type:
object of class Functional
- build_network(input_shape, output_shape, hyperparameters, squash_output)[source]
Build the neural network architecture with the functional API.
- Parameters:
input_shape (int) – Shape of the input features.
output_shape (int) – Shape of the output labels.
hyperparameters (dict) – Dictionary with the hyperparameter names and values for the neural network outcome prediction model.
squash_output (bool) – Indicator for the use of a sigmoid activation function in the output layer.
- Returns:
Instance of the class Functional, which holds methods to make predictions from the neural network model.
- Return type:
object of class ‘Functional’
- compile_and_fit(prediction_model, features, labels, hyperparameters)[source]
Compile and fit the neural network outcome prediction model to the input data.
- Parameters:
prediction_model (object of class Functional) – Instance for the provision of the neural network architecture.
features (tf.float64) – Casted array of input feature values.
labels (tf.float64) – Casted array of input label values.
hyperparameters (dict) – Dictionary with the hyperparameter names and values for the neural network outcome prediction model.
- Returns:
prediction_model – Instance of the class Functional, which holds methods to make predictions from the neural network model.
- Return type:
object of class Functional
- tune_hyperparameters(features, labels)[source]
Tune the hyperparameters of the neural network model via sequential model-based optimization using the tree-structured Parzen estimator. As a variation, the objective function is evaluated based on a stratified k-fold cross-validation.
- Returns:
tuned_hyperparameters – Dictionary with the hyperparameter names and values tuned via Bayesian hyperparameter optimization.
- Return type:
dict
- train(features, labels)[source]
Train the neural network outcome prediction model.
- Returns:
prediction_model – Instance of the class Functional, which holds methods to make predictions from the neural network model.
- Return type:
object of class Functional
- predict(features, squash_output=True)[source]
Predict the label values from the feature values.
- Parameters:
features (ndarray) – Array of input feature values.
squash_output (bool) – Indicator for the use of a sigmoid activation function in the output layer.
- Returns:
Floating-point label prediction or array of label predictions.
- Return type:
float or ndarray
- predict_oof(features, labels)[source]
Predict the out-of-folds (OOF) labels using a stratified k-fold cross-validation.
- Parameters:
oof_splits (int) – Number of splits for the stratified cross-validation.
- Returns:
Array with the out-of-folds label predictions.
- Return type:
ndarray
- set_file_paths(base_path)[source]
Set the paths for model, configuration and hyperparameter files.
- Parameters:
base_path (string) – Base path from which to access the model files.
- read_model_from_file()[source]
Read the neural network outcome prediction model from the model file path.
- Returns:
Instance of the class Functional, which holds methods to make predictions from the neural network model.
- Return type:
object of class Functional
- write_model_to_file(prediction_model)[source]
Write the neural network outcome prediction model to the model file path.
- Parameters:
prediction_model (object of class Functional) – Instance of the class Functional, which holds methods to make predictions from the neural network model.
- read_configuration_from_file()[source]
Read the configuration dictionary from the configuration file path.
- Returns:
Dictionary with information for the modeling, i.e., the dataset, the preprocessing steps, and the hyperparameter search space.
- Return type:
dict
- write_configuration_to_file(configuration)[source]
Write the configuration dictionary to the configuration file path.
- Parameters:
configuration (dict) – Dictionary with information for the modeling, i.e., the dataset, the preprocessing steps, and the hyperparameter search space.