phygnn.model_interfaces.tf_model.TfModel

class TfModel(model, feature_names=None, label_names=None, norm_params=None, normalize=(True, False), one_hot_categories=None)

Bases: ModelBase

TensorFlow Keras Sequential Model interface

Parameters:

• model (tensorflow.keras.models.Sequential) – Tensorflow Keras Model

• feature_names (list) – Ordered list of feature names.

• label_names (list) – Ordered list of label (output) names.

• norm_params (dict, optional) – Dictionary mapping feature and label names (keys) to normalization parameters (mean, stdev), by default None

• normalize (bool | tuple, optional) – Boolean flag(s) as to whether features and labels should be normalized. Possible values: - True means normalize both - False means don’t normalize either - Tuple of flags (normalize_feature, normalize_label) by default True

• one_hot_categories (dict, optional) – Features to one-hot encode using given categories, if None do not run one-hot encoding, by default None

Methods

build(feature_names, label_names[, ...])	Build tensorflow sequential model from given features, layers and kwargs
build_trained(features, labels[, normalize, ...])	Build tensorflow sequential model from given features, layers and kwargs and then train with given label and kwargs
compile_model(n_features[, n_labels, ...])	Build tensorflow sequential model from given layers and kwargs
dict_json_convert(inp)	Recursively convert numeric values in dict to work with json dump
get_mean(name)	Get feature | label mean
get_norm_params(names)	Get means and stdevs for given feature/label names
get_stdev(name)	Get feature | label stdev
load(path)	Load model from model path.
make_one_hot_feature_names(feature_names, ...)	Update feature_names after one-hot encoding
normalize(data[, names])	Normalize given data
parse_features(features[, names])	Parse features - preprocessing of feature data before training or prediction.
parse_labels(labels[, names])	Parse labels and normalize if desired
predict(features[, table, parse_kwargs, ...])	Use model to predict label from given features
save_model(path)	Save TfModel to path.
seed([s])	Set the random seed for reproducible results.
train_model(features, labels[, epochs, ...])	Train the model with the provided features and label
unnormalize(data[, names])	Un-normalize given data

Attributes

bias_weights	Get a list of the NN bias weights (tensors)
feature_dims	Number of features
feature_means	Feature means, used for (un)normalization
feature_names	List of the feature variable names.
feature_stdevs	Feature stdevs, used for (un)normalization
history	Model training history DataFrame (None if not yet trained)
input_feature_names	Input feature names
kernel_weights	Get a list of the NN kernel weights (tensors)
label_dims	Number of labels
label_means	label means, used for (un)normalization
label_names	label variable names
label_stdevs	label stdevs, used for (un)normalization
layers	Model layers
means	Mapping feature/label names to the mean values for (un)normalization
model	Trained model
model_summary	Tensorflow model summary
normalization_parameters	Features and label (un)normalization parameters
normalize_features	Flag to normalize features
normalize_labels	Flag to normalize labels
one_hot_categories	categories to use for one-hot encoding
one_hot_feature_names	One-hot encoded feature names
one_hot_input_feature_names	Input feature names to be one-hot encoded
stdevs	Mapping feature/label names to the stdev values for (un)normalization
version_record	A record of important versions that this model was built with.
weights	Get a list of layer weights for gradient calculations.

property layers

Model layers

Returns:

list

property weights

Get a list of layer weights for gradient calculations.

Returns:

list

property kernel_weights

Get a list of the NN kernel weights (tensors)

(can be used for kernel regularization).

Does not include input layer or dropout layers. Does include the output layer.

Returns:

list

property bias_weights

Get a list of the NN bias weights (tensors)

(can be used for bias regularization).

Does not include input layer or dropout layers. Does include the output layer.

Returns:

list

property history

Model training history DataFrame (None if not yet trained)

Returns:

pandas.DataFrame | None

static compile_model(n_features, n_labels=1, hidden_layers=None, input_layer=None, output_layer=None, learning_rate=0.001, loss='mean_squared_error', metrics=('mae', 'mse'), optimizer_class=<class 'keras.src.optimizers.adam.Adam'>, **kwargs)

Build tensorflow sequential model from given layers and kwargs

Parameters:

• n_features (int) – Number of features (inputs) to train the model on

• n_labels (int, optional) – Number of labels (outputs) to the model, by default 1

