Battery module

evaluate_battery(library_data, library_info, battery_full_codes)

Evaluate a task battery by computing the negative inverse trace (NIT) of the task-by-task covariance matrix.

Parameters:

  • library_data – Task activation data (n_conditions, n_measurement_channels)

  • library_info – DataFrame with condition info (must have ‘full_code’ column)

  • battery_full_codes – List of task condition codes from the ‘full_code’ column in the info file (e.g., [‘task1_cond1’, ‘task2_cond2’])

Returns: NIT score (float) - higher values indicate more separable task patterns and more optimal battery

fetch_task_library(version='V1', atlas='multiatlasHCP', structures=None)

Fetch task activation library from Zenodo.

Parameters:

  • version – Library version (e.g., ‘V1’)

  • atlas – Atlas name (e.g., ‘multiatlasHCP’)

  • structures – List of CIFTI structure names to include. If None, loads all.

Returns:

  • library_data – ndarray (n_conditions, n_measurement_channels)

  • library_info – DataFrame with condition info

get_top_batteries(library_data, library_info, n_samples, battery_size=8, n_top_batteries=10, forced_tasks=None, verbose=True)

Random search over task combinations to find highest NIT.

Parameters:

  • library_data – Task activation data (n_conditions, n_measurement_channels)

  • library_info – DataFrame with condition info (must have ‘full_code’ column)

  • n_samples – Total number of random batteries to test

  • battery_size – Number of task conditions in each battery

  • n_top_batteries – Number of top batteries to keep

  • forced_tasks – List of task names to include in every battery

Returns: DataFrame with columns ‘rank’, ‘evaluation’, ‘battery’

load_library(data_path, info_path, structures=None)

Load task library_data from local files.

Parameters:

  • data_path – Path to library data file (.nii, .nii.gz, .dscalar.nii), must be shape (n_conditions, n_measurement_channels)

  • info_path – Path to library info file (.tsv) with ‘full_code’ column

  • structures – List of CIFTI structure names to include (e.g., [‘CIFTI_STRUCTURE_CORTEX_LEFT’, ‘CIFTI_STRUCTURE_CORTEX_RIGHT’]). If None, loads all data.

Returns:

  • library_data – ndarray (n_conditions, n_measurement_channels)

  • library_info – DataFrame with condition info