BenchNIRS API

load

load.load_dataset(dataset, path, bandpass=None, order=4, tddr=False, baseline=(None, 0), roi_sides=False, downsample=10)

Load and filter one of the open access dataset.

Parameters:
  • dataset (string) – Dataset to load. 'herff_2014_nb' for n-back from Herff et al., 2014 (epoch interval: -5 to 44 seconds). 'shin_2018_nb' for n-back from Shin et al., 2018 (epoch interval: -2 to 40 seconds). 'shin_2018_wg' for word generation from Shin et al., 2018 (epoch interval: -2 to 10 seconds). 'shin_2016_ma' for mental arithmetic from Shin et al., 2016 (epoch interval: -2 to 10 seconds). 'bak_2019_me' for motor execution from Bak et al., 2019 (epoch interval: -2 to 10 seconds).

  • path (string) – Path of the directory of the dataset selected with the dataset parameter.

  • bandpass (list of floats | None) – Cutoff frequencies of the bandpass Butterworth filter (in Hz). Defaults to None for no filtering.

  • order (integer) – Order of the bandpass Butterworth filter.

  • tddr (boolean) – Whether to apply temporal derivative distribution repair.

  • baseline (None or tuple of length 2) – The time interval to apply baseline correction (in sec). If None do not apply it. If a tuple (a, b) the interval is between a and b (in seconds). If a is None the beginning of the data is used and if b is None then b is set to the end of the interval. If (None, None) all the time interval is used. Correction is applied by computing mean of the baseline period and subtracting it from the data. The baseline (a, b) includes both endpoints, i.e. all timepoints t such that a <= t <= b.

  • roi_sides (boolean) – Whether to average channels by hemisphere in the task related regions of interest.

  • downsample (float | None) – Downsample data with the specified frequency (in Hz). Defaults to 10. Ignored if None or higher than the dataset’s original sampling frequency.

Returns:

epochs – MNE epochs data with associated labels. Subject IDs are contained in the metadata property.

Return type:

MNE Epochs object

process

process.process_epochs(mne_epochs, tmax=None, tslide=None, sort=False, reject_criteria=None)

Perform processing on epochs including baseline cropping, bad epoch removal, label extraction and unit conversion.

Parameters:
  • mne_epochs (MNE Epochs object) – MNE epochs of filtered data with associated labels. Subject IDs are contained in the metadata property.

  • tmax (float | None) – End time of selection in seconds. Defaults to None to keep the initial end time.

  • tslide (float | None) – Size of the sliding window in seconds. Will crop the epochs if tmax is not a multiple of tslide. Defaults to None for no window sliding.

  • sort (boolean) – Whether to sort channels by type (all HbO, all HbR). Defaults to False for no sorting.

  • reject_criteria (list of floats | None) – List of the 2 peak-to-peak rejection thresholds for HbO and HbR channels respectively in uM. Defaults to None for no rejection.

Returns:

  • nirs (array of shape (n_epochs, n_channels, n_times)) – Processed NIRS data in uM.

  • labels (array of integer) – List of labels.

  • groups (array of integer) – List of subject ID matching the epochs.

process.extract_features(nirs, feature_list)

Perform feature extraction on NIRS data.

Parameters:
  • nirs (array of shape (n_epochs, n_channels, n_times)) – Processed NIRS data.

  • feature_list (list of strings) – List of features to extract. The list can include 'mean' for the mean along the time axis, 'std' for standard deviation along the time axis and 'slope' for the slope of the linear regression along the time axis, 'kurt' for the kurtosis along the time axis, 'ttp' for the time to peak (requires channels to have been sorted beforehand: all HbO, all HbR), 'peak' for the value of the peak (max value for HbO and min value for HbR, requires channels to have been sorted beforehand: all HbO, all HbR).

Returns:

nirs_features – Features extracted from NIRS data.

Return type:

array of shape (n_epochs, n_channels, n_features)

learn

learn.machine_learn(nirs, labels, groups, model, normalize=None, random_state=None, output_folder='./outputs')

Perform nested k-fold cross-validation for standard machine learning models producing metrics and confusion matrices. The models include linear discriminant analysis (LDA), support vector classifier (SVC) with grid search for the regularization parameter (inner cross-validation), and k-nearest neighbors (kNN) with grid search for the number of neighbors (inner cross-validation).