• hidden_layers (list | None, optional) – List of dictionaries of key word arguments for each hidden layer in the NN. Dense linear layers can be input with their activations or separately for more explicit control over the layer ordering. For example, this is a valid input for hidden_layers that will yield 7 hidden layers (9 layers total):

  [{‘units’: 64, ‘activation’: ‘relu’, ‘dropout’: 0.01},

  {‘units’: 64}, {‘batch_normalization’: {‘axis’: -1}}, {‘activation’: ‘relu’}, {‘dropout’: 0.01}]

  by default None which will lead to a single linear layer

• input_layer (None | bool | InputLayer) – Keras input layer. Will default to an InputLayer with input shape = n_features. Can be False if the input layer will be included in the hidden_layers input.

• output_layer (None | bool | list | dict) – Output layer specification. Can be a list/dict similar to hidden_layers input specifying a dense layer with activation. For example, for a classfication problem with a single output, output_layer should be [{‘units’: 1}, {‘activation’: ‘sigmoid’}] This defaults to a single dense layer with no activation (best for regression problems). Can be False if the output layer will be included in the hidden_layers input.

• learning_rate (float, optional) – tensorflow optimizer learning rate, by default 0.001

• loss (str, optional) – name of objective function, by default “mean_squared_error”

• metrics (list, optional) – List of metrics to be evaluated by the model during training and testing, by default (‘mae’, ‘mse’)

• optimizer_class (tf.keras.optimizers, optional) – Optional explicit request of optimizer. This should be a class that will be instantated in the TfModel.compile_model() method The default is the Adam optimizer

• kwargs (dict) – kwargs for tensorflow.keras.models.compile

Returns:

tensorflow.keras.models.Sequential – Compiled tensorflow Sequential model

train_model(features, labels, epochs=100, shuffle=True, validation_split=0.2, early_stop=True, stop_kwargs=None, parse_kwargs=None, fit_kwargs=None)

Train the model with the provided features and label

Parameters:

• features (dict | pandas.DataFrame) – Input features to train on

• labels (dict | pandas.DataFrame) – label to train on

• norm_labels (bool, optional) – Flag to normalize label, by default True

• epochs (int, optional) – Number of epochs to train the model, by default 100

• shuffle (bool) – Flag to randomly subset the validation data and batch selection from features and labels.

• validation_split (float, optional) – Fraction of the training data to be used as validation data, by default 0.2

• early_stop (bool) – Flag to stop training when it stops improving

• stop_kwargs (dict | None) – kwargs for tf.keras.callbacks.EarlyStopping() if early_stop default is: {‘monitor’: ‘val_loss’, ‘patience’: 10}

• parse_kwargs (dict | None) – kwargs for cls.parse_features

• fit_kwargs (dict | None) – kwargs for tensorflow.keras.models.fit

save_model(path)

Save TfModel to path.

Parameters:

path (str) – Directory path to save model to. The tensorflow model will be saved to the directory while the framework parameters will be saved in json.

classmethod load(path)

Load model from model path.

Parameters:

path (str) – Directory path for TfModel to load model from. There should be a saved model directory with json and pickle files for the TfModel framework.

Returns:

model (TfModel) – Loaded TfModel from disk.

classmethod build(feature_names, label_names, normalize=(True, False), one_hot_categories=None, hidden_layers=None, input_layer=None, output_layer=None, learning_rate=0.001, loss='mean_squared_error', metrics=('mae', 'mse'), optimizer_class=<class 'keras.src.optimizers.adam.Adam'>, **kwargs)

Build tensorflow sequential model from given features, layers and kwargs

Parameters:

• feature_names (list) – Ordered list of feature names.

• label_names (list) – Ordered list of label (output) names.

• normalize (bool | tuple, optional) – Boolean flag(s) as to whether features and labels should be normalized. Possible values: - True means normalize both - False means don’t normalize either - Tuple of flags (normalize_feature, normalize_label) by default True

• one_hot_categories (dict, optional) – Features to one-hot encode using given categories, if None do not run one-hot encoding, by default None

• hidden_layers (list | None, optional) – List of dictionaries of key word arguments for each hidden layer in the NN. Dense linear layers can be input with their activations or separately for more explicit control over the layer ordering. For example, this is a valid input for hidden_layers that will yield 7 hidden layers (9 layers total):

  [{‘units’: 64, ‘activation’: ‘relu’, ‘dropout’: 0.01},

  {‘units’: 64}, {‘batch_normalization’: {‘axis’: -1}}, {‘activation’: ‘relu’}, {‘dropout’: 0.01}]

  by default None which will lead to a single linear layer

