BrainData ¶

Object to align to.

Alignment method: 'probabilistic_srm', 'deterministic_srm', or 'procrustes'. Default 'procrustes'.

Axis to align on. Default 0.

'whole_brain' (default) or 'roi' (per-parcel transforms + reassembly, requires roi_mask).

Atlas image used when spatial_scale='roi'.

'transformed', 'transformation_matrix' and 'common_model', plus 'disparity' and 'scale' for method='procrustes'. A value is a BrainData when its columns are a voxel axis matching the mask it carries, and a raw np.ndarray otherwise. 'procrustes' therefore returns all three as independently owned BrainData, with float 'disparity' and 'scale'. The SRM methods return 'transformed' (n_images, n_features) and 'common_model' (n_model_rows, n_features) as raw np.ndarray, since both span the common model's feature axis rather than voxels, and 'transformation_matrix' as a BrainData of n_features voxel maps. With axis=1 the transformation matrix spans images on its column axis for either method, so it is a raw np.ndarray too. With spatial_scale='roi' the result also carries 'roi_labels', 'transformed' is one stitched BrainData, 'transformation_matrix' and 'common_model' are dicts keyed by atlas label whose values follow the same rule on that parcel's mask, and 'disparity' and 'scale' are one-per-parcel arrays.

If a value that must be returned as a BrainData has a column count other than the mask support — for example a 'procrustes' target with more voxels than the source, which zero-pads the source data to the target's width.

BrainData instance to append.

Clear both X and Y on the result when True. Otherwise, each metadata frame must be empty on both inputs or have compatible columns on both inputs. Default False.

Independently owned data with concatenated row metadata.

Metadata is present on only one input or has incompatible columns.

Mask to apply.

Masked BrainData object.

If the mask is not a single 3-D image, or its shape or affine differs from this object's.

If mask is not a BrainData, nibabel image, or file path.

Datatype to convert to.

BrainData instance with new datatype.

Statistic to bootstrap. Basic aggregates: 'mean', 'median', 'std', 'sum', 'min', 'max' — each the corresponding NumPy reduction over rows, with 'std' at ddof=0. Model statistics (require a fitted _Ridge): 'weights' or 'predict'.

Training features in their original row order — a matrix for ordinary Ridge, a mapping with exactly the fitted feature-space names for banded Ridge. Required by both model statistics; rejected by the basic ones.

Evaluation features for statistic='predict', in the same structure as X. Any row count is allowed.

Number of bootstrap replicates, at least two. Default 5000.

Confidence level of the reported interval, strictly between zero and one. Default 0.95. The bounds are the central percentile interval by linear interpolation, and they are elementwise marginal: the nominal level applies separately to each voxel, feature, or test row, with no simultaneous-coverage claim. A different level needs a new run unless return_samples=True kept the distribution.

Compute device for the Ridge refits: 'cpu' (default) or 'gpu' (PyTorch on CUDA/MPS, or an error when neither is available). Basic statistics reject 'gpu'.

Working-memory budget in GB. It governs the output preflight and CPU-worker planning for every statistic, and GPU batch sizing for the Ridge ones. None (default) measures the device.

Retain and return every replicate. Default False. It changes retention only, never interval semantics.

CPU worker ceiling. -1 (default) means all cores; the planner may use fewer.

Random seed for reproducibility.

If True, show a progress bar. Default False.

estimate (the statistic on the unresampled full sample — for 'weights' the fitted coefficients, for 'predict' the full-data model at X_test), standard_error (the ddof=1 deviation across replicates), ci_lower and ci_upper, all BrainData of identical shape, plus samples as a NumPy array with the bootstrap axis first when return_samples=True.

If the data is not a stack of at least two observations, statistic is unknown, a basic statistic is given X, X_test or device='gpu', a Ridge statistic is missing its features, the fitted model is not a _Ridge, an argument is out of range, or the retained output cannot fit the memory budget.

Voxel-level threshold (e.g. z- or t-cutoff), applied exclusively: a voxel exactly at the threshold is dropped, unlike BrainData.threshold, whose cutoffs are inclusive. None treats self as already thresholded.

Minimum cluster size in voxels.

Report negative clusters separately.

Minimum mm between sub-peaks within a cluster.

Atlas name or list of names (see list_atlases). Defaults to ("harvard_oxford", "aal", "schaefer_200").

Drop probabilistic-atlas regions below this %.

Report with peaks and clusters (polars DataFrames) and stat_img (BrainData).

One contrast definition, or a mapping of names to definitions.

