Result types¶

What the analysis methods hand back. These are read, not constructed: BrainData.predict returns a Predict, BrainData.bootstrap a BootstrapResult, a GLM contrast a ContrastResult, and the brain-space functions a BrainSpaceConfig.

Data classes for neuroimaging analysis.

BrainData (masked voxel data), Adjacency (similarity/distance matrices), DesignMatrix (regressors), the Roc analysis class, the Simulator/SimulateGrid data simulators, and the frozen result records those classes return (Predict, BootstrapResult, ContrastResult) plus the brain-space configuration record (BrainSpaceConfig).

Classes:

Name	Description
`Predict`	Frozen structural record for `BrainData.predict` decoding results.
`BootstrapResult`	Frozen record of one bootstrap statistic's estimate and uncertainty.
`ContrastResult`	Frozen record of the inferential outputs of one contrast.
`BrainSpaceConfig`	Immutable MNI template configuration.

Classes¶

Predict `dataclass` ¶

Predict(
    spatial_scale: str,
    scoring: Any = None,
    classes: ndarray | None = None,
    predictions: ndarray | None = None,
    cv_folds: ndarray | None = None,
    scores: ndarray | None = None,
    estimator: Any = None,
    weight_map: BrainData | None = None,
    roi_labels: ndarray | None = None,
    score_map: BrainData | None = None,
)

Frozen structural record for BrainData.predict decoding results.

spatial_scale is the discriminator: it decides which fields carry a value and which stay None. Construction validates that combination, so an empty or mixed-mode record cannot exist; the shapes within it are the producer's responsibility. Field bindings cannot be rebound, but the payloads they hold remain usable, and the record takes independent ownership of every array, brain map, and estimator it stores.

Brain-space outputs are BrainData objects, not raw arrays, so result.weight_map.plot() works directly (.data gives the array). Non-spatial fields are numpy.

Populated by spatial_scale. 'whole_brain': predictions, cv_folds, scores, estimator, weight_map. 'roi': scores, roi_labels, score_map, weight_map. 'searchlight': score_map. classes accompanies any classifier; scoring records the caller's scoring specification in every mode.

Why the all-data fit is the canonical map. The mean of per-fold coef_ vectors corresponds to no actual fitted estimator (each fold saw a different subset), and fits on overlapping training folds are not independent uncertainty samples. The record therefore exposes one coefficient map, from the estimator refitted on all observations after cross-validation: cross-validation gives the honest score, the refit gives the publishable map.

Attributes:

Name	Type	Description
`spatial_scale`	`str`	`'whole_brain'`, `'roi'`, or `'searchlight'`.
`scoring`	`str \| callable \| None`	The scoring specification the caller passed. `None` records that the estimator's own `score` method was used; it does not by itself name that method's metric.
`classes`	`ndarray \| None`	Classifier class labels, `(n_classes,)`. `None` for regression.
`predictions`	`ndarray \| None`	Out-of-fold predictions, one per row, `(n_samples,)` (whole-brain only).
`cv_folds`	`ndarray \| None`	Fold index per row, `(n_samples,)` (whole-brain only).
`scores`	`ndarray \| None`	Per-fold score — `(n_folds,)` for whole-brain, `(n_folds, n_rois)` for ROI.
`estimator`	`Any`	The all-data fitted sklearn estimator (whole-brain only); use it to `.predict()` on new data.
`weight_map`	`BrainData \| None`	Coefficients of the estimator refit on all data, `(n_voxels,)` or `(n_classes, n_voxels)` for multiclass — one map for regression and binary classification, one map per class in `classes` order for multiclass. For ROI, each parcel's coefficients are written into its voxels (NaN outside parcels); magnitudes are not comparable across parcels.
`roi_labels`	`ndarray \| None`	Atlas integer ids, `(n_rois,)`, in the order of the `scores` parcel axis (ROI only).
`score_map`	`BrainData \| None`	`(n_voxels,)` map of cross-validated scores — for ROI, every voxel of parcel i holds that parcel's mean fold score (NaN outside parcels); for searchlight, the sphere-centered mean fold score at each voxel.
`mean_score`	`float \| ndarray`	Mean of `scores` across folds, computed on demand — a float for whole-brain, `(n_rois,)` for ROI. Accessing it on a searchlight result raises `AttributeError`.
`std_score`	`float \| ndarray`	Standard deviation of `scores` across folds, in `mean_score`'s form and with the same searchlight rule.

Note

Encoding-model timeseries prediction (bd.predict(X=...)) returns a BrainData directly rather than a Predict — the natural container for a voxel timeseries.

Methods:

Name	Description
`asdict`	Convert to dictionary.
`available`	Return names of the fields this result carries (excludes private).

Attributes¶

mean_score `property` ¶

mean_score

Mean score across folds — a float for whole-brain, per parcel for ROI.

std_score `property` ¶

std_score

Score standard deviation across folds, in mean_score's form.

