BrainData¶

BrainData(data = None, *, Y = None, X = None, mask = None, masker = None, h5_compression = 'gzip', verbose = False, resample = True, interpolation = 'auto')

Represent neuroimaging data as vectors instead of three-dimensional matrices.

This representation makes it easier to perform data manipulation and analyses.

Parameters:

Attributes:

Methods:

Methods¶

align¶

align(target, method = 'procrustes', axis = 0, *, spatial_scale: str = 'whole_brain', roi_mask: str = None, radius_mm: float = 10.0)

Align BrainData instance to target object using functional alignment.

Parameters:

Returns:

Examples:

>>> out = data.align(target, method='procrustes')
>>> out = data.align(target, method='probabilistic_srm')

append¶

append(data, ignore_attrs = False, **kwargs)

Append data to BrainData instance.

Parameters:

Returns:

apply_mask¶

apply_mask(mask, resample_mask_to_brain = False)

Mask BrainData instance using nilearn functionality.

Note target data will be resampled into the same space as the mask. If you would like the mask resampled into the BrainData space, then set resample_mask_to_brain=True.

Parameters:

Returns:

astype¶

astype(dtype)

Cast BrainData.data as type.

Parameters:

Returns:

bootstrap¶

bootstrap(stat, *, n_samples = 5000, save_boots = False, percentiles = (2.5, 97.5), X_test = None, device = 'cpu', max_gpu_memory_gb = None, tail = 2, n_jobs = -1, random_state = None, progress_bar: bool = False)

Bootstrap statistics using efficient online algorithms.

Uses memory-efficient bootstrap infrastructure with CPU parallelization or GPU acceleration. Supports simple aggregation statistics and fitted model statistics (Ridge).

Parameters:

Returns:

Examples:

>>> boot = brain.bootstrap(stat='mean', n_samples=1000)
>>> brain.fit(X=dm, model='ridge', alpha=1.0)
>>> boot = brain.bootstrap(stat='weights', n_samples=1000)

cluster_report¶

cluster_report(*, stat_threshold: float | None = 3.0, cluster_threshold: int = 10, two_sided: bool = True, min_distance: float = 8.0, atlas: str | Sequence[str] | None = None, prob_threshold: float = 5.0) -> ClusterReport

Generate a cluster report with anatomical labels.

Identifies surviving clusters in the stat map (after voxel + extent thresholding), reports peak coordinates and sub-peaks, and labels each peak/cluster against one or more atlases.

Parameters:

Returns:

compute_contrasts¶

compute_contrasts(contrasts, statistic = 't')

Compute contrasts from fitted GLM results.

This method computes contrasts as linear combinations of the GLM beta coefficients. Must be called after .fit(model=‘glm’, X=design_matrix) has been run.

Parameters:

Returns:

Examples:

>>> brain.fit(model='glm', X=design_matrix)
>>> contrast1 = brain.compute_contrasts([0, 1, -1])
>>> contrast2 = brain.compute_contrasts("conditionA - conditionB")
>>> results = brain.compute_contrasts({
...     "A_vs_B": "conditionA - conditionB",
...     "avg_effect": [0, 0.5, 0.5],
... })

copy¶

copy()

Create a copy of a BrainData instance (data deep-copied).

The data array and most attributes are deep-copied, so mutating the copy’s data leaves the original untouched. Fitted state is shared, not copied: model_, X_, every glm_*/ridge_* result, and mask/ masker are held by reference (this avoids pickling unpicklable Backend objects — see __deepcopy__). Mutating those on the copy mutates the original; refit the copy if you need independent fit results.

Returns:

create_empty¶

create_empty()

Create a copy of BrainData with empty data array.

Returns:

decompose¶

decompose(*, method = 'pca', axis = 'voxels', n_components = None, **kwargs)

Decompose BrainData object.

Parameters:

Returns:

detrend¶

detrend(method = 'linear')

Remove linear trend from each voxel.

Parameters:

Returns:

distance¶

distance(metric = 'euclidean', *, spatial_scale: str = 'whole_brain', roi_mask: str = None, radius_mm: float = 10.0, **kwargs: float)

Calculate distance between images within a BrainData() instance.

Parameters:

Returns:

extract_roi¶

