vulcanai.models package¶
vulcanai.models.basenetwork module¶
Defines the basenetwork class.
-
class
vulcanai.models.basenetwork.
BaseNetwork
(name, config, in_dim=None, save_path=None, input_networks=None, num_classes=None, activation=ReLU(), pred_activation=None, optim_spec={'lr': 0.001, 'name': 'Adam'}, lr_scheduler=None, early_stopping=None, early_stopping_patience=None, early_stopping_metric='accuracy', criter_spec=CrossEntropyLoss(), device='cuda:0')¶ Bases:
torch.nn.modules.module.Module
Defines the BaseNetwork object.
- Parameters:
- name : str
- The name of the network. Used when saving the file.
- config : dict
- The configuration of the network module, as a dict.
- in_dim : tuple
- The input dimensions of the network. Not required to specify when the network has input_networks.
- save_path : str
- The name of the file to which you would like to save this network.
- input_networks : list of BaseNetwork
- A network object provided as input.
- num_classes : int or None
- The number of classes to predict. In the binary case always specify 2 classes no matter the shape of the data. A value of 1 is used for predicting a single continuous value.
- activation : torch.nn.Module
- The desired activation function for use in the network.
- pred_activation : torch.nn.Module
- The desired activation function for use in the prediction layer.
- optim_spec : dict
- A dictionary of parameters for the desired optimizer.
- lr_scheduler : torch.optim.lr_scheduler
- A callable torch.optim.lr_scheduler
- early_stopping : str or None
- So far just ‘best_validation_error’ is implemented.
- early_stopping_patience: integer
- Number of validation iterations of decreasing loss (note -not necessarily every epoch! before early stopping is applied.
- early_stopping_metric: string
- Either “loss” or “accuracy” are implemented.
- criter_spec : dict
- criterion specification with name and all its parameters.
- device : str or torch.device
- Sets the network module to the relevant device. If cuda available in the host console, “cuda:0” will be run which can be overriden.
- Returns:
- network : BaseNetwork
-
class
EarlyStopping
(patience=2, verbose=False)¶ Bases:
object
Early stops the training if validation loss doesn’t improve after a given number of epochs. Args:
- patience: int default 7
- How many epochs to wait after last time validation loss improved.
- verbose: bool default False
- If True, prints a message for each validation loss improvement.
-
__init__
(patience=2, verbose=False)¶ Initialize early stopping
-
save_checkpoint
(val_loss, model)¶ Saves model when validation loss decrease.
-
__init__
(name, config, in_dim=None, save_path=None, input_networks=None, num_classes=None, activation=ReLU(), pred_activation=None, optim_spec={'lr': 0.001, 'name': 'Adam'}, lr_scheduler=None, early_stopping=None, early_stopping_patience=None, early_stopping_metric='accuracy', criter_spec=CrossEntropyLoss(), device='cuda:0')¶ Define, initialize, and build the BaseNetwork.
-
assert_same_devices
(comparison_device=None)¶ Will check if all incoming networks are on the same device.
Raises specific error about which device the networks need to be re-assigned to.
Specific for when calling fit becuase of grad calculation across several devices not compatible with optimizer. Temporary until replaced with nn.DataParallel or better multi-gpu implmentation.
- Parameters:
- comparison_device : str or torch.device
- The device to compare current device to.
-
bootfold_p_estimate
(data_loader, n_samples, k, epochs, index_to_iter, ls_feat_vals, retain_graph=None, valid_interv=4, plot=False, save_path=None, p_output_path=None, **kwargs)¶ Performs bootfold - estimation to identify whether training model provides statistically significant difference in predicting various values for a given feature when predicting outcome.
- Parameters:
- data_loader : torch.utils.data.DataLoader
- The DataLoader object containing the totality of the data to use for k-fold cross validation.
- n_samples : int
- number of times to randomly sample w/ replacement the data_loader and perform boot_cv
- k : int
- The number of folds to split the training into.
- epochs : int
- The number of epochs to train the network per fold.
- index_to_iter : string
- Index of feature within data_loader who’s values will be iterated to assess difference.
- ls_feat_vals : list
- List of values for feature provided in feat_to_iter
- retain_graph: boolean
- Whether or not to retain the computation graph.
- valid_interv : int
- Specifies after how many epochs validation should occur.
- plot : boolean
- Whether or not to plot all results in prompt and charts.
- save_path : str
- Where to save all figures and results.
- p_output_path: str
- Output file to save p_value to
- kwargs: dict of keyworded parameters
- Values passed to transform callable (function parameters)
- Returns:
- p_value : float
-
criter_spec
¶ Return the criterion specification.
- Returns:
- _criter_spec : dict
- The criterion specification.
-
cross_validate
(data_loader, k, epochs, average_results=True, retain_graph=None, valid_interv=4, plot=False, save_path=None, transform_callable=None, **kwargs)¶ Perform k-fold cross validation given a Network and DataLoader object.
- Parameters:
- data_loader : torch.utils.data.DataLoader
- The DataLoader object containing the totality of the data to use for k-fold cross validation.
- k : int
- The number of folds to split the training into.
- epochs : int
- The number of epochs to train the network per fold.
- average_results : boolean
- Whether or not to return results from all folds or just an average.
- retain_graph : {None, boolean}
- Whether retain_graph will be true when .backwards is called.
- valid_interv : int
- Specifies after how many epochs validation should occur.
- plot : boolean
- Whether or not to plot all results in prompt and charts.
- save_path : str
- Where to save all figures and results.
- transform_callable: callable
- A torch function. e.g. torch.round()
- kwargs: dict of keyworded parameters
- Values passed to transform callable (function parameters)
- Returns:
- results : dict
- If average_results is on, return dict of floats. If average_results is off, return dict of float lists.
-
device
¶ Return the relevant device associalted with network module.
- Returns:
- device : torch.device
- Relevant device associalted with the network module.
-
early_stopping
¶ Return the stopping rule.
- Returns:
- stopping_rule : str
- The stoping rule
-
early_stopping_metric
¶ Return the early stopping netric.
- Returns:
- early_stopping_metric : string
- The early stopping metric
-
early_stopping_patience
¶ Return the early stopping patience.
- Returns:
- early_stopping_patience : int
- The early stopping patience
-
extra_repr
()¶ Set the extra representation of the module.
-
fit
(train_loader, val_loader, epochs, retain_graph=None, valid_interv=4, plot=False, save_path=None)¶ Train the network on the provided data.
- Parameters:
- train_loader : DataLoader
- The DataLoader object containing the training data.
- val_loader : DataLoader
- The DataLoader object containing the validation data.
- epochs : int
- The number of epochs to train for.
- retain_graph : {None, True, False}
- Whether retain_graph will be true when .backwards is called.
- valid_interv : int
- Specifies the period of epochs before validation calculation.
- plot : boolean
- Whether or not to plot training metrics in real-time.
- save_path : str
- Path to save graphics at
- Returns:
- None
-
forward
(inputs, **kwargs)¶ Perform a forward pass through the modules.
If the network is defined with num_classes then it contains a classification layer/network tail. The inputs will be passed through the networks and then through the classifier. If not, the input is passed through the network and returned without passing through a classification layer.
If nn.CrossEntropyLoss is used, the values will not have been passed though a softmax function and this therefore must be done manually.
- Parameters:
- inputs : list(torch.Tensor)
- The inputs to pass throught the network.
- Returns:
- output : torch.Tensor
-
forward_pass
(data_loader, transform_callable=None, **kwargs)¶ Allows the user to pass data through the network with the autograd engine deactivated. Passes data through a final_transform if it is needed (e.g. if CrossEntropyLoss was used and values are therefore not passed through a final layer softmax). Takes a dataloader as input instead of a single tensor. More efficient than calling forward for inference. Parameters:
- data_loader : DataLoader
- DataLoader object to make the pass with.
- transform_callable: callable
- A torch function. e.g. torch.round() used to transform the outputs before they are passed to some scoring function.
- kwargs: dict of keyworded parameters
- Values passed to transform callable (function parameters)
- Returns:
- outputs : numpy.ndarray
- Numpy matrix with the output. Same shape as network out_dim.
-
freeze
(apply_inputs=False)¶ Freeze network weights so training doesn’t modify them.
- Parameters:
- apply_inputs : boolean
- Whether to freeze all input networks recursively
- Returns:
- None
-
get_layers
()¶ Return an ordered dict of all modules in this network (layers).
- Returns:
- layers : OrderedDict()
-
get_weights
()¶ Return a dictionary containing a whole state of the module.
- Returns:
- weights : dict
- A dictionary containing a whole state of the module.
-
is_cuda
¶ Return boolean about whether the network is on cuda device (i.e gpu).
- Returns:
- is_cuda : boolean
- Specifies whether the network is on gpu or not.
-
classmethod
load_model
(load_path, load_complete_model_stack=True)¶ Load the model from the given directory.
- Parameters:
- load_path : str
- The load directory (not a file)
- load_complete_model_stack : boolean
- Whether to load all parent networks as well. Not yet implemented.
- Returns:
- network : BaseNetwork
- A network object with all components intact.
-
lr_scheduler
¶ Return the network lr_scheduler.
- Returns:
- lr_scheduler : torch.optim.lr_scheduler
-
name
¶ Return the name.
- Returns:
- name : string
- The name of the network.
-
run_test
(data_loader, plot=False, save_path=None, pos_label=1, transform_callable=None, **kwargs)¶ Will conduct the test suite to determine network strength. Using metrics.run_test
- Parameters:
- data_loader : DataLoader
- A DataLoader object to run the test with.
- save_path : string
- Folder to place images in.
- plot: bool
- Determine if graphs should be plotted in real time.
- pos_label: int
- The label that is positive in the binary case for macro calculations.
- transform_callable: callable
- A torch function. e.g. torch.round()
- kwargs: dict of keyworded parameters
- Values passed to transform callable (function parameters)
- Returns:
- results : dict
-
save_model
(save_path=None)¶ Save the model (and it’s input networks).
- Parameters:
- save_path : str
- The save directory (not a file)
- Returns:
- save_path : str
- The save path where you’ll find the model directly.
-
save_path
¶ Return the save path of the network.
- Returns:
- save_path : string
- The save path of the network.
-
unfreeze
(apply_inputs=False)¶ Unfreeze network weights so training does modify them.
- Parameters:
- apply_inputs : boolean
- Whether to unfreeze all input networks recursively
- Returns:
- None
vulcanai.models.cnn module¶
Defines the ConvNet class.
-
class
vulcanai.models.cnn.
ConvNet
(name, config, in_dim=None, save_path=None, input_networks=None, num_classes=None, activation=ReLU(), pred_activation=None, optim_spec={'lr': 0.001, 'name': 'Adam'}, lr_scheduler=None, early_stopping=None, early_stopping_patience=None, early_stopping_metric='accuracy', criter_spec=CrossEntropyLoss(), device='cuda:0')¶ Bases:
vulcanai.models.basenetwork.BaseNetwork
Subclass of BaseNetwork defining a ConvNet.
- Parameters:
- name : str
- The name of the network. Used when saving the file.
- config : dict
- The configuration of the network module, as a dict.
- in_dim : tuple
- The input dimensions of the network. Not required to specify when the network has input_networks.
- save_path : str
- The name of the file to which you would like to save this network.
- input_networks : list of BaseNetwork
- A network object provided as input.
- num_classes : int or None
- The number of classes to predict.
- activation : torch.nn.Module
- The desired activation function for use in the network.
- pred_activation : torch.nn.Module
- The desired activation function for use in the prediction layer.
- optim_spec : dict
- A dictionary of parameters for the desired optimizer.
- lr_scheduler : torch.optim.lr_scheduler
- A callable torch.optim.lr_scheduler
- early_stopping : str or None
- So far just ‘best_validation_error’ is implemented.
- early_stopping_patience: integer
- Number of validation iterations of decreasing loss (note -not necessarily every epoch! before early stopping is applied.
- early_stopping_metric: string
- Either “loss” or “accuracy” are implemented.
- criter_spec : dict
- criterion specification with name and all its parameters.
- Returns:
- network : ConvNet
- A network of type BaseNetwork.
-
__init__
(name, config, in_dim=None, save_path=None, input_networks=None, num_classes=None, activation=ReLU(), pred_activation=None, optim_spec={'lr': 0.001, 'name': 'Adam'}, lr_scheduler=None, early_stopping=None, early_stopping_patience=None, early_stopping_metric='accuracy', criter_spec=CrossEntropyLoss(), device='cuda:0')¶ Define the ConvNet object.
vulcanai.models.dnn module¶
Defines the DenseNet class.
-
class
vulcanai.models.dnn.
DenseNet
(name, config, in_dim=None, save_path=None, input_networks=None, num_classes=None, activation=ReLU(), pred_activation=None, optim_spec={'lr': 0.001, 'name': 'Adam'}, lr_scheduler=None, early_stopping=None, early_stopping_patience=None, early_stopping_metric='accuracy', criter_spec=CrossEntropyLoss(), device='cuda:0')¶ Bases:
vulcanai.models.basenetwork.BaseNetwork
Subclass of BaseNetwork defining a DenseNet.
- Parameters:
- name : str
- The name of the network. Used when saving the file.
- config : dict
- The configuration of the network module, as a dict.
- in_dim : tuple
- The input dimensions of the network. Not required to specify when the network has input_networks.
- save_path : str
- The name of the file to which you would like to save this network.
- input_networks : list of BaseNetwork
- A network object provided as input.
- num_classes : int or None
- The number of classes to predict.
- activation : torch.nn.Module
- The desired activation function for use in the network.
- pred_activation : torch.nn.Module
- The desired activation function for use in the prediction layer.
- optim_spec : dict
- A dictionary of parameters for the desired optimizer.
- lr_scheduler : torch.optim.lr_scheduler
- A callable torch.optim.lr_scheduler
- early_stopping : str or None
- So far just ‘best_validation_error’ is implemented.
- early_stopping_patience: integer
- Number of validation iterations of decreasing loss (note -not necessarily every epoch! before early stopping is applied.
- early_stopping_metric: string
- Either “loss” or “accuracy” are implemented.
- criter_spec : dict
- criterion specification with name and all its parameters.
- Returns:
- network : DenseNet
- A network of type BaseNetwork.
-
__init__
(name, config, in_dim=None, save_path=None, input_networks=None, num_classes=None, activation=ReLU(), pred_activation=None, optim_spec={'lr': 0.001, 'name': 'Adam'}, lr_scheduler=None, early_stopping=None, early_stopping_patience=None, early_stopping_metric='accuracy', criter_spec=CrossEntropyLoss(), device='cuda:0')¶ Define the DenseNet object.
vulcanai.models.ensemble module¶
Contains all ensemble models.
-
class
vulcanai.models.ensemble.
SnapshotNet
(name, template_network, n_snapshots=3)¶ Bases:
vulcanai.models.basenetwork.BaseNetwork
Initialize snapshot ensemble given a template network.
A wrapper class for any Network inheriting from BaseNetwork to train the template network using Snapshot Ensembling.
- Parameters:
- name : str
- String of snapshot ensemble name.
- template_network : BaseNetwork
- Network object which you want to ensemble.
- n_snapshots : int
- Number of snapshots in ensemble.
- Returns:
- network : SnapshotNet
-
__init__
(name, template_network, n_snapshots=3)¶ Use Network to build model snapshots.
-
fit
(train_loader, val_loader, epochs, retain_graph=None, valid_interv=4, plot=False)¶ Train each model for T/M epochs and controls network learning rate.
Collects each model in a class variable self.network
- Parameters:
- train_loader : DataLoader
- Input data and targets to train against
- val_loader : DataLoader
- Input data and targets to validate against
- epochs : int
- Total number of epochs (evenly distributed between snapshots)
- Returns:
- None
-
forward
(inputs, **kwargs)¶ Snapshot forward function.
Collect outputs of all internal networks and average outputs.
- Parameters:
- inputs : torch.Tensor
- Input tensor to pass through self.
- Returns:
- output : torch.Tensor
-
save_model
(save_path=None)¶ Save all ensembled network in a folder with ensemble name.
- Parameters:
- save_path : str
- The folder path to save models in.
- Returns:
- None
vulcanai.models.layers module¶
Define the ConvUnit and DenseUnit.
-
class
vulcanai.models.layers.
BaseUnit
(weight_init=None, bias_init=None, norm=None, dropout=None)¶ Bases:
torch.nn.modules.container.Sequential
The base class for all layers.
- Parameters:
- weight_init : torch.nn.init
- Torch initialization function for weights.
- bias_init : int or float
- A constant int or float to initialize biases with.
- norm : str
- ‘batch’ for batch norm of ‘instance’ for instance norm.
- dropout : float between 0-1
- The probability of dropping out a feature during training.
- Returns:
- dense_unit : torch.nn.Sequential
- A single fully connected layer.
-
__init__
(weight_init=None, bias_init=None, norm=None, dropout=None)¶ Initialize a base unit.
-
class
vulcanai.models.layers.
ConvUnit
(conv_dim, in_channels, out_channels, kernel_size, weight_init=None, bias_init=None, stride=1, padding=0, norm=None, activation=None, pool_size=None, dropout=None)¶ Bases:
vulcanai.models.layers.BaseUnit
Define the ConvUnit object.
- Parameters:
- conv_dim : int
- 1, 2, or 3 representing spatial dimensional inputs.
- in_channels : int
- The number of incoming channels.
- out_channels : int
- The number of convolution kernels for this layer.
- kernel_size : int or tuple
- The size of the 1, 2, or 3 dimensional convolution kernel.
- weight_init : torch.nn.init
- Torch initialization function.
- bias_init : int or float
- A constant int or float to initialize biases with.
- stride : int or tuple
- The stride of the 1, 2, or 3 dimensional convolution kernel.
- padding : int
- Number of zero-padding on both sides per dimension.
- norm : str
- ‘batch’ for batch norm of ‘instance’ for instance norm.
- activation : torch.nn.Module
- An activation function to apply after Linear unit.
- pool_size : int
- Max pooling by a factor of pool_size in each dimension.
- dropout : float between 0-1
- The probability of dropping out a feature during training.
- Returns:
- conv_unit : torch.nn.Sequential
- A single convolution layer.
-
__init__
(conv_dim, in_channels, out_channels, kernel_size, weight_init=None, bias_init=None, stride=1, padding=0, norm=None, activation=None, pool_size=None, dropout=None)¶ Initialize a single ConvUnit (i.e. a conv layer).
-
get_conv_output_size
()¶ Calculate the size of the flattened features after conv.
-
class
vulcanai.models.layers.
DenseUnit
(in_features, out_features, weight_init=None, bias_init=None, norm=None, activation=None, dropout=None)¶ Bases:
vulcanai.models.layers.BaseUnit
Define the DenseUnit object.
- Parameters:
- in_features : int
- The incoming feature size of a sample.
- out_features : int
- The number of hidden Linear units for this layer.
- weight_init : torch.nn.init
- Torch initialization function.
- bias_init : int or float
- A constant int or float to initialize biases with.
- norm : str
- ‘batch’ for batch norm of ‘instance’ for instance norm.
- activation : torch.nn.Module
- An activation function to apply after Linear unit.
- dropout : float between 0-1
- The probability of dropping out a feature during training.
- Returns:
- dense_unit : torch.nn.Sequential
- A single fully connected layer.
-
__init__
(in_features, out_features, weight_init=None, bias_init=None, norm=None, activation=None, dropout=None)¶ Initialize a single DenseUnit (i.e. a dense layer).
-
class
vulcanai.models.layers.
FlattenUnit
¶ Bases:
vulcanai.models.layers.BaseUnit
Layer to flatten the input.
- Returns:
- flatten_unit : torch.Sequential
- A flatten layer.
-
__init__
()¶ Initialize flatten layer.
-
forward
(x)¶ Maintain batch size but flatten all remaining dimensions.
vulcanai.models.metrics module¶
Defines the network test suite.
-
class
vulcanai.models.metrics.
Metrics
¶ Bases:
object
A class to calculate all metrics for a BaseNetwork.
Responsible for the test suite.
-
__init__
()¶ Initialize the metrics class for a BaseNetwork.
-
static
bootfold_p_estimate
(network, data_loader, n_samples, k, epochs, index_to_iter, ls_feat_vals, retain_graph=None, valid_interv=4, plot=False, save_path=None, **kwargs)¶ Performs bootfold - estimation to identify whether training model provides statistically significant difference in predicting various values for a given feature when predicting outcome.
- Parameters:
- network : BaseNetwork
- Network descendant of BaseNetwork.
- data_loader : torch.utils.data.DataLoader
- The DataLoader object containing the totality of the data to use for k-fold cross validation.
- n_samples : int
- number of times to randomly sample w/ replacement the data_loader and perform boot_cv
- k : int
- The number of folds to split the training into.
- epochs : int
- The number of epochs to train the network per fold.
- index_to_iter : string
- Name of feature within data_loader who’s values will be iterated to assess difference
- ls_feat_vals : list
- List of values for feature provided in index_to_iter
- retain_graph : {None, boolean}
- Whether retain_graph will be true when .backwards is called.
- valid_interv : int
- Specifies after how many epochs validation should occur.
- plot : boolean
- Whether or not to plot all results in prompt and charts.
- save_path : str
- Where to save all figures and results.
- kwargs: dict of keyworded parameters
- Values passed to transform callable (function parameters)
- Returns:
- p_value : float
-
static
conduct_sensitivity_analysis
(network, data_loader, filename, features=None, cutoff=20)¶ Will conduct tests to figure out directionality of features by finding all the unique feature values present in the dataset and setting the feature for all examples to every unique value of that feature.
- network : BaseNetwork
- Network descendant of BaseNetwork.
- data_loader : DataLoader
- A DataLoader object which contains all the data
- filename: string
- The name of the file to save the test results to
- features: list
- Feature names ordered as the data in the data_loader
- cutoff: int
- Maximum number of unique feature values for a particular feature that will be tested
dataframe characterizing the number of examples classified in the different classes when altering the input to constant feature values
-
static
cross_validate
(network, data_loader, k, epochs, average_results=True, retain_graph=None, valid_interv=4, plot=False, save_path=None, transform_callable=None, stratified=False, strata_column='class_label', **kwargs)¶ Perform k-fold cross validation given a Network and DataLoader object.
- Parameters:
- network : BaseNetwork
- Network descendant of BaseNetwork.
- data_loader : torch.utils.data.DataLoader
- The DataLoader object containing the totality of the data to use for k-fold cross validation.
- k : int
- The number of folds to split the training into.
- epochs : int
- The number of epochs to train the network per fold.
- average_results : boolean
- Whether or not to return results from all folds or just an average.
- retain_graph : {None, boolean}
- Whether retain_graph will be true when .backwards is called.
- valid_interv : int
- Specifies after how many epochs validation should occur.
- plot : boolean
- Whether or not to plot all results in prompt and charts.
- save_path : str
- Where to save all figures and results.
- transform_callable: callable
- A torch function. e.g. torch.round()
- stratified: bool
- Whether to stratify the dataset. Default false.
- strata_column: string or int
- Either “class_label” or integer index of column. Default “class_label”
- kwargs: dict of keyworded parameters
- Values passed to transform callable (function parameters)
- Returns:
- results : dict
- If average_results is on, return dict of floats. If average_results is off, return dict of float lists.
-
static
get_accuracy
(targets, predictions)¶ Calculate the accuracy.
- Parameters:
- targets: numpy.ndarray of integers
- The target values.
- predictions: numpy.ndarray of integers
- The predicted values.
- Returns:
- accuracy: array of np.float32
- The accuracy.
-
static
get_auc
(targets, raw_predictions, num_classes, average=None, pos_label=1)¶ Calculate the AUC. Note: raw_predictions and num_classes are required.
- Parameters:
- targets: numpy.ndarray of integers
- The target values.
- raw_predictions: numpy.ndarray of floats
- The raw predicted values, not converted to classes.
- num_classes: int
- The number of classes that will be predicted.
- average: string
- [None, ‘binary’ (def), ‘micro’, ‘macro’, ‘samples’, ‘weighted’] This parameter is required for multiclass/multilabel targets. If None, the scores for each class are returned. Otherwise, this determines the type of averaging performed on the data. See Scikit learn.
- pos_label: int default 1
- The index value that is positive when in the binary case
- Returns:
- f1: np.float32 or array of np.float32
- The AUC.
-
static
get_confusion_matrix_values
(targets, predictions)¶ Calculate the tp, tn, fp, fn values given targets and predictions.
- Parameters:
- targets: numpy.ndarray of integers
- The target values.
- predictions: numpy.ndarray of integers
- The predicted values.
- Returns:
- tp, tn, fp, fn: array of np.float32 with classes in sorted order
- The true positive/negative, false positive/negative values.
-
static
get_dice
(targets, predictions, average=None, pos_label=1)¶ Calculate the dice metric.
- Parameters:
- targets: numpy.ndarray of integers
- The target values.
- predictions: numpy.ndarray of integers
- The predicted values.
- average: string
- [None, ‘binary’ (def), ‘micro’, ‘macro’, ‘samples’, ‘weighted’] Only None, ‘binary’, and ‘macro’ currently implemented. This parameter is required for multiclass/multilabel targets. If None, the scores for each class are returned. Otherwise, this determines the type of averaging performed on the data. See Scikit learn.
- pos_label: int
- 0 or 1. Only used in the binary case to indicate which class label will be used to provide the output for average=binary.
- Returns:
- dice: np.float32 or array of np.float32
- The dice metric.
-
static
get_f1
(targets, predictions, average=None, pos_label=1)¶ Calculate the f1 score.
- Parameters:
- targets: numpy.ndarray of integers
- The target values
- predictions: numpy.ndarray of integers
- The predicted values
- average: string
- [None, ‘binary’ (def), ‘micro’, ‘macro’, ‘samples’, ‘weighted’] This parameter is required for multiclass/multilabel targets. If None, the scores for each class are returned. Otherwise, this determines the type of averaging performed on the data. See Scikit learn.
- pos_label: int default 1:
- The index value that is positive when in the binary case
- Returns:
- f1: np.float32 or array of np.float32
- The f1 score.
-
static
get_mse
(targets, raw_predictions)¶ Calculate the negative MSE.
Note: raw_predictions and num_classes are required. Negative values are returned so the value can be optimized.
- Parameters:
- targets: numpy.ndarray of integers
- The target values.
- raw_predictions: numpy.ndarray of floats
- The raw predicted values, not converted to classes.
- Returns:
- results: float
- The MSE value
-
static
get_npv
(targets, predictions, average=None, pos_label=1)¶ Calculate the negative predictive value.
- Parameters:
- targets: numpy.ndarray of integers
- The target values.
- predictions: numpy.ndarray of integers
- The predicted values.
- average: string
- [None, ‘binary’ (def), ‘micro’, ‘macro’, ‘samples’, ‘weighted’] Only None, ‘binary’, and ‘macro’ currently implemented. This parameter is required for multiclass/multilabel targets. If None, the scores for each class are returned. Otherwise, this determines the type of averaging performed on the data. See Scikit learn.
- pos_label: int
- 0 or 1. Only used in the binary case to indicate which class label will be used to provide the output for average=binary.
- Returns:
- npv: np.float32 or array of np.float32
- The negative predictive value
-
static
get_ppv
(targets, predictions, average=None, pos_label=1)¶ Calculate the positive predictive value.
- Parameters:
- targets: numpy.ndarray of integers
- The target values.
- predictions: numpy.ndarray of integers
- The predicted values.
- average: string
- [None, ‘binary’ (def), ‘micro’, ‘macro’, ‘samples’, ‘weighted’] Only None, ‘binary’, and ‘macro’ currently implemented. This parameter is required for multiclass/multilabel targets. If None, the scores for each class are returned. Otherwise, this determines the type of averaging performed on the data. See Scikit learn.
- pos_label: int
- 0 or 1. Only used in the binary case to indicate which class label will be used to provide the output for average=binary.
- Returns:
- ppv: float32 or array of np.float32
- The positive predictive value.
-
static
get_score
(targets, predictions, metrics='accuracy', average=None, class_converted=False)¶ Calculate the provided metrics given some targets and predictions.
- Parameters:
- targets: numpy.ndarray of integers
- The target values
- predictions: numpy.ndarray of integers or numpy.ndarray of floats
- The predicted values
- metrics: list of strings
- The strings definition the “get_”… functions to call
- average: string,
- [None, ‘binary’ (default), ‘micro’, ‘macro’, ‘samples’, ‘weighted’] This parameter is required for multiclass/multilabel targets. If None, the scores for each class are returned. Otherwise, this determines the type of averaging performed on the data. See scikit learn documentation for each metric.
- class_converted: binary. default False
- True: If raw_predictions have already been converted using transform_outputs False: If raw_predictions are used
- Returns:
- metrics: dict
- Values returned by the metric functions.
-
static
get_sensitivity
(targets, predictions, average=None, pos_label=1)¶ Calculate the sensitivity.
Also referred to as recall, or the true positive rate.
- Parameters:
- targets: numpy.ndarray of integers
- The target values.
- predictions: numpy.ndarray of integers
- The predicted values.
- average: string
- [None, ‘binary’ (def), ‘micro’, ‘macro’, ‘samples’, ‘weighted’] This parameter is required for multiclass/multilabel targets. If None, the scores for each class are returned. Otherwise, this determines the type of averaging performed on the data. See Scikit learn.
- pos_label: int
- 0 or 1. Only used in the binary case to indicate which class label will be used to provide the output for average=binary.
- Returns:
- sensitivity: np.float32 or array of np.float32
- The sensitivity.
-
static
get_specificity
(targets, predictions, average=None, pos_label=1)¶ Calculate the specificity.
- Parameters:
- targets: numpy.ndarray of integers
- The target values.
- predictions: numpy.ndarray of integers
- The predicted values.
- average: string
- [None, ‘binary’ (def), ‘micro’, ‘macro’, ‘samples’, ‘weighted’] This parameter is required for multiclass/multilabel targets. If None, the scores for each class are returned. Otherwise, this determines the type of averaging performed on the data. See Scikit learn.
- pos_label: int
- 0 or 1. Only used in the binary case to indicate which class label will be used to provide the output for average=binary.
- Returns:
- specificity: np.float32 or array of np.float32
- The specificity.
-
static
run_test
(network, data_loader, plot=False, save_path=None, pos_label=1, transform_callable=None, **kwargs)¶ Will conduct the test suite to determine network strength.
Calls either _run_test_single_continuous or _run_test_multi depending on the number of classes. _run_test_multi only works with raw one-hot encoded output values. Note that multi class multi outputs are not supported: values will either be converted to class values from one-hot encoding or be a single continuous value. However, values can be transformed after the forward pass using transform_callable.
- Parameters:
- network: nn.Module
- The network
- data_loader : DataLoader
- A DataLoader object to run the test with.
- save_path : string
- Folder to place images in.
- plot: bool
- Determine if graphs should be plotted in real time.
- pos_label: int
- The label that is positive in the binary case for macro calculations.
- transform_callable: callable
- A torch function. e.g. torch.round()
- kwargs: dict of keyworded parameters
- Values passed to transform callable (function parameters)
- Returns:
- results : dict
-
static
stratified_split
(dataset, k, strata_column='class_label')¶ Split data into k subsets evenly over the given strata_column Does not work for greater than 2-D data.
- Parameters:
- dataset : data.dataset
- The dataset to be split.
- k : int
- The number of folds to split the training into.
- strata_column: string or int
- Either “class_label” or integer index of column. Default “class_label”
- Returns:
- split_datasets : list A list of dataset objects split into k parts.
-
static
transform_outputs
(in_matrix)¶ Reformat output matrix.
If one-hot, truth matrix to be the classes in a 1D array.
Note: This does not handle multiple class prediction.
- Parameters:
- in_matrix : numpy.ndarray or torch.Tensor
- One-hot matrix of shape [batch, num_classes].
- Returns:
- class_list : numpy.ndarray of floats
- 1D class array.
-
vulcanai.models.utils module¶
Define utilities for all networks.
-
vulcanai.models.utils.
get_one_hot
(in_matrix)¶ Reformat truth matrix to same size as the output of the dense network.
- Parameters:
- in_matrix : numpy.ndarray
- The categorized 1D matrix
- Returns:
- one_hot : numpy.ndarray
- A one-hot matrix representing the categorized matrix
-
vulcanai.models.utils.
master_device_setter
(network, device=None)¶ Convert network and input_networks to specified device.
- Parameters:
- network : BaseNetwork
- network to be converted to the specified device.
- device : str or torch.device
- the desired device
-
vulcanai.models.utils.
network_summary
(network, input_size=None)¶ Returns the summary of shapes of all layers in the network :return: OrderedDict of shape of each layer in the network
-
vulcanai.models.utils.
pad
(tensor, target_shape)¶ Pad incoming tensor to the size of target_shape.
tensor must have same spatial dimenison as the target_shape. Useful for combining various conv dimension outputs and to implement ‘same’ padding for conv operations.
- Parameters:
- tensor : torch.Tensor
- Tensor to be padded
- target_shape : np.array
- Final padded tensor shape [*spatial_dimensions]
- Returns:
- tensor : torch.Tensor
- zero padded tensor with spatial dimension as target_shape
-
vulcanai.models.utils.
print_model_structure
(network)¶ Print the entire model structure.
-
vulcanai.models.utils.
round_list
(raw_list, decimals=4)¶ Return the same list with each item rounded off.
- Parameters:
- raw_list : float list
- float list to round.
- decimals : int
- How many decimal points to round to.
- Returns:
- rounded_list : float list
- The rounded list in the same shape as raw_list.
-
vulcanai.models.utils.
selu_bias_init_
(tensor, const=0.0)¶ SELU layer bias initialization function.
Function assigned to variable that will be called within _init_bias function to assign bias for selu.
- Parameters:
- tensor : torch.tensor
- Bias tensor to be adjusted
- const : float
- Constant value to be assigned to tensor.
- Returns:
- torch.tensor
- bias tensor with constant values.
-
vulcanai.models.utils.
selu_weight_init_
(tensor, mean=0.0)¶ SELU layer weight initialization function.
Function assigned to variable that will be called within _init_weights function to assign weights for selu.
- Parameters:
- tensor : torch.tensor
- Weight tensor to be adjusted
- mean : float
- Mean value for the normal distribution
- Returns:
- torch.tensor
- weight tensor with normal distribution
-
vulcanai.models.utils.
set_tensor_device
(data, device=None)¶ Convert list of data tensors to specified device.
- Parameters:
- data : torch.tensor or list
- data to be converted to the specified device.
- device : str or torch.device
- the desired device
- Returns:
- data : torch.tensor or list
- data converted to the specified device