Methods:¶

asdict ¶

asdict(include_none: bool = False) -> dict

Convert to dictionary.

Parameters:

Name	Type	Description	Default
`include_none`	`bool`	If True, include every field that does not apply to this spatial scale, whose value is None. `spatial_scale` and `scoring` are always included. Private fields (starting with _) are always excluded.	`False`

Returns:

Type	Description
`dict`	Dictionary of field names to values.

available ¶

available() -> list

Return names of the fields this result carries (excludes private).

spatial_scale and scoring always count: a scoring of None records that the estimator's own score method was used, which is a value, not an absent field.

BootstrapResult `dataclass` ¶

BootstrapResult(
    estimate: Payload,
    standard_error: Payload,
    ci_lower: Payload,
    ci_upper: Payload,
    samples: ndarray | None = None,
)

Bases: Generic[Payload]

Frozen record of one bootstrap statistic's estimate and uncertainty.

The single result structure every supported bootstrap statistic returns. Its payload is whatever the producer works in: BrainData for the BrainData facade, Adjacency for the Adjacency facade. The four summary payloads share one data shape.

Field bindings cannot be rebound. The payloads stay usable, but the record takes independent ownership of each one, so mutating a returned payload never reaches the source object or a sibling payload.

The record deliberately exposes no replicate mean and no z, p, or tail output: those need a separately defined bootstrap hypothesis test. For a normal-approximation stand-in, users compute it themselves from estimate and standard_error.

Attributes:

Name	Type	Description
`estimate`	`Payload`	The statistic evaluated once on the original full sample — not the mean of the replicates.
`standard_error`	`Payload`	Elementwise standard deviation of the bootstrap replicates, with `ddof=1`.
`ci_lower`	`Payload`	Lower bound of the central percentile interval at the requested `confidence_level`.
`ci_upper`	`Payload`	Upper bound of that interval. The bounds are elementwise marginal: the nominal level applies separately to each voxel, feature, or test row, with no simultaneous-coverage claim.
`samples`	`ndarray \| None`	Every replicate, bootstrap axis first, when `return_samples=True`; `None` otherwise.

ContrastResult `dataclass` ¶

ContrastResult(
    effect: Payload,
    variance: Payload,
    standard_error: Payload,
    statistic: Payload,
    z_score: Payload,
    p_value: Payload,
    degrees_of_freedom: float | ndarray,
)

Bases: Generic[Payload]

Frozen record of the inferential outputs of one contrast.

The one result type inferential contrast methods return. Its payload is whatever the producer works in: float or np.ndarray for a Glm, BrainData for the BrainData facade.

Fields cannot be rebound. Array payloads stay mutable, but each result owns its arrays: they never alias the input contrast, a model's retained state, or another result.

Every statistic describes the directional hypothesis that effect is zero, so p_value is one-sided; negating the contrast tests the other direction.

Attributes:

Name	Type	Description
`effect`	`Payload`	The estimated linear combination of coefficients.
`variance`	`Payload`	The estimated variance of `effect`.
`standard_error`	`Payload`	`np.sqrt` of `variance`, with no absolute value or clipping, so it may be non-finite.
`statistic`	`Payload`	The signed t-statistic for the null hypothesis that `effect` is zero.
`z_score`	`Payload`	The signed normal-score equivalent of the directional p-value.
`p_value`	`Payload`	The one-sided upper-tail p-value.
`degrees_of_freedom`	`float \| ndarray`	The residual degrees of freedom used for inference.

BrainSpaceConfig `dataclass` ¶

BrainSpaceConfig(
    template: TemplateName = "default",
    resolution: Resolution = 2,
)

Immutable MNI template configuration.

Attributes:

Name	Type	Description
`template`	`str`	Template variant (`'default'`, `'nilearn'`, `'fmriprep'`).
`resolution`	`int`	Resolution in mm (1, 2, or 3).
`mask`	`str`	Path to the brain mask file.
`brain`	`str`	Path to the brain-extracted image.
`plot`	`str`	Path to the full T1 image used for plotting.

Attributes¶

brain `property` ¶

brain: str

Path to the brain-extracted image.

mask `property` ¶

mask: str

Path to the brain mask file.

plot `property` ¶

plot: str

Path to the full T1 image used for plotting.

Result types¶

Classes¶

Predict dataclass ¶

Attributes¶

mean_score property ¶

std_score property ¶

Methods:¶

asdict ¶

available ¶

BootstrapResult dataclass ¶

ContrastResult dataclass ¶

BrainSpaceConfig dataclass ¶

Attributes¶

brain property ¶

mask property ¶

plot property ¶

Predict `dataclass` ¶

mean_score `property` ¶

std_score `property` ¶

BootstrapResult `dataclass` ¶

ContrastResult `dataclass` ¶

BrainSpaceConfig `dataclass` ¶

brain `property` ¶

mask `property` ¶

plot `property` ¶