ml4fmri 1.0.4

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"

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

• "FBNetGen" (Time Series + FNC) Connectivity estimator, fuses it with FNC to do classification. Paper Code and bib item

FNC Models

• "LR" (FNC)
  Logistic regression, wired for FNC 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