If True, return ContrastResult records carrying effect, variance, standard error, t-statistic, z-score, one-sided p-value, and degrees of freedom. Default False.

An effect map for one contrast, or a ContrastResult of maps when inference=True; a dictionary with the same keys for a mapping.

If no model has been fitted.

If the fitted model is not a _Glm, or a contrast is invalid (see _Glm.compute_contrasts).

An independent copy, including fitted state.

A copy of this object with an empty data array.

Decomposition algorithm: 'pca', 'ica', 'nnmf', 'fa', 'dictionary', or 'kernelpca'. Default 'pca'.

Dimension to decompose: 'voxels' (default) or 'images'.

Number of components. If None then retain as many as possible.

Forwarded to the underlying sklearn decomposition estimator.

A dictionary of decomposition parameters.

Type of detrending: 'linear' (default) or 'constant'.

Detrended BrainData instance.

Distance metric — any scipy.spatial.distance metric supported by cdist. Default 'euclidean'.

One of 'whole_brain' (default), 'roi', or 'searchlight'. 'whole_brain' returns a single pairwise distance Adjacency between images. 'roi' requires roi_mask and returns a stacked Adjacency with one RDM per sorted nonzero atlas label present inside the source mask after nearest-neighbor resampling. 'searchlight' returns one RDM per source-mask voxel in mask order.

Atlas image for spatial_scale='roi'.

Searchlight radius in mm. Default 10.0.

Additional metric options forwarded to scipy.spatial.distance.cdist (e.g. p for minkowski).

Single pairwise distance matrix for 'whole_brain'; ordinary stack for 'roi' / 'searchlight'. Map per-matrix values externally using roi_to_brain_from_atlas with the aligned atlas and sorted surviving ROI labels, or nilearn.masking.unmask with the source mask for searchlights. Subset the mapping whenever selecting matrices from the returned stack.

Binary mask or labeled atlas to extract from, on any grid.

Extraction method: 'mean' (default), 'median', or 'pca'.

Number of components to return when method='pca'.

For a binary mask, a scalar (single image) or 1D array (multiple images). For a labeled atlas, a 1D array (single image), a 2D array of ROIs x images (multiple images), or the PCA components array when method='pca'.

If, after resampling onto this object's grid, mask has no overlap with it.

Sampling frequency in hertz (i.e. 1 / TR).

High-pass cutoff frequency in hertz.

Low-pass cutoff frequency in hertz.

Additional arguments passed to nilearn.signal.clean.

Filtered BrainData instance. X and Y follow the rows clean returns: one run at a time in np.unique(runs) order, censored by that run's sample_mask.

cutoff to identify spikes in global signal in standard deviations, or None to skip.

cutoff to identify spikes in average frame difference in standard deviations, or None to skip.

Repetition time in seconds. Sets the returned DesignMatrix's sampling_freq for downstream .append(...) / .convolve(). Pass exactly one of TR or sampling_freq.

Sampling frequency in Hz (= 1/TR). See TR.

One indicator column per detected spike TR, with all spike columns pre-marked as confounds. A TR flagged by both detectors yields a single column (named global_spike*); the colliding detections are bitwise identical, so only the retained name differs.

'glm' (default) or 'ridge'.

A precomputed DesignMatrix for a GLM; a feature matrix for ridge, or a mapping of feature-space names to matrices for banded ridge. Required.

Ridge only. A positive scalar fits a fixed α and requires ridge_cv=None; a sequence selects α by cross-validation and requires ridge_cv. Default 1.0.

Ridge only. Cross-validation specification; int → unshuffled KFold(cv). Generators are rejected. Default None.

Ridge only, banded. Sampled feature-space weight vectors. Default 100.

Ridge only, banded. Dirichlet concentration for those candidate weights. Default (0.1, 1.0).

Ridge only. 'cpu' (default) or 'gpu'.

Ridge only. Working-memory budget in GB for the solver's internal batching. Default None (measure the device).

Ridge only. Select α per voxel (default True) or one shared α.

Ridge only. Select the largest α within one standard deviation of the best score. Default False.

Ridge only. Show a progress bar over the banded search. Default False.

GLM only. 'ols' (default) or 'arN' for Nilearn's autoregressive model of order N.

GLM only. Nilearn's discretization of the estimated AR coefficients. Default 100.

GLM only. CPUs Nilearn uses for autoregressive groups; the default OLS fit does not use this path. Default 1.

If True (default), mutate self and return self. If False, fit and return an independent BrainData copy while leaving every part of self untouched.