extract_roi(mask, method = 'mean', n_components = None)

Extract activity from mask or ROI atlas using NiftiLabelsMasker.

Parameters:

Returns:

Examples:

>>> roi_values = brain.extract_roi(binary_mask)
>>> atlas_values = brain.extract_roi(atlas_mask)
>>> components = brain.extract_roi(mask, method='pca', n_components=5)

filter¶

filter(*, sampling_freq = None, high_pass = None, low_pass = None, **kwargs)

Apply a Butterworth filter to data (wraps nilearn.signal.clean).

Parameters:

Returns:

find_spikes¶

find_spikes(global_spike_cutoff = 3, diff_spike_cutoff = 3, *, TR: float | None = None, sampling_freq: float | None = None)

Identify spikes from Time Series Data.

Parameters:

Returns:

fit¶

fit(model = 'glm', *, X = None, cv = None, device = 'cpu', local_alpha = True, fit_intercept = False, inplace = True, scale = 'auto', standardize = 'auto', progress_bar = False, **kwargs)

Fit a model to brain imaging data.

Creates and fits a model from string specification. The brain data (self.data) is always used as the target variable. Model and results are stored for later use with predict().

Parameters:

Returns:

Examples:

>>> brain_data.fit(model='ridge', alpha=1.0, cv=5, X=features)
>>> fit = brain_data.fit(model='ridge', alpha=1.0, X=features, inplace=False)

iplot¶

iplot(*, view: str = 'ortho', threshold: float | str | None = None, lower: float | str | None = None, upper: float | str | None = None, autoscale: bool | tuple[float, float] = True, cmap: str = 'warm', bg_img: str | bool | None = None, atlas: str | Atlas | None = None, opacity: float = 1.0, outline: float = 0.0, colorbar: bool = True, controls: bool = True, **kwargs: bool)

Interactive WebGL brain viewer powered by niivue.

Renders inline in a live kernel (Jupyter, marimo) with live windowing (right-drag to set the threshold/contrast), slice scrolling, native 4D frame scrubbing, true 3D rendering, a stat-map colorbar, and optional nltools-atlas overlays. Static-built docs (plain Markdown) are not interactive; use plot there.

Returns a NiivueViewer widget. By default (controls=True) it renders an in-widget threshold slider above the viewer; the window is reactive through the cal_min / cal_max traits. Pass controls=False to hide the slider (right-drag windowing still works).

Thresholding is a divergent magnitude window: cal_min is the display floor (sub-floor voxels render transparent), cal_max the saturation point, with the positive limb using cmap and the negative limb its mirrored partner. Precedence: lower/upper win; otherwise threshold sets the floor; any unset edge comes from autoscale. The window is always computed in Python and passed to niivue explicitly, so the slider handles show exactly the window being rendered.

Parameters:

Returns:

mean¶

mean(axis = 0, *, spatial_scale: str = 'whole_brain', roi_mask: str = None)

Get mean of each voxel or image.

Parameters:

Returns:

median¶

median(axis = 0, *, spatial_scale: str = 'whole_brain', roi_mask: str = None)

Get median of each voxel or image.

Parameters:

Returns:

multivariate_similarity¶

multivariate_similarity(images, method = 'ols', tail = 2)

Predict a BrainData spatial distribution from a linear combination.

The predictors may be other BrainData instances or nibabel images.

Parameters:

Returns:

plot¶

plot(*, method = 'glass', upper = None, lower = None, threshold = None, view = 'z', cut_coords = None, cmap = None, bg_img = None, ax = None, figsize = (8, 6), title = None, colorbar = True, save = None, stat = 'mean', limit = 3, **kwargs)

Plot BrainData instance using nilearn visualization or matplotlib.

Parameters:

Returns:

plot_flatmap¶

plot_flatmap(*, threshold = None, cmap = 'RdBu_r', vmax = None, vmin = None, template = 'fsaverage5', with_curvature = True, curvature_contrast = 0.5, curvature_brightness = 0.5, transparency = 'auto', colorbar = True, colorbar_orientation = 'horizontal', figsize = (12, 6), title = None, radius_mm = 3.0, interpolation = 'linear', axes = None, save = None)

Plot brain data on cortical flatmap.

Parameters:

Returns:

plot_surf¶

