inference¶

Group-level reductions and cross-subject ops for BrainCollection.

Module-level functions that the BrainCollection facade delegates to. Reductions stream from path-backed inputs (Welford-style) and produce in-memory BrainData (or dicts of them); they never path-back their own output.

Methods:

Classes¶

Methods¶

align¶

align(bc: BrainCollection, *, method: str = 'procrustes', spatial_scale: str = 'searchlight', radius_mm: float = 10.0, roi_mask: nib.Nifti1Image | None = None, n_features: int | None = None, n_iter: int = 3, device: str = 'cpu', return_model: bool = False, n_jobs: int = -1, progress_bar: bool = False, cache: Literal['auto', True, False] = 'auto')

Functional alignment via LocalAlignment.

Materializes all subjects (algorithm constraint in v0.6.0). Returns a new BrainCollection of aligned data, or (BrainCollection, LocalAlignment) when return_model=True.

anova¶

anova(bc: BrainCollection, groups: str | list | np.ndarray) -> dict[str, BrainData | int]

One-way ANOVA across subjects.

groups is a metadata column name, a list, or an ndarray of length n_subjects. Returns {'F', 'p', 'df_between', 'df_within'}.

concat¶

concat(bc: BrainCollection) -> BrainData

Stack along axis 0 → BrainData of shape (n_total_obs, n_voxels).

Not streamable — the operation is materialization. 1D items are promoted to (1, n_voxels) before concatenation.

isc¶

isc(bc: BrainCollection, *, method: str = 'loo', roi_mask: nib.Nifti1Image | Path | str | None = None, summary: str = 'median') -> dict

Inter-subject correlation across the time dimension.

method=‘loo’ uses the leave-one-out template approach (each subject correlated with the average of the others). method=‘pairwise’ computes all subject pairs. Both materialize all subjects in v0.6.0; the streaming rewrite is deferred to a later release.

Passing roi_mask restricts the computation to that ROI; the returned maps carry the ROI mask rather than the collection’s whole-brain mask.

Returns {'isc', 'per_subject'} for loo or {'isc', 'pairs'} for pairwise.

isc_test¶

isc_test(bc: BrainCollection, *, method: str = 'loo', roi_mask: nib.Nifti1Image | Path | str | None = None, n_samples: int = 5000, summary: str = 'median', tail: int | str = 2, random_state: int | None = None) -> dict

Bootstrap inference on ISC.

Resamples subjects with replacement, recomputes ISC each draw, and derives a per-voxel p-value from the null distribution centered at 0. tail: 2|‘two’ (two-tailed, default) or 1|‘one’ (one-tailed: ISC > 0).

Passing roi_mask restricts the computation to that ROI; the returned maps carry the ROI mask rather than the collection’s whole-brain mask.

max_¶

max_(bc: BrainCollection) -> BrainData

Per-voxel max across subjects. Streams.

mean¶

mean(bc: BrainCollection) -> BrainData

Mean across subjects (leading axis). Streams from path-backed input.

median¶

median(bc: BrainCollection) -> BrainData

Median across subjects. Materializes (not streaming-friendly).

min_¶

min_(bc: BrainCollection) -> BrainData

Per-voxel min across subjects. Streams.

permutation_test¶

permutation_test(bc: BrainCollection, *, n_permute: int = 5000, tail: int | str = 2, device: str = 'cpu', return_null: bool = False, n_jobs: int = -1, random_state: int | None = None, progress_bar: bool = False) -> dict

Sign-flipping permutation test across subjects (one-sample).

Per the streaming-algorithms table in docs/development/execution-model.md, sign-flipping needs all subjects in memory by design. Delegates to the engine’s one_sample_permutation_test (as isc_test already does), so device and n_jobs select the real execution backend.

permutation_test2¶

permutation_test2(bc: BrainCollection, other: BrainCollection, *, n_permute: int = 5000, tail: int | str = 2, device: str = 'cpu', return_null: bool = False, n_jobs: int = -1, random_state: int | None = None, progress_bar: bool = False) -> dict

Two-sample permutation test by random label shuffling.

Delegates to the engine’s two_sample_permutation_test, so device and n_jobs select the real execution backend. The result’s mean map is the engine’s mean_diff (group difference).

std¶

std(bc: BrainCollection) -> BrainData

Std across subjects. Streams via Welford; ddof=1.

sum_¶

sum_(bc: BrainCollection) -> BrainData

Sum across subjects. Streams.

ttest¶

ttest(bc: BrainCollection, *, popmean: float = 0.0, tail: int | str = 2) -> dict[str, BrainData]

One-sample t-test across subjects.

Returns {'mean', 't', 'z', 'p'} — same shape contract as BrainData.ttest. Streams from path-backed input via Welford. tail: 2|‘two’ (two-tailed, default) or 1|‘one’ (one-tailed: mean > popmean; negate the data for the other direction). The z map is derived from the reported p, so it matches the requested tail.

ttest2¶

ttest2(bc: BrainCollection, other: BrainCollection, *, equal_var: bool = True, tail: int | str = 2) -> dict[str, BrainData]

Two-sample t-test between two collections (subject-level).

tail: 2|‘two’ (two-tailed, default) or 1|‘one’ (one-tailed: bc > other; swap the operands for the other direction).

var¶

var(bc: BrainCollection) -> BrainData

Variance across subjects. Streams via Welford; ddof=1.