Seed shared by both estimators.

Self when inplace=True; otherwise an independently owned fitted copy.

"ortho" (default), "axial", "coronal", "sagittal", or "render" (3D volume render). "surface" is no longer supported — use "render" or plot_flatmap / plot_surf.

Convenience symmetric magnitude floor (→ cal_min). Accepts a percentile string ("95%") resolved over the finite nonzero magnitudes, consistent with threshold.

Window floor as a magnitude (→ cal_min). Overrides threshold. Accepts a percentile string. A value at or below zero is raised to the slider's smallest step.

Window ceiling as a magnitude (→ cal_max). Overrides threshold. Accepts a percentile string.

Robust default window for the edges not set above. True (default): ceiling at the 98^th percentile of the finite nonzero magnitudes — a couple of outlier voxels no longer wash out the whole map — and an epsilon floor, never above the smallest nonzero magnitude, so zeros render transparent and every real voxel stays visible (threshold up from there). False: the raw magnitude range, from one slider step above zero to the largest absolute value. For a custom percentile window pass lower/upper (e.g. lower="60%", upper="98%").

"auto" (default) mirrors mixed-signed maps but lets each sign in a one-sided map determine its own ceiling. True always mirrors; False scales positive and negative limbs independently.

niivue colormap for the positive limb. The default uses niivue's red positive and blue negative palettes. Common matplotlib names are auto-mapped with a warning.

None/True auto-loads the matching MNI template when the data is in standard space (else none); False disables the background; a path string uses that image.

Atlas overlay — a registry name (e.g. "aal"), a loaded atlas record, or None. Deterministic atlases only; probabilistic atlases raise.

Stat-map (and filled-atlas) opacity in 0..1.

> 0 draws atlas region boundaries of that width (stat map stays visible); 0 draws filled regions.

Show the stat-map colorbar (default True). An explicit is_colorbar kwarg overrides this.

Render an in-widget threshold slider above the viewer (default True). False hides it; the viewer still supports niivue's right-drag windowing. No extra dependency either way — the slider is native to the widget frontend.

Passed as niivue options. height configures the canvas and is_colorbar overrides colorbar.

An anywidget.AnyWidget whose threshold window is reactive via the cal_min and cal_max traits.

If autoscale is not a bool or symmetric is not True, False, or "auto".

0 = across images (default, returns BrainData), 1 = within images (returns array).

Mean values.

0 = across images (default, returns BrainData), 1 = within images (returns array).

Median values.

Predictor image(s) — a BrainData stack of weight maps or nibabel images.

2 or 'two' for two-tailed (default); 1 or 'one' for one-tailed (positive direction) regression p-values.

Regression statistics as BrainData instances, keyed 'beta', 't', 'p', 'df', 'residual'.

Visualization type: 'glass', 'slices', 'timeseries', 'histogram'

Upper threshold.

Lower threshold.

Absolute transparency cutoff. Percentile strings resolve over finite, nonzero magnitudes. Omitted, method="glass" draws every voxel.

For method="slices", any non-empty combination of "x", "y", "z" (e.g. "xyz", "xz", "y"). Default: "z".

Cut coordinates for multi-slice views. Takes precedence over view-based defaults. Either a list matching len(view) or a dict keyed by axis letter.

Colormap name. Defaults are sign-aware.

Background image.

Matplotlib axis to draw on. The nilearn methods receive it as axes=, and the figure stays the caller's. One axis holds one map, so ax raises unless exactly one map is drawn (limit=1 on a multi-image stack draws the first).

Figure size for method='timeseries' and method='histogram' when no ax is given. Default (8, 6). A glass or slice figure takes its size from a supplied ax, or from nilearn's own default.

Plot title.

Whether to show colorbar. Default: True.

Path to save figure(s).

Statistic for timeseries plots. Default: 'mean'.

Maximum number of images to render when this BrainData contains multiple maps and method is "glass" or "slices". Default: 3. Warns when more images exist than limit.

Additional arguments passed to nilearn plot functions.

A single figure for single-image data; a list of figures for multi-image data with method in {"glass", "slices"} (one per image for glass; one per image-and-view pair for slices).

Absolute cutoff or percentile string.

Matplotlib colormap. Defaults are sign-aware.

Maximum value; inferred from displayed data.

Minimum value; inferred from displayed data.

Freesurfer surface resolution. Default: 'fsaverage5'.

Binary mask used to render vertices outside the mask as transparent. "auto" (default) uses the instance's .mask; pass None to disable masking.

Show colorbar. Default: True.