Parameters:
  • nirs (array of shape (n_epochs, n_channels, n_times)) – Processed NIRS data.

  • labels (array of integers) – List of labels matching the NIRS data.

  • groups (array of integers | None) – List of subject ID matching the epochs to perfrom a group k-fold cross-validation. If None, performs a stratified k-fold cross-validation instead.

  • model (string) – Standard machine learning to use. Either 'lda' for a linear discriminant analysis, 'svc' for a linear support vector classifier or 'knn' for a k-nearest neighbors classifier.

  • normalize (tuple of integers | None) – Axes on which to normalize data before feeding to the model with min-max scaling based on the train set for each iteration of the outer cross-validation. For example (0, 2) to normalize across epochs and time. Defaults to None for no normalization.

  • random_state (integer | None) – Controls the shuffling applied to data. Pass an integer for reproducible output across multiple function calls. Defaults to None for not setting the seed.

  • output_folder (string) – Path to the directory into which the figures will be saved. Defaults to './outputs'.

Returns:

  • accuracies (array of floats) – List of accuracies on the test sets (one for each iteration of the outer cross-validation).

  • all_hps (list of floats | list of None) – List of regularization parameters for the SVC or a list of None for the LDA (one for each iteration of the outer cross-validation).

  • additional_metrics (list of tuples) – List of tuples of metrics composed of (precision, recall, F1 score) on the outer cross-validation (one tuple for each iteration of the outer cross-validation). This uses the precision_recall_fscore_support function from scikit-learn with average='weighted', y_true and y_pred being the true and the predictions on the specific iteration of the outer cross-validation.

learn.deep_learn(nirs, labels, groups, model_class, normalize=None, batch_sizes=[4, 8, 16, 32, 64], lrs=[1e-05, 0.0001, 0.001, 0.01, 0.1], max_epoch=100, random_state=None, output_folder='./outputs')

Perform nested k-fold cross-validation for a deep learning model. Produces loss graph, accuracy graph and confusion matrice. This is made with early stopping (with a validation set of 20 %) once the model has been fine tuned on the inner loop of the nested k-fold cross-validation. The number of classes is deduced from the number of unique labels.

Parameters:
  • nirs (array of shape (n_epochs, n_channels, n_times)) – Processed NIRS data.

  • labels (array of integers) – List of labels matching the NIRS data.

  • groups (array of integers | None) – List of subject ID matching the epochs to perfrom a group k-fold cross-validation. If None, performs a stratified k-fold cross-validation instead.

  • model_class (string | PyTorch nn.Module class) – The PyTorch model class to use. If a string, can be either 'ann', 'cnn' or 'lstm'. If a PyTorch nn.Module class, the __init__() method must accept the number of classes as a parameter, and this needs to be the number of output neurons.

  • normalize (tuple of integers | None) – Axes on which to normalize data before feeding to the model with min-max scaling based on the train set for each iteration of the outer cross-validation. For example (0, 2) to normalize across epochs and time. Defaults to None for no normalization.

  • batch_sizes (list of integers) – List of batch sizes to test for fine-tuning.

  • lrs (list of floats) – List of learning rates to test for fine-tuning.

  • max_epoch (integer) – Maximum number of epochs possible for training. Defaults to 100.

  • random_state (integer | None) – Controls the shuffling applied to data and random model initialization. Pass an integer for reproducible output across multiple function calls. Defaults to None for not setting the seed.

  • output_folder (string) – Path to the directory into which the figures will be saved. Defaults to './outputs'.

Returns:

  • accuracies (array of floats) – List of accuracies on the test sets (one for each iteration of the outer cross-validation).

  • all_hps (list of tuples) – List of best hyperparameters (one tuple for each iteration of the outer cross-validation). Each tuple will be (batch size, learning rate).

  • additional_metrics (list of tuples) – List of tuples of metrics composed of (precision, recall, F1 score) on the outer cross-validation (one tuple for each iteration of the outer cross-validation). This uses the precision_recall_fscore_support function from scikit-learn with average='weighted', y_true and y_pred being the true and the predictions on the specific iteration of the outer cross-validation.

viz

viz.epochs_viz(mne_epochs, reject_criteria=None)

Perform processing and visualization on epochs. Processing includes baseline cropping and bad epoch removal.

Parameters:
  • mne_epochs (MNE Epochs object) – MNE epochs of filtered data with associated labels. Subject IDs are contained in the metadata property.

  • reject_criteria (list of floats | None) – List of the 2 peak-to-peak rejection thresholds for HbO and HbR channels respectively in uM. Defaults to None for no rejection.