plot_surf(*, hemi = 'both', view = 'montage', surface = 'pial', template = 'fsaverage5', threshold = None, cmap = 'RdBu_r', vmin = None, vmax = None, transparency = 'auto', bg_on_data = False, colorbar = True, colorbar_orientation = 'horizontal', figsize = (10, 8), title = None, radius_mm = 3.0, interpolation = 'linear', zoom = 1.2, axes = None, save = None)

Render this BrainData on fsaverage surfaces as a tight 2×2 montage.

Facade over plot_surf. See that function’s docstring for the full argument reference. Notable defaults: surface="pial", zoom=1.2, transparency="auto" (uses this instance’s .mask).

Returns:

predict¶

predict(*, y: np.ndarray | str | None = None, X: np.ndarray | None = None, spatial_scale: str = 'whole_brain', model: str = 'svm', cv: int | str = 5, standardize: bool = True, reduce: str | None = None, n_components: int | None = None, scoring: str = 'auto', groups: np.ndarray | str | None = None, roi_mask: np.ndarray | str | None = None, radius_mm: float = 10.0, inplace: bool = False, n_jobs: int = 1, random_state: int | None = None, progress_bar: bool = False)

Predict voxel timeseries (encoding) or decode labels (MVPA).

Dispatched by which of X or y is provided:

1. Timeseries prediction (X provided): use a fitted ridge / GLM encoding model on self to predict voxel responses. Returns a fresh BrainData whose .data holds the predicted timeseries (composes directly with .plot(), .standardize() etc.). inplace has no effect in this mode.

2. MVPA decoding (y provided, or resolvable from .Y): train a classifier or regressor with cross-validation. Returns a Predict dataclass. Spatial fields (weight_map, fold_weight_maps, final_weight_map, accuracy_map) are BrainData objects so result.weight_map.plot() works directly. Drop down to numpy via result.weight_map.data.

Labels travel with the data: when y is omitted and this object carries a single-column .Y frame, that column is decoded (y='name' picks a column of a multi-column .Y; groups accepts a .Y column name the same way). An object with both a fitted encoding model and a stored .Y refuses the no-argument call as ambiguous — pass y= or X= explicitly.

Field shapes by spatial_scale=:

• whole_brain: predictions (n_samples,) OOF predictions, scores (n_folds,), mean_score float, std_score float, weight_map BrainData (coef_ from one fit on the full (X, y) — the publishable map), fold_weight_maps BrainData (n_folds, n_voxels) for stability analysis, estimator the fitted all-data sklearn estimator (use for .predict() on new data).

• roi: scores (n_folds, n_rois), mean_score (n_rois,), std_score (n_rois,), roi_labels (n_rois,) atlas IDs in matching order, accuracy_map / weight_map / fold_weight_maps BrainData (per-parcel coefs reassembled to voxel space; voxels outside the atlas = NaN), estimator dict keyed by atlas label.

• searchlight: accuracy_map BrainData.

With inplace=True, fields are attached to self with a predict_ prefix (e.g. self.predict_weight_map, self.predict_accuracy_map), mirroring bd.fit()'s glm_* / ridge_* naming.

Why weight_map is the all-data refit, not the CV mean: the mean of K per-fold coef_ vectors doesn’t correspond to any actual fitted estimator (each fold saw a different subset). The all-data refit is a single legitimate model with all the information used. CV gives the honest score; the refit gives the publishable map. The CV-mean is one line away if you want it: result.fold_weight_maps.data.mean(axis=0).

Parameters:

Returns:

Examples:

>>> result = brain.predict(y=labels, spatial_scale='whole_brain', cv=5)
>>> result.weight_map.plot()       # publishable map (all-data fit)
>>> result.mean_score              # honest CV-derived accuracy
>>> new_pred = result.estimator.predict(new_X)  # apply to new data

>>> result = brain.predict(y=labels, spatial_scale='searchlight',
...                        radius_mm=8.0, n_jobs=4)
>>> result.accuracy_map.plot()

>>> result = brain.predict(y=labels, spatial_scale='roi', roi_mask=atlas)
>>> top = result.roi_labels[result.mean_score.argsort()[::-1][:10]]
>>> result.accuracy_map.plot()  # brain-space view of the same map