• input_layer (None | bool | InputLayer) – Keras input layer. Will default to an InputLayer with input shape = n_features. Can be False if the input layer will be included in the hidden_layers input.

• output_layer (None | bool | list | dict) – Output layer specification. Can be a list/dict similar to hidden_layers input specifying a dense layer with activation. For example, for a classfication problem with a single output, output_layer should be [{‘units’: 1}, {‘activation’: ‘sigmoid’}] This defaults to a single dense layer with no activation (best for regression problems). Can be False if the output layer will be included in the hidden_layers input.

• learning_rate (float, optional) – tensorflow optimizer learning rate, by default 0.001

• loss (str, optional) – name of objective function, by default “mean_squared_error”

• metrics (list, optional) – List of metrics to be evaluated by the model during training and testing, by default (‘mae’, ‘mse’)

• optimizer_class (tf.keras.optimizers, optional) – Optional explicit request of optimizer. This should be a class that will be instantated in the TfModel.compile_model() method The default is the Adam optimizer

• kwargs (dict) – kwargs for tensorflow.keras.models.compile

Returns:

model (TfModel) – Initialized TfModel obj

classmethod build_trained(features, labels, normalize=(True, False), one_hot_categories=None, hidden_layers=None, input_layer=None, output_layer=None, learning_rate=0.001, loss='mean_squared_error', metrics=('mae', 'mse'), optimizer_class=<class 'keras.src.optimizers.adam.Adam'>, epochs=100, shuffle=True, validation_split=0.2, early_stop=True, stop_kwargs=None, save_path=None, compile_kwargs=None, parse_kwargs=None, fit_kwargs=None)

Build tensorflow sequential model from given features, layers and kwargs and then train with given label and kwargs

Parameters:

• features (dict | pandas.DataFrame) – Model features

• labels (dict | pandas.DataFrame) – label to train on

• normalize (bool | tuple, optional) – Boolean flag(s) as to whether features and labels should be normalized. Possible values: - True means normalize both - False means don’t normalize either - Tuple of flags (normalize_feature, normalize_label) by default True

• one_hot_categories (dict, optional) – Features to one-hot encode using given categories, if None do not run one-hot encoding, by default None

• hidden_layers (list | None, optional) – List of dictionaries of key word arguments for each hidden layer in the NN. Dense linear layers can be input with their activations or separately for more explicit control over the layer ordering. For example, this is a valid input for hidden_layers that will yield 7 hidden layers (9 layers total):

  [{‘units’: 64, ‘activation’: ‘relu’, ‘dropout’: 0.01},

  {‘units’: 64}, {‘batch_normalization’: {‘axis’: -1}}, {‘activation’: ‘relu’}, {‘dropout’: 0.01}]

  by default None which will lead to a single linear layer

• input_layer (None | bool | InputLayer) – Keras input layer. Will default to an InputLayer with input shape = n_features. Can be False if the input layer will be included in the hidden_layers input.

• output_layer (None | bool | list | dict) – Output layer specification. Can be a list/dict similar to hidden_layers input specifying a dense layer with activation. For example, for a classfication problem with a single output, output_layer should be [{‘units’: 1}, {‘activation’: ‘sigmoid’}] This defaults to a single dense layer with no activation (best for regression problems). Can be False if the output layer will be included in the hidden_layers input.

• learning_rate (float, optional) – tensorflow optimizer learning rate, by default 0.001

• loss (str, optional) – name of objective function, by default “mean_squared_error”

• metrics (list, optional) – List of metrics to be evaluated by the model during training and testing, by default (‘mae’, ‘mse’)

• optimizer_class (tf.keras.optimizers, optional) – Optional explicit request of optimizer. This should be a class that will be instantated in the TfModel.compile_model() method The default is the Adam optimizer

• epochs (int, optional) – Number of epochs to train the model, by default 100

• shuffle (bool) – Flag to randomly subset the validation data and batch selection from features and labels.

• validation_split (float, optional) – Fraction of the training data to be used as validation data, by default 0.2

• early_stop (bool) – Flag to stop training when it stops improving

• stop_kwargs (dict | None) – kwargs for tf.keras.callbacks.EarlyStopping() if early_stop default is: {‘monitor’: ‘val_loss’, ‘patience’: 10}

• save_path (str) – Directory path to save model to. The tensorflow model will be saved to the directory while the framework parameters will be saved in json.

• compile_kwargs (dict) – kwargs for tensorflow.keras.models.compile

• parse_kwargs (dict) – kwargs for cls.parse_features

• fit_kwargs (dict) – kwargs for tensorflow.keras.models.fit

