mbfmri.models

General - Cross-validation

class mbfmri.models.mvpa_general.MVPA_Base(voxel_mask=None, **kwargs)

Bases: object

reset(**kwargs)
fit(X, y, **kwargs)
predict(X, **kwargs)
class mbfmri.models.mvpa_general.MVPA_CV(X_dict, y_dict, model, model_param_dict={}, method='5-fold', n_cv_repeat=1, cv_save=True, cv_save_path='.', fit_reporter=None, post_reporter=None)

Bases: object

MVPA_CV class runs cross-validation experiments for given X, y and a regression model. To allow subjec-wise cross-validation, leave-n-subject-out, X and y data are required to be in dictionary, which a subject’s data can be indexed by its ID. The cross-validation itself can be repeated, and contain the data involved including data used for training, validating, model weights fitted, and additional report values the model offers. (an example of report values is internal cross-validation errors from fitting ElasticNet) The data obtained from fitting models then post-processed by report functions in Reporter. Making a brain activation map from interpreting models is also included in these report functions. Please refer to mbfmri.models.elasticnet and mb.models.tf_mlp for detail.

Parameters

  • X_dict (dict) – Dictionary of multi-voxel signals indexed by the subject ID. X_dict[{subject_id}] = np.array(time, voxel_num)

  • y_dict (dict) – Dictionary of latent process indexed by the subject ID. y_dict[{subject_id}] = np.array(time,)

  • model (MVPA_Base) – MVPA model implemented uppon MVPA_Base interface. ElasticNet, MLP and CNN are available. Please refer to the corresponding documentation.

  • model_param_dict (dict, default={}) – Dictionary for keywarded arguments, which would be required in configuring models if applicable. (It is not used in models offered by this package.)

  • method (str, default=’5-fold’) – name of method for cross-validation “{n}-fold” : n will be parsed as integer and n cross-validation will be conducted. “{n}-lnso” : n will be parsed as integer and leave-n-subject-out will be conducted.

  • n_cv_repaet (int, default=1) – Number of repetition of running cross-validation Bigger the value, more time for computation and more stability. (recommend to use smaller than 5 or it will need much time to finish.)

  • cv_save (boolean, default=True) – Indicate whether save results or not

  • cv_save_path (str or pathlib.PosixPath, default=’.’) – Path for saving results.

  • fit_reporter (utils.report.FitReporter) – Reporting object which will make reports for every fold. Metrics like MSE or R can be done by FitReporter. Please refer to the documentation of report module.

  • post_reporter (utils.report.PostReporter) – Reporting object which will make reports after all folds are done. Results like brain activation map, or goodness-of-fit plot can be generated by PostReporter. Please refer to the documentation of report module.

run(**kwargs)

Run MVPA cross-validation experiment (Fitting & Interpreting).

Models

ElasticNet

class mbfmri.models.elasticnet.MVPA_ElasticNet(alpha=0.001, n_sample=30000, max_lambda=10, min_lambda_ratio=0.0001, lambda_search_num=100, n_jobs=16, n_splits=5, logistic=False, **kwargs)

Bases: mbfmri.models.mvpa_general.MVPA_Base