Figure size as (width, height). Default: (12, 6).

Figure title.

File path to save figure.

The rendered figure.

The rendered figure.

Features for fitted-model prediction, shape (n_samples, n_features), or a mapping of feature-space names to matrices for a banded _Ridge.

Labels (classification) or continuous targets (regression), shape (n_samples,), or the name of a .Y column. Must be one-dimensional with one value per row; multioutput and multilabel targets are not accepted.

A built-in shortcut — 'linear_svc', 'logistic_regression', 'linear_discriminant_analysis', 'ridge_classifier', 'ridge', 'lasso', 'linear_svr' — or any sklearn estimator or Pipeline, which is used exactly as supplied. Default 'linear_svc'. Every shortcut standardizes voxels inside each fold and then fits a linear estimator; the two ridge shortcuts select their penalty inside that fold too, by an inner cross-validation over a ten-point log grid from 1e-3 to 1e6 (RidgeCV and RidgeClassifierCV), because the working penalty at whole-brain scale is nowhere near scikit-learn's default alpha=1. A classification shortcut on a multiclass target is wrapped in OneVsRestClassifier, so every class gets its own signed map. A caller-supplied estimator is never wrapped and never has its multiclass strategy overridden — pass a OneVsRestClassifier to get one. Every preprocessing step, in every spatial scale, must be one of StandardScaler, PCA, VarianceThreshold, GenericUnivariateSelect, SelectPercentile, SelectKBest, SelectFpr, SelectFdr, SelectFwe, SelectFromModel, RFE, RFECV, SequentialFeatureSelector, None, or 'passthrough'. Whole-brain and ROI pipelines must also end in an estimator exposing coef_, since those two scales extract a weight map; searchlight builds none and does not require it.

Constructor options for a shortcut, merged over the shortcut's own defaults so a supplied key wins — estimator='ridge', estimator_kwargs={'alphas': [1e4]} fixes the penalty grid. Passing it alongside a caller-supplied estimator raises ValueError: that estimator is used exactly as given, so configure it at construction.

None (the default, five folds) or an int fold count both mean a deterministic, unshuffled stratified K-fold: class-balanced folds for a classifier, and for a regressor folds balanced on quantile bins of y so every fold matches the outcome distribution — which needs at least two rows per fold, and raises below that. With groups given, the group-aware variant (StratifiedGroupKFold), so no group is split across the train/test boundary. An sklearn splitter is used as supplied. Test folds must partition the rows, so shuffle-split and repeated splitters raise.

Group labels — one per row (subject, run), or the name of a .Y column holding them. With an integer or None cv they select the group-aware splitter; with an explicit splitter they are forwarded to its split() (e.g. LeaveOneGroupOut for leave-one-run-out).

Follows scikit-learn's single-metric scoring contract. None (the default) uses the estimator's own score method; a scoring name or callable overrides it. Multimetric mappings are not accepted, and an unrecognized name raises before anything is fitted at every spatial scale.

MVPA dispatch — 'whole_brain', 'roi', or 'searchlight'.

Atlas image; required by, and only valid for, spatial_scale='roi'.

Searchlight sphere radius in millimeters; only valid for spatial_scale='searchlight'. Default 10.0.

Draw the cross-validated figures as a side effect. Default False; the returned PredictResult is the same either way. Regression draws predicted values against observed ones, titled with the cross-validated Pearson r. Binary classification draws the ROC of the out-of-fold decision values, then the margin figure (decision_function) or the probability figure (predict_proba), whichever the estimator exposes. Both also draw weight_map. Multiclass decoding, and any spatial scale other than 'whole_brain', raise instead of drawing.

Parallel workers for the outer independent work of the selected spatial scale — cross-validation folds for whole-brain, parcels for ROI, spheres for searchlight. Default 1; every worker holds a copy of the data, so a real brain at higher n_jobs can be memory-heavy.

Show a progress bar for searchlight and ROI.

A PredictResult record for MVPA; a new BrainData holding the predicted timeseries for fitted-model prediction. The record's spatial_scale says which of its fields carry values: whole-brain fills predictions, cv_folds, scores, estimator and weight_map; ROI fills scores, roi_labels, score_map and weight_map; searchlight fills score_map alone. classes accompanies any classifier and scoring records the scoring specification in every mode. mean_score and std_score are computed from scores on demand and do not exist for a searchlight result. weight_map holds one coefficient map for regression and binary classification (the signed map for classes[1] versus classes[0]) and one map per class, in classes order, for multiclass — never an average across classes. It is projected back to voxel units through the pipeline's fitted preprocessing, but centering is not undone, so raw_data @ weight_map does not reproduce the decision function; use result.estimator to predict.

