Optimal Battery

To construct a multi-task battery suitable for parcellating a specific brain structure (or ROI within a brain structure), we developed an algorithm that selects an optimal battery based on a large library of task activity patterns.

Load library

The task library is hosted on Zenodo (DOI: 10.5281/zenodo.18793343). The fetch_task_library function downloads and caches it locally.

The download fetches two files:

  • Data file (.dscalar.nii): Group-averaged fMRI activity patterns in CIFTI format (cortex in fs32k space, subcortical structures in MNI152NLin6Asym space)

  • Info file (.tsv): Metadata for each row in the data file, including: - task_code: unique task code - cond_code: condition code (some tasks have multiple conditions) - full_code: task_code + cond_code (used to identify conditions) - source: datasets used to compute the average activation pattern - total_subjects: number of subjects the activation pattern is based on

import MultiTaskBattery.battery as bat

data, info = bat.fetch_task_library(version='V1')

You can also filter by brain structure:

data, info = bat.fetch_task_library(version='V1', structures=['CEREBELLUM_LEFT', 'CEREBELLUM_RIGHT'])

The available structures in the V1 library are:

  • CORTEX_LEFT, CORTEX_RIGHT

  • ACCUMBENS_LEFT, ACCUMBENS_RIGHT

  • AMYGDALA_LEFT, AMYGDALA_RIGHT

  • BRAIN_STEM

  • CAUDATE_LEFT, CAUDATE_RIGHT

  • CEREBELLUM_LEFT, CEREBELLUM_RIGHT

  • DIENCEPHALON_VENTRAL_LEFT, DIENCEPHALON_VENTRAL_RIGHT

  • HIPPOCAMPUS_LEFT, HIPPOCAMPUS_RIGHT

  • PALLIDUM_LEFT, PALLIDUM_RIGHT

  • PUTAMEN_LEFT, PUTAMEN_RIGHT

  • THALAMUS_LEFT, THALAMUS_RIGHT

Evaluate a battery

Given a set of task conditions, evaluate_battery computes the Negative Inverse Trace (NIT) of the task-by-task covariance matrix. Higher NIT means the tasks produce more separable brain activation patterns (higher potential for brain mapping).

# Define a battery using full_code values from the info file
my_battery = ['tom_task', 'movie_romance', 'fingr_sequence',
              'nbckverb_2bcknrep', 'vissearch_small', 'rest_task',
              'vrbgen_generate', 'actobserv_knot']

nit = bat.evaluate_battery(data, info, my_battery)
print(f"NIT score: {nit:.4f}")

Find optimal batteries

get_top_batteries performs a random search over many task combinations to find batteries with the highest NIT scores.

# Search 100,000 random 8-task batteries, keep top 10
top = bat.get_top_batteries(data, info,
                            n_samples=100000,
                            battery_size=8,
                            n_top_batteries=10)
print(top)

You can also force certain tasks to always be included:

# Always include rest, search for best remaining 7 tasks
top = bat.get_top_batteries(data, info,
                            n_samples=100000,
                            battery_size=8,
                            forced_tasks=['rest_task'])

Load from local files

If you already have the library files downloaded, use load_library directly:

data, info = bat.load_library('path/to/data.dscalar.nii', 'path/to/info.tsv')