MVPA_ElasticNet is an MVPA model implementation of ElasticNet, wrapping ElasticNet from “glmnet” python package. Please refer to (https://github.com/civisanalytics/python-glmnet).

ElasticNet adopts a mixed L1 and L2 norm as a penalty term additional to Mean Squerred Error (MSE) in regression.

  • L1 norm and L2 norm is mixed as alpha * L1 + (1-alpha)/2 * L2

  • Total penalalty is modulated with shrinkage parameter : [alpha * L1 + (1-alpha)/2 * L2] * lambda

Shrinkage parameter is searched through lambda search space, lambda_path, and will be selected by comparing N-fold cross-validation MSE. lambda_path is determined by log-linearly slicing lambda_search_num times which exponentially decaying from max_lambda to max_lambda * min_lambda_ratio

The model interpretation, which means extracting the weight value for each voxel, is done by reading coefficient values of the linear layer.

Also, additional intermediate results are reported by report attribute. The below data will be used for reporting and plotting the results.

  • ‘cv_mean_score’ : mean CV MSE of each CV in lambda search space

  • ‘coef_path’ : coefficient values of each CV in lambda search space

  • ‘cv_standard_error’ : SE of CV MSE of each CV in lambda search space

  • ‘lambda_best’ : best lambda valeu

  • ‘lambda_path’ : lambda search space

Parameters

  • alpha (float, default=0.001) – Value between 0 and 1, indicating the mixing parameter in ElasticNet. penalty = [alpha * L1 + (1-alpha)/2 * L2] * lambda

  • n_sample (int, default=30000) – Max number of samples used in a single fitting. If the number of data is bigger than n_sample, sampling will be done for each model fitting. This is for preventing memory overload.

  • max_lambda (float, default=10) – Maximum value of lambda in lambda search space. The lambda search space is used when searching the best lambda value.

  • min_lambda_ratio (float, default=1e-4) – Ratio of minimum lambda value to maximum value. With this ratio, a log-linearly scaled lambda space will be created.

  • lambda_search_num (int, default=100) – Number of points in lambda search space. Bigger the number, finer will the lambda searching be.

  • n_jobs (int, default=16) – Number of cores used in fitting ElasticNet

  • n_splits (int, default=5) – Number of fold used in inner cross-validation, which aims to find the best lambda value.

  • logistic (bool, default=False) – Indicate if logistic regression is required. If True, LogitNet will be used instead, which optimizes logistic regression with the same penalties.

reset(**kwargs)
fit(X, y, **kwargs)
predict(X, **kwargs)
get_weights()
report(**kwargs)

Multi-layer Perceptron

class mbfmri.models.tf_mlp.MVPA_MLP(input_shape, layer_dims=[1024, 1024], activation='sigmoid', activation_output=None, use_bias=True, dropout_rate=0.5, batch_norm=False, logistic=False, l1_regularize=0, l2_regularize=0, val_ratio=0.2, optimizer='adam', loss=None, learning_rate=0.001, n_batch=64, n_epoch=50, n_min_epoch=5, n_patience=10, n_sample=30000, train_verbosity=0, model_save_path=None, explainer=None, **kwargs)

Bases: mbfmri.models.tf_base.MVPA_TF

MVPA_MLP is an MVPA model implementation of Multi-layer Perceptron (MLP). The model is implemented upon Tensorflow Keras (>= 2.4.0).

Parameters

  • input_shape (int or [int]) – Dimension of input data, which will be fed as X. It should be same as the number of voxel feature.

  • layer_dims (list of int, default=[1024, 1024]) – List of integer specifying the dimensions of each hidden layer. Fully-connected layers will be stacked with the sizes indicated by layer_dims. The last layer, layer_dims[-1] –> 1, will be added.

  • activation (str, default=”linear”) – Name of activation function which will be applied to the output of hidden layers.

  • activation_output (str, default=None) – Name of activation function for the final output. If None (default), it will be automatically determined as “linear” for linear regression and “sigmoid” for logistic regression.

  • use_bias (bool, default=True) – Indicate if bias is required. If True, bias will be used in layers, otherwise bias term will not be considered.

  • dropout_rate (float, default=0.5) – Rate of drop out, which will be applied after the hidden layers.

  • batch_norm (bool, default=False) – Indicate if batch normalization (BN) is applied. If True, BN will be done after each layer before the dropout layer.

  • logistic (bool, default=False) – Indicate if logistic regression is required. If True, the input should be binary and binary classification model will be trained.

  • l1_regularize (float, default=0) – Value for L1 penalty of all the weights in the model.

  • l2_regularize (float, default=0) – Value for L2 penalty of all the weights in the model.

  • val_ratio (float, default=0.2) – Rate for inner cross-validation, which will be used to split input data to (train[1-val_ratio], valid[val_ratio]). The validation dataset will be used for determining early stopping.

  • optimizer (str, default=”adam”) – Name of optimizer used for fitting model. The default optimizer is Adam. (https://arxiv.org/abs/1412.6980) Please refer to Keras optimizer api to use another. (https://www.tensorflow.org/api_docs/python/tf/keras/optimizers)

  • loss (str, default=None,) – Name of objective function to minimize in training. If None (default), it will be automatically determined as “mse” (mean squared error) for linear regression and “bce” (binary cross entropy) for logistic regression. Please refer to Keras loss api to use another. (https://www.tensorflow.org/api_docs/python/tf/keras/losses)

  • learning_rate (float, default=0.001) – Tensor, floating point value, or a schedule that is a tf.keras.optimizers.schedules.LearningRateSchedule, or a callable that takes no arguments and returns the actual value to use, The learning rate. Defaults to 0.001. Please refer to Keras optimizer api to use another. (https://www.tensorflow.org/api_docs/python/tf/keras/optimizers)

  • n_batch (int, default=64) – Number of samples per gradient update.

  • n_epoch (int, default=50) – Number of epochs to train the model. An epoch is an iteration over the entire x and y data provided. Note that in conjunction with initial_epoch, epochs is to be understood as “final epoch”. The model is not trained for a number of iterations given by epochs, but merely until the epoch of index epochs is reached.

  • n_min_epoch (int, default=50) – Number of minimum epochs to train the model before applying early stopping.

  • n_patience (int, default=10) – Number of epochs with no improvement after which training will be stopped. Please refer to https://keras.io/api/callbacks/early_stopping/

  • n_sample (int, default=30000) – Max number of samples used in a single fitting. If the number of data is bigger than n_samples, sampling will be done for each model fitting. This is for preventing memory overload.

  • train_verbosity (int, default=0) – Level of verbosity for model fitting. If it is 1, the reports from keras model fitting will be printed.

  • model_save_path (str or pathlib.PosixPath, default=None) – Path for saving best models. If not given, trained models will not be saved.

  • explainer (utils.explain.Explainer) – Explainer object for interpeting the trained models. Please refer to the explainer module documentation.

reset(**kwargs)

interpreting DNN

Convolutional Neural Network

class mbfmri.models.tf_cnn.MVPA_CNN(input_shape, layer_dims=[8, 16, 32], kernel_size=[3, 3, 3], logit_layer_dim=256, activation='relu', activation_output=None, dropout_rate=0.2, batch_norm=True, logistic=False, l1_regularize=0, l2_regularize=0, val_ratio=0.2, optimizer='adam', loss=None, learning_rate=0.001, n_batch=64, n_epoch=50, n_min_epoch=5, n_patience=10, n_sample=30000, train_verbosity=0, model_save_path=None, explainer=None, **kwargs)

Bases: mbfmri.models.tf_base.MVPA_TF

MVPA_CNN is an MVPA model implementation of Covolutional Neural Network (CNN). The model is implemented upon Tensorflow Kerase (v.2.4.0).

Parameters

  • input_shape (tuple of int) – Dimension of input data, which will be fed as X.

  • layer_dims (list of int, default=[8, 16, 32]) – List of integer specifying the dimensions (channels) of each hidden layer. Convolutional layers will be stacked with the channel sizes indicated by layer_dims.

  • kernel_size (list of int, default=[3, 3, 3]) – List of integer specifying the kernel size of each convolutional layer.

  • logit_layer_dim (int, default=256) – Size of a Fully-connected layer, which will be added on convolutional layers. The last layer, logit_layer_dim –> 1, will be added for regression.

  • activation (str, default=”linear”) – Name of activation function which will be applied to the output of hidden layers.

  • activation_output (str, default=None) – Name of activation function for the final output. If None (default), it will be automatically determined as “linear” for linear regression and “sigmoid” for logistic regression.

  • use_bias (bool, default=True) – Indicate if bias is required. If True, bias will be used in layers, otherwise bias term will not be considered.

  • dropout_rate (float, default=0.5) – Rate of drop out, which will be applied after the last logit layers.

  • batch_norm (bool, default=False) – Indicate if batch normalization (BN) is applied. If True, BN will be done after each layer before the dropout layer.

  • logistic (bool, default=False) – Indicate if logistic regression is required. If True, the input should be binary and binary classification model will be trained.

  • l1_regularize (float, default=0) – Value for L1 penalty of all the weights in the model.

  • l2_regularize (float, default=0) – Value for L2 penalty of all the weights in the model.

  • val_ratio (float, default=0.2) – Rate for inner cross-validation, which will be used to split input data to (train[1-val_ratio], valid[val_ratio]). The validation dataset will be used for determining early stopping.

  • optimizer (str, default=”adam”) – Name of optimizer used for fitting model. The default optimizer is Adam. (https://arxiv.org/abs/1412.6980) Please refer to Keras optimizer api to use another. (https://www.tensorflow.org/api_docs/python/tf/keras/optimizers)

  • loss (str, default=None,) – Name of objective function to minimize in training. If None (default), it will be automatically determined as “mse” (mean squared error) for linear regression and “bce” (binary cross entropy) for logistic regression. Please refer to Keras loss api to use another. (https://www.tensorflow.org/api_docs/python/tf/keras/losses)

  • learning_rate (float, default=0.001) – Tensor, floating point value, or a schedule that is a tf.keras.optimizers.schedules.LearningRateSchedule, or a callable that takes no arguments and returns the actual value to use, The learning rate. Defaults to 0.001. Please refer to Keras optimizer api to use another. (https://www.tensorflow.org/api_docs/python/tf/keras/optimizers)

  • n_batch (int, default=64) – Number of samples per gradient update.

  • n_epoch (int, default=50) – Number of epochs to train the model. An epoch is an iteration over the entire x and y data provided. Note that in conjunction with initial_epoch, epochs is to be understood as “final epoch”. The model is not trained for a number of iterations given by epochs, but merely until the epoch of index epochs is reached.

  • n_min_epoch (int, default=50) – Number of minimum epochs to train the model before applying early stopping.

  • n_patience (int, default=10) – Number of epochs with no improvement after which training will be stopped. Please refer to https://keras.io/api/callbacks/early_stopping/

  • n_sample (int, default=30000) – Max number of samples used in a single fitting. If the number of data is bigger than n_samples, sampling will be done for each model fitting. This is for preventing memory overload.

  • train_verbosity (int, default=0) – Level of verbosity for model fitting. If it is 1, the reports from keras model fitting will be printed.

  • model_save_path (str or pathlib.PosixPath, default=None) – Path for saving best models. If not given, trained models will not be saved.

  • explainer (utils.explain.Explainer) – Explainer object for interpeting the trained models. Please refer to the explainer documentation.

reset(**kwargs)

interpreting DNN