On both X and y, a decoding argument on a fitted-model call, an unknown estimator shortcut or spatial scale, a target or group vector that is not one value per row, a continuous target with fewer than two rows per fold under an integer cv, cross-validation folds that do not partition the rows, a preprocessing step outside the supported set, a pipeline whose coefficients cannot be projected back onto the voxel axis (whole-brain and ROI decoding only), estimator_kwargs alongside a caller-supplied estimator, or plot=True on a multiclass target or a non-whole-brain scale.

On a removed keyword, an estimator that is neither a shortcut name nor an object with fit/predict, or a cv that is neither None, an int, nor a splitter.

Minimum volume in mm3 for a region to be kept.

Type of extraction method ['connected_components', 'local_regions'].

Smooth an image to extract more sparser regions.

Treat the data as a binary mask and split it into connected components with nilearn.regions.connected_label_regions instead. Default False.

One image per extracted region; binary when is_mask=True, and otherwise carrying the source values inside each region.

If is_mask=True and no region reaches min_region_size.

Target image supplying the grid to match.

Target isotropic voxel size in mm.

Interpolation method for the data: 'nearest', 'linear', 'continuous', or None to use the instance's setting.

New BrainData instance with resampled data and mask.

If both img and resolution are None, both are provided, or resolution is not positive.

If img is not a valid image type.

Target value for the mean after scaling. Default 100.

None for grand-mean scaling (default), 0 for voxel-wise scaling.

New BrainData instance with scaled data.

Image to evaluate similarity against.

Type of similarity: 'correlation' (default), 'pearson', 'rank_correlation', 'spearman', 'dot_product', or 'cosine'.

Similarity value(s).

Full width at half maximum of the Gaussian spatial filter, in mm.

Copy with smoothed data.

'center' subtracts the mean (default); 'zscore' subtracts the mean and divides by the standard deviation.

0 standardizes each voxel across observations (default). 1 standardizes each observation across voxels.

Standardized BrainData instance.

If method is neither 'center' nor 'zscore'.

0 = across images (default, returns BrainData), 1 = within images (returns array).

Standard deviation values.

0 = across images (default, returns BrainData), 1 = within images (returns array).

Sum values.

Sampling frequency of the data in hertz.

Resampling target, interpreted per target_type.

How to read target: 'hz' (default), 'samples', or 'seconds'.

Resampled BrainData instance.

Upper cutoff for thresholding; a percentile string like '95%' is accepted.

Lower cutoff for thresholding; a percentile string is accepted.

Return a binarized image. Default False.

Coerce NaN values to 0s. Default True.

Minimum cluster size in voxels. Default 0.

Thresholded BrainData object.

Brain data as a NIfTI image.

BrainData instance transformed into pairwise comparisons

Population mean to test against. Default 0.0.

If True, take p from a sign-flip permutation test on images - popmean. The reported t stays the observed parametric statistic. Default False.

Number of permutations, used only when permutation=True. Default 5000.

2 or 'two' for two-tailed (default); 1 or 'one' for one-tailed (mean > popmean).

If True, also return the permutation null. Has no effect on the parametric path, which computes no null. Default False.

Number of parallel jobs. Default -1 (all cores).

Random seed for reproducibility.

If True, show a progress bar. Default False.

"mean", "t", "z" and "p" as independent BrainData images with observation metadata cleared. "mean" is the voxelwise mean minus popmean — the effect relative to the tested null, equal to the raw mean only when popmean=0. "t" is the observed one-sample t-statistic on both paths. "p" is parametric, or the empirical sign-flip p-value when permutation=True. "z" is the tail-aware normal score of p (sign(t) * norm.isf(p/2) two-tailed), matching nilearn's output_type='z_score'. With permutation=True and return_null=True the dict also holds "null_dist", an owned (n_permute, n_voxels) array of centered means in the units of "mean". Maps are unthresholded. Apply a cutoff or a multiple-comparison correction afterwards.

If this BrainData contains fewer than 2 images.

NeuroVault API access token. Required.

Name of a new collection to create.

NeuroVault collection_id when adding images to an existing collection.

NeuroVault map_type. Required.

NeuroVault image modality. Required.

Additional image metadata forwarded to the NeuroVault API.

NeuroVault collection information.

Output file path (.nii/.nii.gz for NIfTI, .h5/.hdf5 for HDF5).