Skip to content

Overview

One page per task: which nltools call to reach for, in what order, and what will bite you. The Tutorials are executed narratives you read start to finish; the Reference is the generated signature for every public symbol. These pages sit between the two, short and linked into both.

The three data classes

Everything in nltools flows through three objects. Each flattens a neuroimaging structure into a 2-D array so ordinary array operations work on it.

Class Holds You get one from
BrainData Images × in-mask voxels A NIfTI path, a list of paths, an array + mask, an .h5 file
DesignMatrix Timepoints × regressors A BIDS events .tsv, a confounds table, an array, a dict
Adjacency Matrices × node pairs BrainData.distance, a square matrix, a stack of them

Three flows cover most analyses:

  • Univariate. Load a run → build a design → fit → compute_contrasts → stack the per-subject maps → ttest → threshold. See Design matrices & GLM.
  • Multivariate. Load images → predict (decoding) or distance → Adjacency → similarity (RSA). See Prediction and Similarity & RSA.
  • Many subjects. Apply BrainData methods per subject, then concatenate the resulting maps for group analysis. See the GLM workflow.

Pages

Page Covers
Loading data & masks BrainData from files and URLs, masks, the resolution rule, HDF5, bundled datasets
Design matrices & GLM Events → regressors, confounds, drift, collinearity warnings, fit, contrasts, group tests
Prediction: encoding & decoding predict, cross-validation specs, ROI and searchlight scales, ridge encoding, ROC
Similarity & RSA Brain RDMs, model RDMs, Mantel tests, plot_stacked_adjacency, painting results back on the brain
Functional alignment Hyperalignment vs SRM vs local alignment, common models, transforming new subjects
Statistics & inference t-tests, permutation, bootstrap, FDR/Holm, tail, n_permute vs n_samples, n_jobs
Intersubject correlation isc, isfc, isps, group comparisons, array-based ISC
Plotting Which plot for which object, thresholds, interactive viewers, saving
Atlases & cluster reports Bundled parcellations, anatomical labels, parcel summaries, cluster tables

Kwarg conventions

  • method= picks an algorithm variant; metric= picks a distance or similarity measure; summary= picks a central tendency ('mean' or 'median'). They are never interchangeable.
  • spatial_scale= ('whole_brain', 'roi', 'searchlight') picks the scale an analysis runs at.
  • n_jobs= sets joblib workers and never changes a seeded result. device= picks CPU or GPU on the ridge paths (Ridge, BrainData.fit(ridge_device=), BrainData.bootstrap), the only ones with a GPU implementation; an explicit device='gpu' runs on the GPU or raises.
  • n_permute= counts permutations; n_samples= counts bootstrap draws.
  • random_state= makes any resampling reproducible.

The full manifest is in the architecture notes.