ml4fmri 1.0.7

Machine learning models for fMRI classification

ml4fmri

A one-line Python toolkit for fMRI classification that allows you to benchmark multiple deep learning models for fMRI analysis on your data with a single function call. While designed for fMRI time series, it can work with any temporal classification task.

Originally based on the codebase behind the NeuroImage paper "A simple but tough-to-beat baseline for fMRI time-series classification". This work was funded by the National Science Foundation grant 2112455, NIH grant R01MH123610, and in part by NIH grant R01MH129047.

Use example

You can install the package directly from PyPI:

pip install ml4fmri

Check out the 👉 Colab tutorial for a more detailed guide and ways to modify the default behavior.

# In Python, get fMRI time series DATA in shape (SAMPLES, TIME, FEATURES)
# and LABELS in shape (SAMPLES) (binary or multiclass)

from ml4fmri import cvbench  # runs CV experiments with implemented models on the given data

# Run cross-validation with all available models. See below for more info on available `models`
report = cvbench(DATA, LABELS, models='all', n_folds=5)

# Plot test AUC boxplots for all models
report.plot_scores()

# Save test and training dataframes as .csv, and metadata as .json
report.save()

# Access logs directly as variables
train_df = report.get_train_dataframe()
test_df  = report.get_test_dataframe()
meta     = report.get_meta()

# Inspect training curves
report.plot_training_curves()

Available Models

You can set models input in cvbench to:

• 'all' - (default for non-CPU) run all models,
• 'lite' (default for CPU) – use only faster models, better for quick tests
• 'ts' – run only time series models
• 'fnc' – run only FNC models; FNC data is derived from input time series
• '<model_name>' – run only the specified model (e.g. 'meanMLP'); see below for full model list
• ['<model_name_1>', '<model_name_2>'] – run only the listed models

Time Series Models

• "meanMLP" (Time Series)
  A simple MLP model for time series classification, surprisingly good for fMRi time series. Paper
  Code and bib item

• "LSTM" (Time Series)
  Standard LSTM recurrent network for sequence classification.
  Paper
  Code and bib item

• "meanLSTM" (Time Series)
  A variant of LSTM where outputs are mean-aggregated across time.
  Paper
  Code and bib item

• "Transformer" (Time Series)
  Vanilla transformer encoder for modeling temporal dependencies in fMRI time series.
  Paper
  Code and bib item

• "meanTransformer" (Time Series)
  Transformer with temporal mean pooling for classification.
  Paper
  Code and bib item

• "MILC" (Time Series)
  CNN+LSTM model for fMRI time series.
  Paper
  Code and bib item

• "BolT" (Time Series) Fused window Transformer for fMRI time series; slow but good, outperformed meanMLP on larger datasets. Paper Code and bib item

• "DICE" (Time Series) LSTM-based connectivity estimator and classifier, works with time series. Paper Code and bib item

• "Glacier" (Time Series) Transformer-based connectivity estimator and classifier, works with time series. Paper Code and bib item

FNC Models

• "LR" (FNC)
  Logistic regression, wired for FNC classification.
  Paper
  Code and bib item

• "FBNetGen" (Time Series + FNC) Estimates connectivity from time series, fuses it with FNC to do classification. Paper Code and bib item

• "BNT" (FNC) Transformer/GNN model for FNC classification. Paper Code and bib item

• "BrainNetCNN" (FNC) CNN classifier, designed for FNC-like matrices in mind. Paper Code and bib item