Custom sklearn pipeline as model — standardize auto-defaults to False because we detect the Pipeline:

from sklearn.feature_selection import SelectKBest
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.svm import LinearSVC
pipe = make_pipeline(StandardScaler(), SelectKBest(k=500),
                     LinearSVC())
result = brain.predict(y=labels, model=pipe)

r_to_z¶

r_to_z()

Apply Fisher’s r-to-z transformation to each data element.

regions¶

regions(*, min_region_size = 1350, method = 'local_regions', smoothing_fwhm = 6, is_mask = False)

Extract brain connected regions into separate regions.

Parameters:

Returns:

report¶

report(contrasts = None, **kwargs)

Generate a nilearn HTML report for a fitted GLM.

Must be called after fit(model='glm', ...). Renders the design matrix, requested contrast maps, and model parameters as a self-contained HTML report.

Parameters:

Returns:

Examples:

>>> brain.fit(model='glm', X=design_matrix)
>>> brain.report(contrasts='conditionA - conditionB').save_as_html('report.html')

resample_to¶

resample_to(*, img = None, resolution = None, interpolation = None)

Resample BrainData to match target image or resolution.

Parameters:

Returns:

scale¶

scale(scale_val = 100.0, axis = None)

Scale data via mean scaling.

Two scaling modes are available:

• Grand-mean scaling (axis=None, default): Divides all values by the global mean across all voxels and timepoints.

• Voxel-wise scaling (axis=0): Divides each voxel’s time-series by its own temporal mean.

Parameters:

Returns:

similarity¶

similarity(image, metric = 'correlation')

Calculate similarity to a single BrainData or nibabel image.

Parameters:

Returns:

smooth¶

smooth(fwhm)

Apply spatial smoothing using nilearn smooth_img().

Parameters:

Returns:

standardize¶

standardize(*, axis = 0, method = 'center', suppress_warnings = False)

Standardize BrainData() instance.

Parameters:

Returns:

std¶

std(axis = 0, *, spatial_scale: str = 'whole_brain', roi_mask: str = None)

Get standard deviation of each voxel or image.

Parameters:

Returns:

sum¶

sum(axis = 0)

Get sum of each voxel or image.

Parameters:

Returns:

temporal_resample¶

temporal_resample(*, sampling_freq = None, target = None, target_type = 'hz')

Resample BrainData timeseries to a new target frequency or number of samples.

Parameters:

Returns:

threshold¶

threshold(*, upper = None, lower = None, binarize = False, coerce_nan = True, cluster_threshold = 0)

Threshold BrainData instance with optional cluster filtering.

Parameters:

Returns:

to_nifti¶

to_nifti()

Convert BrainData Instance into Nifti Object.

Returns:

transform_pairwise¶

transform_pairwise()

Transform data into pairwise comparisons.

Returns:

ttest¶

ttest(*, popmean = 0.0, permutation = False, n_permute = 5000, tail = 2, return_null = False, n_jobs = -1, random_state = None)

One-sample voxelwise t-test across images (axis 0).

Tests whether the per-voxel mean across images differs from popmean. Operates on a stack of images (e.g. subject-level contrast maps) with shape (n_samples, n_voxels).

Parameters:

Returns:

Examples:

>>> # Stack of subject-level contrast maps
>>> result = contrast_maps.ttest()
>>> sig = result["p"].data < 0.05
>>> effect = result["mean"]       # for reporting magnitude
>>> z_map = result["z"]           # for nilearn-style thresholding

>>> # Permutation-based p-values; still reports t/z/mean
>>> result = contrast_maps.ttest(permutation=True, n_permute=5000)

ttest2¶

ttest2(other, equal_var = True, tail = 2)

Two-sample voxelwise t-test between two BrainData stacks.

Parameters:

Returns:

upload_neurovault¶

upload_neurovault(*, access_token = None, collection_name = None, collection_id = None, img_type = None, img_modality = None, **kwargs)

Upload BrainData images and metadata to NeuroVault.

Adds any columns in self.X to image metadata. The index is used as the image name.

Parameters:

Returns:

write¶

write(file_name)

Write out BrainData object to Nifti or HDF5 File.

Parameters:

z_to_r¶

z_to_r()

Convert z score back into r value for each element of data object.