Returns:

model (TfModel) – Initialized and trained TfModel obj

static dict_json_convert(inp)

Recursively convert numeric values in dict to work with json dump

Parameters:

inp (dict) – Dictionary to convert.

Returns:

out (dict) – Copy of dict input with all nested numeric values converted to base python int or float and all arrays converted to lists.

property feature_dims

Number of features

Returns:

int

property feature_means

Feature means, used for (un)normalization

Returns:

list

property feature_names

List of the feature variable names.

Returns:

list

property feature_stdevs

Feature stdevs, used for (un)normalization

Returns:

list

get_mean(name)

Get feature | label mean

Parameters:

name (str) – feature | label name

Returns:

mean (float) – Mean value used for normalization

get_norm_params(names)

Get means and stdevs for given feature/label names

Parameters:

names (list) – list of feature/label names to get normalization params for

Returns:

• means (list) – List of means to use for (un)normalization

• stdevs (list) – List of stdevs to use for (un)normalization

get_stdev(name)

Get feature | label stdev

Parameters:

name (str) – feature | label name

Returns:

stdev (float) – Stdev value used for normalization

property input_feature_names

Input feature names

Returns:

list

property label_dims

Number of labels

Returns:

int

property label_means

label means, used for (un)normalization

Returns:

list

property label_names

label variable names

Returns:

list

property label_stdevs

label stdevs, used for (un)normalization

Returns:

list

static make_one_hot_feature_names(feature_names, one_hot_categories)

Update feature_names after one-hot encoding

Parameters:

• feature_names (list) – Input feature names

• one_hot_categories (dict) – Features to one-hot encode using given categories

Returns:

one_hot_feature_names (list) – Updated list of feature names with one_hot categories

property means

Mapping feature/label names to the mean values for (un)normalization

Returns:

dict

property model

Trained model

Returns:

tensorflow.keras.models

property model_summary

Tensorflow model summary

Returns:

str

property normalization_parameters

Features and label (un)normalization parameters

Returns:

dict

normalize(data, names=None)

Normalize given data

Parameters:

• data (dict | pandas.DataFrame | ndarray) – Data to normalize

• names (list, optional) – List of data item names, needed to normalized ndarrays, by default None

Returns:

data (dict | pandas.DataFrame | ndarray) – Normalized data in same format as input

property normalize_features

Flag to normalize features

Returns:

bool

property normalize_labels

Flag to normalize labels

Returns:

bool

property one_hot_categories

categories to use for one-hot encoding

Returns:

dict

property one_hot_feature_names

One-hot encoded feature names

Returns:

list

property one_hot_input_feature_names

Input feature names to be one-hot encoded

Returns:

list

parse_features(features, names=None, **kwargs)

Parse features - preprocessing of feature data before training or prediction. This will do one-hot encoding based on self.one_hot_categories, and feature normalization based on self.normalize_features

Parameters:

• features (pandas.DataFrame | dict | ndarray) – Features to train on or predict from

• names (list, optional) – List of feature names, by default None

• kwargs (dict, optional) – kwargs for PreProcess.one_hot

Returns:

features (ndarray) – Parsed features array normalized and with str columns converted to one hot vectors if desired

parse_labels(labels, names=None)

Parse labels and normalize if desired

Parameters:

• labels (pandas.DataFrame | dict | ndarray) – Features to train on or predict from

• names (list, optional) – List of label names, by default None

Returns:

labels (ndarray) – Parsed labels array, normalized if desired

predict(features, table=True, parse_kwargs=None, predict_kwargs=None)

Use model to predict label from given features

Parameters:

• features (dict | pandas.DataFrame) – features to predict from

• table (bool, optional) – Return pandas DataFrame

• parse_kwargs (dict) – kwargs for cls.parse_features

• predict_kwargs (dict) – kwargs for tensorflow.*.predict

Returns:

prediction (ndarray | pandas.DataFrame) – label prediction

static seed(s=0)

Set the random seed for reproducible results. :Parameters: s (int) – Random number generator seed

property stdevs

Mapping feature/label names to the stdev values for (un)normalization

Returns:

dict

unnormalize(data, names=None)

Un-normalize given data

Parameters:

• data (dict | pandas.DataFrame | ndarray) – Data to un-normalize

• names (list, optional) – List of data item names, needed to un-normalized ndarrays, by default None

Returns:

data (dict | pandas.DataFrame | ndarray) – Native data in same format as input

property version_record

A record of important versions that this model was built with.

Returns:

dict