analysis¶

BrainData analysis functions.

Standalone functions extracted from BrainData class methods for similarity, distance, masking, ROI extraction, filtering, thresholding, decomposition, alignment, smoothing, and other analytical operations.

Methods:

Methods¶

align¶

align(bd, target, method = 'procrustes', axis = 0)

Align a BrainData instance to a target using functional alignment.

Alignment type can be hyperalignment or Shared Response Model. When using hyperalignment, target image can be another subject or an already estimated common model. When using SRM, target must be a previously estimated common model stored as a numpy array. Transformed data can be back projected to original data using Transformation matrix.

See nltools.algorithms.align for aligning multiple BrainData instances

Parameters:

Returns:

Examples:

• Hyperalign using procrustes transform:

  out = data.align(target, method=‘procrustes’)

• Align using shared response model:

  out = data.align(target, method=‘probabilistic_srm’, n_features=None)

• Project aligned data into original data:

  original_data = np.dot(out[‘transformed’].data,out[‘transformation_matrix’].T)

align_per_roi¶

align_per_roi(bd, target, *, method, axis, roi_mask)

Per-parcel functional alignment + voxel-space reassembly.

For each atlas parcel, runs align() on the slice of bd and target restricted to that parcel’s voxels and collects results. The transformed field is reassembled into a single BrainData of the same shape as the input (each voxel filled with its parcel’s transformed value per image; voxels outside any parcel = NaN). Per-parcel transform matrices and common-model objects are kept as dicts keyed by atlas label, since matrices over different voxel subsets can’t be painted into one image.

apply_mask¶

apply_mask(bd, 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:

check_masks¶

check_masks(bd, image)

Ensure two datasets use compatible masks, creating a union mask if needed.

Parameters:

Returns:

decompose¶

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

Decompose a BrainData object.

Parameters:

Returns:

detrend_data¶

detrend_data(bd, method = 'linear')

Remove the linear trend from each voxel.

Parameters:

Returns:

distance¶

distance(bd, 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(bd, mask, method = 'mean', n_components = None)

Extract activity from mask or ROI atlas using NiftiLabelsMasker.

This method now uses nilearn’s NiftiLabelsMasker for efficient ROI extraction when dealing with labeled atlases (multiple ROIs).

Parameters:

Returns:

Examples:

>>> # Extract mean from binary mask
>>> roi_values = brain.extract_roi(binary_mask)
>>> # Extract from atlas
>>> atlas_values = brain.extract_roi(atlas_mask)
>>> # PCA extraction
>>> components = brain.extract_roi(mask, method='pca', n_components=5)

filter_data¶

filter_data(bd, *, sampling_freq = None, high_pass = None, low_pass = None, **kwargs)

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

Does not default to detrending and standardizing like nilearn implementation, but this can be overridden using kwargs.

Parameters:

Returns:

find_spikes_data¶

find_spikes_data(bd, global_spike_cutoff = 3, diff_spike_cutoff = 3, *, TR = None, sampling_freq = None)

Identify spikes from time-series data; see find_spikes.

multivariate_similarity¶

multivariate_similarity(bd, 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:

r_to_z¶

r_to_z(bd)

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

Parameters:

Returns:

reduce_per_roi¶

reduce_per_roi(bd, reducer, *, roi_mask)

Apply a reducer within each parcel and paint results back to voxel space.

This performs spatial smoothing via parcellation using a reducer such as np.mean.

For each image i and each parcel p, computes reducer(bd.data[i, voxels-in-p]) and assigns that scalar to every voxel in parcel p for image i. Voxels outside any parcel get NaN. Output is a BrainData of the same shape as the input.

Used by BrainData.{mean,std,median}(spatial_scale='roi').

regions¶

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

Extract brain connected regions into separate regions.

Parameters:

Returns:

scale_data¶

scale_data(bd, 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. This is consistent with FSL and SPM behavior. Use scale_val=10000 for FSL-style scaling.

• Voxel-wise scaling (axis=0): Divides each voxel’s time-series by its own temporal mean. This is AFNI-style scaling and can be useful when voxels have very different baseline intensities. Voxels with zero or near-zero mean are set to zero to avoid NaN/Inf.

When scale_val=100 (default), the result can be interpreted as something akin to (but not exactly) “percent signal change.”

Parameters:

Returns:

Examples:

>>> # Grand-mean scaling (default)
>>> scaled = brain.scale(100.0)
>>>
>>> # Voxel-wise scaling (AFNI style)
>>> scaled = brain.scale(100.0, axis=0)

similarity¶

similarity(bd, image, metric = 'correlation')

Calculate similarity to a single BrainData or nibabel image.

Parameters:

Returns:

smooth¶

smooth(bd, fwhm)

Apply spatial smoothing using nilearn’s smooth_img.

Parameters:

Returns:

standardize¶

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

Standardize BrainData() instance.

Parameters:

Returns:

temporal_resample¶

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

Resample a BrainData time series to a target frequency or sample count.

Resample BrainData timeseries to a new target frequency or number of samples using Piecewise Cubic Hermite Interpolating Polynomial (PCHIP) interpolation. This function can up- or down-sample data.

Note: this function can use quite a bit of RAM.

Parameters:

Returns:

threshold_data¶

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

Threshold BrainData instance with optional cluster filtering.

Provide upper and lower values or percentages to perform two-sided thresholding. Binarize will return a mask image respecting thresholds if provided, otherwise respecting every non-zero value.

Parameters:

Returns:

transform_pairwise_data¶

transform_pairwise_data(bd)

Transform BrainData into pairwise comparisons.

Parameters:

Returns:

z_to_r¶

z_to_r(bd)

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

Parameters:

Returns: