algorithms¶

nltools.algorithms — the functional core of nltools.

Every user-facing statistical function and algorithm is importable flat from here (from nltools.algorithms import fdr, zscore, isc), organized into focused submodules underneath:

• corrections: multiple-comparison corrections (FDR, Holm-Bonferroni, thresholding)

• outliers: outlier detection, winsorizing, z-scoring

• signal: temporal signal processing (resampling, filtering, basis functions)

• similarity: similarity metrics and Fisher transforms

• regression: standalone OLS regression on numpy arrays

• alignment: SRM, HyperAlignment, LocalAlignment, and the functional align/procrustes entry points

• inference: permutation tests, bootstrap resampling, and intersubject statistics (ISC/ISFC/ISPS) with CPU-parallel and GPU backends

• ridge: regularized regression (also exported as a module for advanced usage)

• hrf: hemodynamic response functions

Classes:

Methods:

Modules:

Classes¶

DetSRM¶

DetSRM(*, n_iter: int = 10, features: int = 50, rand_seed: int = 0) -> None

Bases: BaseEstimator, TransformerMixin

Deterministic Shared Response Model (DetSRM).

Given multi-subject data, factorize it as a shared response S among all subjects and an orthogonal transform W per subject:

Parameters:

Attributes:

Methods:

Examples:

Basic multi-subject DetSRM fitting:

>>> from nltools.algorithms import DetSRM
>>> import numpy as np
>>>
>>> # Create sample data (3 subjects)
>>> data = [np.random.randn(100, 50) for _ in range(3)]
>>>
>>> # Fit DetSRM with CPU parallelization (default)
>>> detsrm = DetSRM(n_iter=10, features=50)
>>> detsrm.fit(data, parallel="cpu", n_jobs=-1)
>>>
>>> # Transform to shared response space
>>> shared_responses = detsrm.transform(data)
>>>
>>> # Access fitted model components
>>> w = detsrm.w_  # Subject-specific transforms
>>> s = detsrm.s_  # Shared response

Methods¶

fit¶

fit(X: list[np.ndarray], y: Any | None = None, *, parallel: str | None = 'cpu', n_jobs: int = -1) -> DetSRM

Compute the Deterministic Shared Response Model.

Parameters:

Returns:

transform¶

transform(X: list[np.ndarray], y: Any | None = None, *, parallel: str | None = 'cpu', n_jobs: int = -1) -> list[np.ndarray]

Use the model to transform data to the Shared Response subspace.

Parameters:

Returns:

transform_subject¶

transform_subject(X: np.ndarray) -> np.ndarray

Transform a new subject using the existing model.

The subject is assumed to have received equivalent stimulation.

Parameters:

Returns:

HyperAlignment¶

HyperAlignment(n_iter: int = 2, auto_pad: bool = True) -> None

Bases: BaseEstimator, TransformerMixin

Hyperalignment using iterative Procrustes alignment.

Three-stage iterative process for aligning multi-subject data:

1. Create initial average template

2. Refine template through n_iter iterations

3. Final alignment of all subjects to refined template

This implements the Procrustes-based hyperalignment method commonly used in multi-subject neuroimaging analysis.

Parameters:

Parameters:

Attributes:

Methods:

Examples:

Basic multi-subject alignment:

>>> from nltools.algorithms import HyperAlignment
>>> import numpy as np
>>>
>>> # Create sample data (3 subjects)
>>> data = [np.random.randn(100, 50) for _ in range(3)]
>>>
>>> # Fit hyperalignment with CPU parallelization (default)
>>> hyper = HyperAlignment(n_iter=2)
>>> hyper.fit(data, parallel="cpu", n_jobs=-1)
>>>
>>> # Transform to common space
>>> aligned = hyper.transform(data)
>>>
>>> # Access common template
>>> template = hyper.s_  # or hyper.common_model_
>>>
>>> # Align a new subject
>>> new_subject = np.random.randn(100, 50)
>>> new_transform = hyper.transform_subject(new_subject)

Methods¶

fit¶

fit(data: list[np.ndarray], *, parallel: str | None = 'cpu', n_jobs: int = -1) -> HyperAlignment

Fit hyperalignment model to data.

Parameters:

Returns:

transform¶

transform(data: list[np.ndarray], *, parallel: str | None = 'cpu', n_jobs: int = -1) -> list[np.ndarray]

Transform data to common space using fitted transformations.

Parameters:

Returns:

transform_subject¶

transform_subject(subject_data: np.ndarray) -> tuple[np.ndarray, np.ndarray, float, float]

Align a new subject to the common space.

Parameters:

Returns:

LocalAlignment¶

LocalAlignment(spatial_scale: str = 'searchlight', method: str = 'procrustes', radius_mm: float = 10.0, roi_mask: nib.Nifti1Image | None = None, n_features: int | None = None, n_iter: int = 3, aggregation: str = 'center', parallel: str | None = 'cpu', n_jobs: int = -1, progress_bar: bool = False, n_neighborhoods_batch: int | None = None, max_memory_gb: float | None = None, transforms_: dict[int, list[np.ndarray]] | None = None, template_: dict[int, np.ndarray] | None = None, neighborhoods_: SphereNeighborhoods | dict[int, np.ndarray] | None = None, n_voxels_: int | None = None, mask_: nib.Nifti1Image | None = None, backend_: Backend | None = None) -> None

Local (neighborhood-based) functional alignment across subjects.

Learns alignment transforms within local neighborhoods (searchlight spheres or parcels) and applies center-only aggregation to preserve orthogonality.

Parameters:

Attributes:

Methods:

Examples:

>>> import numpy as np
>>> import nibabel as nib
>>> from nltools.algorithms.alignment import LocalAlignment
>>> # Create synthetic multi-subject data (voxels, samples)
>>> data = [np.random.randn(1000, 100) for _ in range(5)]
>>> # Build a mask whose nonzero voxels match the 1000-voxel data
>>> mask = nib.Nifti1Image(np.ones((10, 10, 10), dtype=np.int8), np.eye(4))
>>> la = LocalAlignment(spatial_scale='searchlight', method='procrustes', radius_mm=10.0)
>>> la.fit(data, mask)
>>> aligned = la.transform(data)

Methods¶

fit¶

fit(data: list[np.ndarray], mask: nib.Nifti1Image) -> LocalAlignment

Fit local alignment on multi-subject data.

Parameters:

Returns:

fit_transform¶

fit_transform(data: list[np.ndarray], mask: nib.Nifti1Image) -> list[np.ndarray]

Fit alignment and transform data in one step.

Parameters:

Returns:

transform¶

transform(data: list[np.ndarray]) -> list[np.ndarray]

Apply local transforms to data.

For the searchlight scale with center-only aggregation: each voxel uses the transform from the neighborhood where it was the center.

For the roi scale: all voxels in each parcel use the same transform.

Parameters:

Returns:

SRM¶

SRM(*, n_iter: int = 10, features: int = 50, rand_seed: int = 0) -> None

Bases: BaseEstimator, TransformerMixin

Probabilistic Shared Response Model (SRM).

Given multi-subject data, factorize it as a shared response S among all subjects and an orthogonal transform W per subject:

Parameters:

Attributes:

Methods:

Examples:

Basic multi-subject SRM fitting:

>>> from nltools.algorithms import SRM
>>> import numpy as np
>>>
>>> # Create sample data (3 subjects)
>>> data = [np.random.randn(100, 50) for _ in range(3)]
>>>
>>> # Fit SRM with CPU parallelization (default)
>>> srm = SRM(n_iter=10, features=50)
>>> srm.fit(data, parallel="cpu", n_jobs=-1)
>>>
>>> # Transform to shared response space
>>> shared_responses = srm.transform(data)
>>>
>>> # Access fitted model components
>>> w = srm.w_  # Subject-specific transforms
>>> s = srm.s_  # Shared response

Methods¶

fit¶

fit(X: list[np.ndarray], y: Any | None = None, *, parallel: str | None = 'cpu', n_jobs: int = -1, pad_samples: bool = True) -> SRM

Compute the probabilistic Shared Response Model.

Parameters:

Returns:

transform¶

transform(X: list[np.ndarray], y: Any | None = None, *, parallel: str | None = 'cpu', n_jobs: int = -1) -> list[np.ndarray | None]

Use the model to transform matrix to Shared Response space.

Parameters:

Returns:

transform_subject¶

transform_subject(X: np.ndarray) -> np.ndarray

Transform a new subject using the existing model.

The subject is assumed to have received equivalent stimulation.

Parameters:

Returns:

Methods¶

align¶

align(data, method = 'deterministic_srm', n_features = None, axis = 0, *args, **kwargs)

Align subject data into a common response model.

This function is a convenience wrapper around HyperAlignment and SRM classes.

Can be used to hyperalign source data to target data using Hyperalignment from Dartmouth (i.e., procrustes transformation; see nltools.algorithms.procrustes) or Shared Response Model from Princeton (see nltools.algorithms.srm). (see nltools.data.BrainData.align for aligning a single Brain object to another). Common Model is shared response model or centered target data. Transformed data can be back projected to original data using Tranformation matrix. Inputs must be a list of BrainData instances or numpy arrays (observations by features).

Parameters:

Returns:

Examples:

• Hyperalign using procrustes transform:

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

• Align using shared response model:

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

• Project aligned data into original data:

  original_data = [np.dot(t.data,tm.T) for t,tm in zip(out[‘transformed’], out[‘transformation_matrix’])]

align_states¶

align_states(reference, target, *, metric = 'correlation', return_index = False, replace_zero_variance = False)

Align state weight maps by minimizing pairwise distance between group states.

This function uses the Hungarian algorithm for state alignment, which is different from aligning multiple subjects’ data.

Parameters:

Returns: If return_index=False (default): target[:, remapping], a single ndarray of the target’s columns reordered to match the reference, oriented pattern x state (same shape as target). If return_index=True: the remapping index array (ndarray) that reorders the target’s state columns.

calc_bpm¶

calc_bpm(beat_interval, sampling_freq)

Calculate instantaneous BPM from beat to beat interval.

Parameters:

Returns:

circle_shift¶

circle_shift(data: np.ndarray, shift_amount: int | np.ndarray | None = None, random_state: int | np.random.RandomState | None = None) -> np.ndarray

Circular shift for time-series data.

Performs a circular shift that preserves autocorrelation structure. Useful for permutation tests on autocorrelated time series (e.g., fMRI). For 1D data, shifts by a single amount. For 2D data, shifts each feature (column) independently.

Parameters:

Returns:

Examples:

>>> x = np.array([1, 2, 3, 4, 5])
>>> circle_shift(x, shift_amount=2)
array([4, 5, 1, 2, 3])

>>> X = np.array([[1, 10], [2, 20], [3, 30], [4, 40]])
>>> circle_shift(X, shift_amount=np.array([1, 2]))
array([[ 4, 30],
       [ 1, 40],
       [ 2, 10],
       [ 3, 20]])

compute_multivariate_similarity¶

compute_multivariate_similarity(y, X, method = 'ols', tail = 2)

Compute multivariate similarity via OLS regression.

This is the functional core implementation for multivariate similarity computation. Used by BrainData.multivariate_similarity() to delegate computation to the functional core.

Predicts spatial distribution of y from linear combination of X columns. Computes OLS regression statistics including beta coefficients, t-statistics, p-values, and residuals.

Parameters:

Returns:

Examples:

>>> y = np.random.randn(100)
>>> X = np.random.randn(100, 5)
>>> result = compute_multivariate_similarity(y, X, method='ols')
>>> 'beta' in result
True
>>> result['beta'].shape
(6,)  # 5 predictors + intercept

compute_similarity¶

compute_similarity(data1, data2, metric = 'correlation')

Compute similarity between two data arrays.

This is the functional core implementation for similarity computation. Used by BrainData.similarity() to delegate computation to the functional core.

Parameters:

Returns:

Examples:

>>> data1 = np.random.randn(10, 100)
>>> data2 = np.random.randn(5, 100)
>>> sim = compute_similarity(data1, data2, metric='correlation')
>>> sim.shape
(10, 5)

correlation_permutation_test¶

correlation_permutation_test(data1: np.ndarray, data2: np.ndarray, *, n_permute: int = 5000, metric: str = 'pearson', tail: int | str = 2, return_null: bool = False, device: str | None = 'cpu', n_jobs: int = -1, max_gpu_memory_gb: float | None = None, random_state: int | None = None, progress_bar: bool = False) -> dict

Correlation permutation test.

Tests whether the correlation between data1 and data2 is significantly different from zero by randomly permuting data1 and computing correlations.

Assumption: Observations are independent (i.i.d.). For autocorrelated time series, use timeseries_correlation_permutation_test with circle_shift or phase_randomize methods instead.

Parameters:

Returns:

Examples:

>>> # Single feature (default CPU parallelization)
>>> x = np.random.randn(100)
>>> y = x + np.random.randn(100) * 0.5  # Correlated
>>> result = correlation_permutation_test(x, y, n_permute=5000)
>>> result['correlation']
0.85
>>> result['p']
0.001

>>> # Multi-feature (2D arrays)
>>> data1 = np.random.randn(100, 10)  # 100 samples, 10 features
>>> data2 = data1 + np.random.randn(100, 10) * 0.3  # Correlated
>>> result = correlation_permutation_test(data1, data2, n_permute=5000)
>>> result['correlation'].shape
(10,)
>>> result['p'].shape
(10,)

>>> # GPU acceleration
>>> result = correlation_permutation_test(data1, data2, n_permute=5000, device='gpu')

distance_correlation¶

distance_correlation(x: np.ndarray, y: np.ndarray, bias_corrected: bool = True, ttest: bool = False) -> dict

Compute the distance correlation between 2 arrays to test for multivariate dependence (linear or non-linear).

Arrays must match on their first dimension. It’s almost always preferable to compute the bias_corrected version which can also optionally perform a ttest. This ttest operates on a statistic thats ~dcorr^2 and will be also returned.

Explanation: Distance correlation involves computing the normalized covariance of two centered euclidean distance matrices. Each distance matrix is the euclidean distance between rows (if x or y are 2d) or scalars (if x or y are 1d). Each matrix is centered prior to computing the covariance either using double-centering or u-centering, which corrects for bias as the number of dimensions increases. U-centering is almost always preferred in all cases. It also permits inference of the normalized covariance between each distance matrix using a one-tailed directional t-test. (Szekely & Rizzo, 2013). While distance correlation is normally bounded between 0 and 1, u-centering can produce negative estimates, which are never significant.

Validated against the dcor and dcor.ttest functions in the ‘energy’ R package and the dcor.distance_correlation, dcor.udistance_correlation_sqr, and dcor.independence.distance_correlation_t_test functions in the dcor Python package.

Parameters:

Returns:

Examples:

>>> import numpy as np
>>> x = np.random.randn(20, 3)
>>> y = x + np.random.randn(20, 3) * 0.1  # Strongly correlated
>>> result = distance_correlation(x, y, bias_corrected=True)
>>> 'dcorr' in result
True
>>> 0 <= result['dcorr'] <= 1
True

double_center¶

double_center(mat: np.ndarray) -> np.ndarray

Double center a 2d array.

Double-centering subtracts row means, column means, and adds the grand mean. This centers both rows and columns around zero.

Parameters:

Returns:

Examples:

>>> mat = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]], dtype=float)
>>> result = double_center(mat)
>>> np.allclose(result.mean(axis=0), 0)
True
>>> np.allclose(result.mean(axis=1), 0)
True

downsample¶

downsample(data, *, sampling_freq = None, target = None, target_type = 'samples', method = 'mean')

Downsample a Polars DataFrame/Series to a new target frequency or number of samples using averaging.

Parameters:

Returns:

fdr¶

fdr(p, q = 0.05)

Determine an FDR threshold for an array of p-values.

Uses the desired false discovery rate q. Written by Tal Yarkoni.

Parameters:

Returns:

find_spikes¶

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

Identify spikes (motion artifacts, intensity outliers) in 4D fMRI data.

Parameters:

Returns:

fisher_r_to_z¶

fisher_r_to_z(r)

Use Fisher transformation to convert correlation to z score.

Parameters:

Returns:

fisher_z_to_r¶

fisher_z_to_r(z)

Convert Fisher z back to a correlation coefficient.

Parameters:

Returns:

glover_dispersion_derivative¶

glover_dispersion_derivative(t_r, oversampling = 50, time_length = 32.0, onset = 0.0)

Implement the Glover dispersion derivative :term:HRF model.

Parameters¶

t_r : float :term:Repetition time<TR>, in seconds (sampling period).

Returns¶

dhrf : array of shape (length / t_r * oversampling), dtype=float dhrf sampling on the oversampled time grid

Examples¶

import numpy as np from nilearn.glm.first_level import glover_dispersion_derivative ddhrf = glover_dispersion_derivative( ... t_r=2.0, oversampling=1, time_length=20.0 ... ) np.round(ddhrf, 3).tolist() [0.0, -0.0, -0.373, 0.282, 0.295, -0.04, -0.094, -0.048, -0.017, -0.005]

glover_hrf¶

glover_hrf(t_r, oversampling = 50, time_length = 32.0, onset = 0.0)

Implement the Glover :term:HRF model.

Parameters¶

t_r : float :term:Repetition time<TR>, in seconds (sampling period).

Returns¶

hrf : array of shape (length / t_r * oversampling, dtype=float) :term:HRF sampling on the oversampled time grid.

Examples¶

import numpy as np from nilearn.glm.first_level import glover_hrf hrf = glover_hrf(t_r=2.0, oversampling=1, time_length=20.0) np.round(hrf, 3).tolist() [0.0, 0.0, 0.226, 0.741, 0.5, 0.037, -0.181, -0.176, -0.103, -0.045]

glover_time_derivative¶

glover_time_derivative(t_r, oversampling = 50, time_length = 32.0, onset = 0.0)

Implement the Glover time derivative :term:HRF (dhrf) model.

Parameters¶

t_r : float :term:Repetition time<TR>, in seconds (sampling period).

Returns¶

dhrf : array of shape (length / t_r), dtype=float dhrf sampling on the provided grid

Examples¶

import numpy as np from nilearn.glm.first_level import glover_time_derivative dhrf = glover_time_derivative( ... t_r=2.0, oversampling=1, time_length=20.0 ... ) np.round(dhrf, 3).tolist() [0.0, 0.0, 0.267, 0.076, -0.215, -0.168, -0.039, 0.027, 0.033, 0.019]

holm_bonf¶

holm_bonf(p, alpha = 0.05)

Compute Holm-Bonferroni-corrected p-values.

This step-down procedure applies iteratively less correction to the highest p-values. It is a bit more conservative than FDR, but much more powerful than vanilla Bonferroni correction.

Parameters:

Returns:

isc¶

isc(data, *, n_samples = 5000, summary = 'median', method = 'bootstrap', ci_percentile = 95, exclude_self_corr = True, tail = 2, metric = 'correlation', return_null = False, n_jobs = -1, random_state = None, progress_bar = False)

Compute pairwise intersubject correlation from observations by subjects array.

This function computes pairwise intersubject correlations (ISC) using the median as recommended by Chen et al., 2016). However, if the mean is preferred, we compute the mean correlation after performing the fisher r-to-z transformation and then convert back to correlations to minimize artificially inflating the correlation values.

There are currently three different methods to compute p-values. These include the classic methods for computing permuted time-series by either circle-shifting the data or phase-randomizing the data (see Lancaster et al., 2018). These methods create random surrogate data while preserving the temporal autocorrelation inherent to the signal. By default, we use the subject-wise bootstrap method from Chen et al., 2016. Instead of recomputing the pairwise ISC using circle_shift or phase_randomization methods, this approach uses the computationally more efficient method of bootstrapping the subjects and computing a new pairwise similarity matrix with randomly selected subjects with replacement. If the same subject is selected multiple times, we set the perfect correlation to a nan with (exclude_self_corr=True). We compute the p-values using the percentile method using the same method in Brainiak.

Chen, G., Shin, Y. W., Taylor, P. A., Glen, D. R., Reynolds, R. C., Israel, R. B., & Cox, R. W. (2016). Untangling the relatedness among correlations, part I: nonparametric approaches to inter-subject correlation analysis at the group level. NeuroImage, 142, 248-259.

Hall, P., & Wilson, S. R. (1991). Two guidelines for bootstrap hypothesis testing. Biometrics, 757-762.

Lancaster, G., Iatsenko, D., Pidde, A., Ticcinelli, V., & Stefanovska, A. (2018). Surrogate data for hypothesis testing of physical systems. Physics Reports, 748, 1-60.

This function is a wrapper around isc_permutation_test from the inference module, which provides optimized implementations with CPU-parallel and GPU acceleration support.

Parameters:

Returns:

isc_group¶

isc_group(group1, group2, *, n_samples = 5000, summary = 'median', method = 'permute', ci_percentile = 95, exclude_self_corr = True, return_null = False, tail = 2, metric = 'correlation', n_jobs = -1, random_state = None, progress_bar = False)

Compute difference in intersubject correlation between groups.

This function computes pairwise intersubject correlations (ISC) using the median as recommended by Chen et al., 2016). However, if the mean is preferred, we compute the mean correlation after performing the fisher r-to-z transformation and then convert back to correlations to minimize artificially inflating the correlation values.

There are currently two different methods to compute p-values. By default, we use the subject-wise permutation method recommended Chen et al., 2016. This method combines the two groups and computes pairwise similarity both within and between the groups. Then the group labels are permuted and the mean difference between the two groups are recomputed to generate a null distribution. The second method uses subject-wise bootstrapping, where a new pairwise similarity matrix with randomly selected subjects with replacement is created separately for each group and the ISC difference between these groups is used to generate a null distribution. If the same subject is selected multiple times, we set the perfect correlation to a nan with (exclude_self_corr=True). We compute the p-values using the percentile method (Hall & Wilson, 1991).

Chen, G., Shin, Y. W., Taylor, P. A., Glen, D. R., Reynolds, R. C., Israel, R. B., & Cox, R. W. (2016). Untangling the relatedness among correlations, part I: nonparametric approaches to inter-subject correlation analysis at the group level. NeuroImage, 142, 248-259.

Hall, P., & Wilson, S. R. (1991). Two guidelines for bootstrap hypothesis testing. Biometrics, 757-762.

This function is a thin wrapper around isc_group_permutation_test from the inference module (which provides optimized CPU parallelization and optional GPU acceleration), pinning the classic pairwise behavior and the n_samples vocabulary.

Parameters:

Returns:

isc_group_permutation_test¶

isc_group_permutation_test(group1: np.ndarray, group2: np.ndarray, *, n_permute: int = 5000, summary: Literal['median', 'mean'] = 'median', method: Literal['permute', 'bootstrap'] = 'permute', summary_statistic: Literal['leave-one-out', 'pairwise'] = 'pairwise', ci_percentile: float = 95, tail: int | str = 2, device: Literal['cpu', 'gpu'] | None = 'cpu', n_jobs: int = -1, random_state: int | None = None, return_null: bool = False, progress_bar: bool = False, exclude_self_corr: bool = True, metric: str = 'correlation') -> dict[str, Any]

Compute ISC difference between groups with permutation testing.

Supports both subject-wise permutation and bootstrap methods with efficient CPU-parallel and optional GPU acceleration. Follows the statistical methods from Chen et al. (2016) for correct group comparison inference.

Parameters:

Returns:

Examples:

>>> # Single-feature ISC group comparison
>>> group1 = np.random.randn(100, 10)  # 10 subjects
>>> group2 = np.random.randn(100, 10)
>>> result = isc_group_permutation_test(group1, group2, n_permute=1000)
>>> print(f"ISC difference: {result['isc_group_difference']:.3f}, p: {result['p']:.3f}")

>>> # Voxel-wise ISC group comparison with GPU acceleration
>>> group1_voxels = np.random.randn(100, 10, 5000)  # 5K voxels
>>> group2_voxels = np.random.randn(100, 10, 5000)
>>> result = isc_group_permutation_test(
...     group1_voxels,
...     group2_voxels,
...     summary_statistic='leave-one-out',
...     device='gpu',  # GPU for LOO computation
...     n_permute=5000
... )
>>> print(f"Significant voxels: {(result['p'] < 0.05).sum()}")

isc_permutation_test¶

isc_permutation_test(data: np.ndarray, *, n_permute: int = 5000, summary: Literal['median', 'mean'] = 'median', summary_statistic: Literal['leave-one-out', 'pairwise'] = 'pairwise', method: Literal['bootstrap', 'circle_shift', 'phase_randomize'] = 'bootstrap', ci_percentile: float = 95, tail: int | str = 2, return_null: bool = False, progress_bar: bool = False, exclude_self_corr: bool = True, metric: str = 'correlation', device: Literal['cpu', 'gpu'] | None = 'cpu', n_jobs: int = -1, max_gpu_memory_gb: float | None = None, random_state: int | None = None) -> dict[str, Any]

Compute intersubject correlation with permutation testing.

Supports both leave-one-out and pairwise ISC computation modes with GPU acceleration for large voxel-wise problems and CPU-parallel bootstrap resampling.

Parameters:

Returns:

Examples:

>>> # Single-feature ISC
>>> data = np.random.randn(100, 10)  # 100 timepoints, 10 subjects
>>> result = isc_permutation_test(data, n_permute=1000)
>>> print(f"ISC: {result['isc']:.3f}, p: {result['p']:.3f}")

>>> # Voxel-wise ISC with GPU acceleration
>>> data_voxels = np.random.randn(100, 50, 5000)  # 5K voxels
>>> result = isc_permutation_test(
...     data_voxels,
...     summary_statistic='leave-one-out',
...     device='gpu',  # GPU for LOO computation
...     n_permute=5000
... )
>>> print(f"Significant voxels: {(result['p'] < 0.05).sum()}")

>>> # Compare LOO vs pairwise
>>> result_loo = isc_permutation_test(data, summary_statistic='leave-one-out')
>>> result_pair = isc_permutation_test(data, summary_statistic='pairwise')
>>> print(f"LOO: {result_loo['isc']:.3f}, Pairwise: {result_pair['isc']:.3f}")

isfc¶

isfc(data, method = 'average', n_jobs = -1)

Compute intersubject functional connectivity (ISFC) from a list of observation x feature matrices.

This function uses the leave one out approach to compute ISFC (Simony et al., 2016). For each subject, compute the cross-correlation between each voxel/roi with the average of the rest of the subjects data. In other words, compute the mean voxel/ROI response for all participants except the target subject. Then compute the correlation between each ROI within the target subject with the mean ROI response in the group average.

Simony, E., Honey, C. J., Chen, J., Lositsky, O., Yeshurun, Y., Wiesel, A., & Hasson, U. (2016). Dynamic reconfiguration of the default mode network during narrative comprehension. Nature communications, 7, 12141.

This function now uses the optimized implementation from the inference module, which provides efficient cross-correlation computation between matrix columns. CPU parallelization is available via joblib when n_jobs > 1 or n_jobs=-1. Each subject’s ISFC computation is independent and can be parallelized efficiently.

Parameters:

Returns:

isps¶

isps(data, *, sampling_freq = 0.5, low_cut = 0.04, high_cut = 0.07, order = 5, pairwise = False)

Compute dynamic intersubject phase synchrony (ISPS) from an observations-by-subjects array.

This function computes the instantaneous intersubject phase synchrony for a single voxel/roi timeseries. Requires multiple subjects. This method is largely based on that described by Glerean et al., 2012 and performs a hilbert transform on narrow bandpass filtered timeseries (butterworth) data to get the instantaneous phase angle. The function returns a dictionary containing the average phase angle, the average vector length, and parametric p-values computed using the rayleigh test using circular statistics (Fisher, 1993). If pairwise=True, then it will compute these on the pairwise phase angle differences, if pairwise=False, it will compute these on the actual phase angles. This is called inter-site phase coupling or inter-trial phase coupling respectively in the EEG literatures.

This function requires narrow band filtering your data. As a default we use the recommendations by (Glerean et al., 2012) of .04-.07Hz. This is similar to the “slow-4” band (0.025–0.067 Hz) described by (Zuo et al., 2010; Penttonen & Buzsáki, 2003), but excludes the .03 band, which has been demonstrated to contain aliased respiration signals (Birn, 2006).

Birn RM, Smith MA, Bandettini PA, Diamond JB. 2006. Separating respiratory-variation-related fluctuations from neuronal-activity- related fluctuations in fMRI. Neuroimage 31:1536–1548.

Buzsáki, G., & Draguhn, A. (2004). Neuronal oscillations in cortical networks. Science, 304(5679), 1926-1929.

Fisher, N. I. (1995). Statistical analysis of circular data. cambridge university press.

Glerean, E., Salmi, J., Lahnakoski, J. M., Jääskeläinen, I. P., & Sams, M. (2012). Functional magnetic resonance imaging phase synchronization as a measure of dynamic functional connectivity. Brain connectivity, 2(2), 91-101.

Parameters:

Returns:

make_cosine_basis¶

make_cosine_basis(nsamples, sampling_freq, filter_length, unit_scale = True, drop = 0)

Create basis functions for a discrete cosine transform.

Based on the implementation in spm_filter and spm_dctmtx because scipy DCT can only apply transforms but not return the basis functions. Like SPM, this does not add a constant (i.e. intercept), but does retain the first basis (i.e. sigmoidal/linear drift).

Parameters:

Returns:

matrix_permutation_test¶

matrix_permutation_test(data1: np.ndarray, data2: np.ndarray, *, n_permute: int = 5000, metric: str = 'pearson', how: str = 'upper', include_diag: bool = False, tail: int | str = 2, return_null: bool = False, device: str | None = 'cpu', n_jobs: int = -1, random_state: int | None = None, progress_bar: bool = False) -> dict

Matrix permutation test (Mantel test) for correlating two square matrices.

Tests whether the correlation between elements of two matrices is significant by permuting rows and columns of one matrix symmetrically while keeping the other fixed.

Statistical Method: For each permutation, create random permutation perm, then apply: matrix1[perm][:, perm]. This preserves matrix structure while destroying correlation. Count how often permuted correlation is as extreme as observed.

Assumptions:

• Matrices are square and same size

• Under H₀, row/column ordering is exchangeable

• Symmetric permutation preserves matrix properties (e.g., symmetry)

Parameters:

Returns:

Examples:

>>> import numpy as np
>>> from nltools.algorithms.inference import matrix_permutation_test
>>>
>>> # Create two correlated similarity matrices
>>> np.random.seed(42)
>>> n = 50
>>> true_pattern = np.random.randn(n)
>>> data1 = np.corrcoef(true_pattern + np.random.randn(n) * 0.1)
>>> data2 = np.corrcoef(true_pattern + np.random.randn(n) * 0.1)
>>>
>>> # Test if matrices are correlated
>>> result = matrix_permutation_test(data1, data2, n_permute=1000)
>>> print(f"Correlation: {result['correlation']:.3f}, p = {result['p']:.4f}")

multi_threshold¶

multi_threshold(t_map, p_map, thresh)

Threshold test image by multiple p-values from p image.

Parameters:

Returns:

one_sample_permutation_test¶

one_sample_permutation_test(data: np.ndarray, *, n_permute: int = 5000, tail: int | str = 2, return_null: bool = False, device: str | None = 'cpu', n_jobs: int = -1, max_gpu_memory_gb: float | None = None, random_state: int | None = None, progress_bar: bool = False) -> dict

One-sample permutation test using sign-flipping.

Tests whether the mean of data is significantly different from zero by randomly flipping the sign of each observation. This is the permutation test equivalent of a one-sample t-test.

Assumption: Symmetric error distribution around zero. For highly skewed distributions, consider alternative methods (e.g., bootstrap resampling).

Parameters:

Returns:

Examples:

>>> # Single feature (default CPU parallelization)
>>> data = np.random.randn(30)
>>> result = one_sample_permutation_test(data, n_permute=5000)
>>> result['p']
0.23

>>> # Voxel-wise test with GPU
>>> data = np.random.randn(30, 10000)  # 30 subjects, 10K voxels
>>> result = one_sample_permutation_test(data, n_permute=5000, device='gpu')
>>> result['mean'].shape
(10000,)
>>> result['p'].shape
(10000,)

>>> # Single-threaded (for debugging)
>>> result = one_sample_permutation_test(data, n_permute=5000, device=None)

phase_randomize¶

phase_randomize(data: np.ndarray, *, device: str | None = 'cpu', random_state: int | np.random.RandomState | None = None) -> np.ndarray

FFT-based phase randomization for time-series data.

Preserves the power spectrum (autocorrelation) but destroys nonlinear temporal structure by randomizing Fourier phases. Used to test whether data was generated by a linear Gaussian process or contains nonlinear dynamics.

Parameters:

Returns:

Examples:

>>> x = np.sin(np.linspace(0, 10*np.pi, 100))  # Sine wave
>>> x_rand = phase_randomize(x, random_state=42)
>>> # Power spectrum preserved:
>>> np.allclose(np.abs(np.fft.rfft(x))**2, np.abs(np.fft.rfft(x_rand))**2)
True

>>> # GPU acceleration for large datasets:
>>> x_large = np.random.randn(10000)
>>> x_rand_gpu = phase_randomize(x_large, device='gpu', random_state=42)

procrustes_distance¶

procrustes_distance(mat1, mat2, *, n_permute = 5000, tail = 2, n_jobs = -1, random_state = None)

Test matrix similarity using Procrustes superposition.

Matrices need to match in size on their first dimension only, as the smaller matrix on the second dimension will be padded with zeros. After aligning two matrices using the Procrustes transformation, use the computed disparity between them (sum of squared error of elements) as a similarity metric. Shuffle the rows of one of the matrices and recompute the disparity to perform inference (Peres-Neto & Jackson, 2001).

Parameters:

Returns:

regress¶

regress(X, Y, *, method: str = 'ols', stats: str = 'full', tail: int | str = 2)

Fit an OLS regression of Y on X.

Does not add an intercept — include one in X explicitly. If Y is 2D, a separate regression is fit to each column.

Parameters:

Returns:

ridge_cv¶

ridge_cv(X: np.ndarray, y: np.ndarray, *, alphas: np.ndarray | None = None, cv: int | BaseCrossValidator = 5, fit_intercept: bool = False, parallel: str | None = 'cpu', max_gpu_memory_gb: float | None = None, random_state: int | None = None) -> dict

Ridge regression with cross-validation for hyperparameter selection.

Performs k-fold cross-validation to select the best alpha parameter, then fits a final model on all data using the selected alpha.

Parameters:

Returns:

Examples:

>>> X = np.random.randn(100, 50)
>>> y = np.random.randn(100)
>>> result = ridge_cv(X, y, cv=3)
>>> result['alpha']  # Best alpha selected
1.0
>>> result['coef'].shape
(50,)

ridge_svd¶

ridge_svd(X: np.ndarray, y: np.ndarray, *, alpha: float = 1.0, parallel: str | None = None, max_gpu_memory_gb: float | None = None, random_state: int | None = None) -> np.ndarray

Solve ridge regression using Singular Value Decomposition.

This function implements ridge regression using SVD, which provides numerical stability and efficiency for high-dimensional problems. The implementation is inspired by the himalaya library.

Parameters:

Returns:

Examples:

>>> X = np.random.randn(100, 50)
>>> y = np.random.randn(100)
>>> beta = ridge_svd(X, y, alpha=1.0)
>>> beta.shape
(50,)

>>> # Multi-target regression
>>> Y = np.random.randn(100, 5)
>>> beta = ridge_svd(X, Y, alpha=1.0)
>>> beta.shape
(50, 5)

spm_dispersion_derivative¶

spm_dispersion_derivative(t_r, oversampling = 50, time_length = 32.0, onset = 0.0)

Implement the :term:SPM dispersion derivative :term:HRF model.

Parameters¶

t_r : float :term:Repetition time<TR>, in seconds (sampling period).

Returns¶

dhrf : array of shape (length / tr * oversampling), dtype=float dhrf sampling on the oversampled time grid

Examples¶

import numpy as np from nilearn.glm.first_level import glover_dispersion_derivative ddhrf = glover_dispersion_derivative( ... t_r=2.0, oversampling=1, time_length=20.0 ... ) np.round(ddhrf, 3).tolist() [0.0, -0.0, -0.373, 0.282, 0.295, -0.04, -0.094, -0.048, -0.017, -0.005]

spm_hrf¶

spm_hrf(t_r, oversampling = 50, time_length = 32.0, onset = 0.0)

Implement the :term:SPM :term:HRF model.

Parameters¶

t_r : float :term:Repetition time<TR>, in seconds (sampling period).

Returns¶

hrf : array of shape (length / t_r * oversampling, dtype=float) :term:HRF sampling on the oversampled time grid

Examples¶

import numpy as np from nilearn.glm.first_level import spm_hrf hrf = spm_hrf(t_r=2.0, oversampling=1, time_length=20.0) np.round(hrf, 3).tolist() [0.0, 0.0, 0.161, 0.443, 0.335, 0.139, 0.022, -0.028, -0.04, -0.033]

spm_time_derivative¶

spm_time_derivative(t_r, oversampling = 50, time_length = 32.0, onset = 0.0)

Implement the :term:SPM time derivative :term:HRF (dhrf) model.

Parameters¶

t_r : float :term:Repetition time<TR>, in seconds (sampling period).

Returns¶

dhrf : array of shape (length / t_r, dtype=float) dhrf sampling on the provided grid

Examples¶

import numpy as np from nilearn.glm.first_level import spm_time_derivative dhrf = spm_time_derivative(t_r=2.0, oversampling=1, time_length=20.0) np.round(dhrf, 3).tolist() [0.0, 0.0, 0.167, 0.04, -0.091, -0.072, -0.035, -0.013, -0.0, 0.005]

threshold¶

threshold(stat, p, thr = 0.05, return_mask = False)

Threshold test image by p-value from p image.

Parameters:

Returns:

timeseries_correlation_permutation_test¶

timeseries_correlation_permutation_test(data1: np.ndarray, data2: np.ndarray, *, method: Literal['circle_shift', 'phase_randomize'] = 'circle_shift', n_permute: int = 5000, metric: Literal['pearson', 'spearman', 'kendall'] = 'pearson', tail: int | str = 2, device: str | None = 'cpu', n_jobs: int = -1, max_gpu_memory_gb: float | None = None, return_null: bool = False, random_state: int | np.random.RandomState | None = None, progress_bar: bool = False) -> dict

Time-series correlation permutation test.

Unlike standard permutation tests that shuffle data independently, this test uses time-series-aware permutation methods that preserve temporal structure (circle_shift) or power spectrum (phase_randomize).

Use this test when data contains temporal autocorrelation. Standard permutation tests inflate Type I error for autocorrelated data.

Parameters:

Returns:

Examples:

>>> x = np.sin(np.linspace(0, 10*np.pi, 100))
>>> y = np.cos(np.linspace(0, 10*np.pi, 100))
>>> result = timeseries_correlation_permutation_test(
...     x, y, method='circle_shift', n_permute=1000, random_state=42
... )
>>> result['correlation']  # Strong negative correlation
-0.999...
>>> result['p'] < 0.05  # Significant
True

>>> # GPU acceleration
>>> result = timeseries_correlation_permutation_test(
...     x, y, method='phase_randomize', device='gpu', n_permute=5000
... )

transform_pairwise¶

transform_pairwise(X, y)

Transform data into pairs with balanced labels for ranking.

Transforms a n-class ranking problem into a two-class classification problem. Subclasses implementing particular strategies for choosing pairs should override this method. In this method, all pairs are choosen, except for those that have the same target value. The output is an array of balanced classes, i.e. there are the same number of -1 as +1

Reference: “Large Margin Rank Boundaries for Ordinal Regression”, R. Herbrich, T. Graepel, K. Obermayer. Authors: Fabian Pedregosa fabian@fseoane.net Alexandre Gramfort alexandre.gramfort@inria.fr

Parameters:

Returns:

trim¶

trim(data, cutoff = None)

Trim a Polars DataFrame/Series by replacing outlier values with NaNs.

Parameters:

Returns: out: (pl.DataFrame, pl.Series) trimmed data (same type as input)

two_sample_permutation_test¶

two_sample_permutation_test(data1: np.ndarray, data2: np.ndarray, *, n_permute: int = 5000, tail: int | str = 2, return_null: bool = False, device: str | None = 'cpu', n_jobs: int = -1, max_gpu_memory_gb: float | None = None, random_state: int | None = None, progress_bar: bool = False) -> dict

Two-sample permutation test using group label shuffling.

Tests whether two independent groups have different means by randomly permuting group labels. This is the permutation test equivalent of an independent samples t-test.

Assumption: Exchangeability under the null hypothesis (group assignments are arbitrary). Valid for independent samples from similar distributions.

Parameters:

Returns:

Examples:

>>> # Single feature (default CPU parallelization)
>>> data1 = np.random.randn(20)  # Group 1: 20 subjects
>>> data2 = np.random.randn(25)  # Group 2: 25 subjects
>>> result = two_sample_permutation_test(data1, data2, n_permute=5000)
>>> result['p']
0.45

>>> # Voxel-wise test with GPU
>>> data1 = np.random.randn(20, 10000)  # 20 subjects, 10K voxels
>>> data2 = np.random.randn(25, 10000)  # 25 subjects, 10K voxels
>>> result = two_sample_permutation_test(data1, data2, n_permute=5000, device='gpu')
>>> result['mean_diff'].shape
(10000,)
>>> result['p'].shape
(10000,)

>>> # Single-threaded (for debugging)
>>> result = two_sample_permutation_test(data1, data2, n_permute=5000, device=None)

u_center¶

u_center(mat: np.ndarray) -> np.ndarray

U-center a 2d array. U-centering is a bias-corrected form of double-centering.

U-centering corrects for bias that occurs with double-centering as the number of dimensions increases. The diagonal is explicitly set to zero.

Parameters:

Returns:

Examples:

>>> mat = np.random.randn(5, 5)
>>> result = u_center(mat)
>>> np.allclose(np.diag(result), 0)
True

upsample¶

upsample(data, *, sampling_freq = None, target = None, target_type = 'samples', method = 'linear')

Upsample a Polars DataFrame/Series to a new target frequency or number of samples using interpolation.

Parameters:

Returns: upsampled Polars DataFrame or Series (same type as input)

winsorize¶

winsorize(data, cutoff = None, replace_with_cutoff = True)

Winsorize a Polars DataFrame/Series with the largest/lowest value not considered outlier.

Parameters:

Returns: out: (pl.DataFrame, pl.Series) winsorized data (same type as input)

zscore¶

zscore(data)

Z-score every column of a Polars or pandas DataFrame/Series.

Accepts pandas inputs at the boundary for convenience and converts to Polars internally. Always returns Polars output (DataFrame or Series, matching the input shape).

Parameters:

Returns:

Modules¶

alignment¶

Multi-subject functional alignment algorithms.

This package provides algorithms for aligning functional data across subjects:

• LocalAlignment: Searchlight/ROI-scale alignment (Bazeille et al. 2021)

• HyperAlignment: Iterative Procrustes alignment (Haxby et al. 2011)

• SRM / DetSRM: Shared Response Model (Chen et al. 2015)

• align / procrustes / procrustes_distance / align_states: functional entry points for whole-brain alignment (SRM or Procrustes)

Classes:

Methods:

Modules:

Classes¶

DetSRM¶

DetSRM(*, n_iter: int = 10, features: int = 50, rand_seed: int = 0) -> None

Bases: BaseEstimator, TransformerMixin

Deterministic Shared Response Model (DetSRM).

Given multi-subject data, factorize it as a shared response S among all subjects and an orthogonal transform W per subject:

Parameters:

Attributes:

Methods:

####### Attributes##

Examples:

Basic multi-subject DetSRM fitting:

>>> from nltools.algorithms import DetSRM
>>> import numpy as np
>>>
>>> # Create sample data (3 subjects)
>>> data = [np.random.randn(100, 50) for _ in range(3)]
>>>
>>> # Fit DetSRM with CPU parallelization (default)
>>> detsrm = DetSRM(n_iter=10, features=50)
>>> detsrm.fit(data, parallel="cpu", n_jobs=-1)
>>>
>>> # Transform to shared response space
>>> shared_responses = detsrm.transform(data)
>>>
>>> # Access fitted model components
>>> w = detsrm.w_  # Subject-specific transforms
>>> s = detsrm.s_  # Shared response

features¶

features = features

######## n_iter

n_iter = n_iter

######## rand_seed

rand_seed = rand_seed

####### Functions##

fit¶

fit(X: list[np.ndarray], y: Any | None = None, *, parallel: str | None = 'cpu', n_jobs: int = -1) -> DetSRM

Compute the Deterministic Shared Response Model.

Parameters:

Parameters:

Parameters:

Returns:

######## transform

transform(X: list[np.ndarray], y: Any | None = None, *, parallel: str | None = 'cpu', n_jobs: int = -1) -> list[np.ndarray]

Use the model to transform data to the Shared Response subspace.

Returns:

######## transform_subject

transform_subject(X: np.ndarray) -> np.ndarray

Transform a new subject using the existing model.

The subject is assumed to have received equivalent stimulation.

Returns:

HyperAlignment¶

HyperAlignment(n_iter: int = 2, auto_pad: bool = True) -> None

Bases: BaseEstimator, TransformerMixin

Hyperalignment using iterative Procrustes alignment.

Three-stage iterative process for aligning multi-subject data:

1. Create initial average template

2. Refine template through n_iter iterations

3. Final alignment of all subjects to refined template

This implements the Procrustes-based hyperalignment method commonly used in multi-subject neuroimaging analysis.

Parameters:

Parameters:

####### Attributes##

Attributes:

Methods:

Examples:

Basic multi-subject alignment:

>>> from nltools.algorithms import HyperAlignment
>>> import numpy as np
>>>
>>> # Create sample data (3 subjects)
>>> data = [np.random.randn(100, 50) for _ in range(3)]
>>>
>>> # Fit hyperalignment with CPU parallelization (default)
>>> hyper = HyperAlignment(n_iter=2)
>>> hyper.fit(data, parallel="cpu", n_jobs=-1)
>>>
>>> # Transform to common space
>>> aligned = hyper.transform(data)
>>>
>>> # Access common template
>>> template = hyper.s_  # or hyper.common_model_
>>>
>>> # Align a new subject
>>> new_subject = np.random.randn(100, 50)
>>> new_transform = hyper.transform_subject(new_subject)

auto_pad¶

auto_pad = auto_pad

######## common_model_

common_model_

Alias for s_ (common template).

######## n_iter

n_iter = n_iter

####### Functions##

fit¶

fit(data: list[np.ndarray], *, parallel: str | None = 'cpu', n_jobs: int = -1) -> HyperAlignment

Fit hyperalignment model to data.

Parameters:

Parameters:

Parameters:

Returns:

######## transform

transform(data: list[np.ndarray], *, parallel: str | None = 'cpu', n_jobs: int = -1) -> list[np.ndarray]

Transform data to common space using fitted transformations.

Returns:

######## transform_subject

transform_subject(subject_data: np.ndarray) -> tuple[np.ndarray, np.ndarray, float, float]

Align a new subject to the common space.

Returns:

LocalAlignment¶

LocalAlignment(spatial_scale: str = 'searchlight', method: str = 'procrustes', radius_mm: float = 10.0, roi_mask: nib.Nifti1Image | None = None, n_features: int | None = None, n_iter: int = 3, aggregation: str = 'center', parallel: str | None = 'cpu', n_jobs: int = -1, progress_bar: bool = False, n_neighborhoods_batch: int | None = None, max_memory_gb: float | None = None, transforms_: dict[int, list[np.ndarray]] | None = None, template_: dict[int, np.ndarray] | None = None, neighborhoods_: SphereNeighborhoods | dict[int, np.ndarray] | None = None, n_voxels_: int | None = None, mask_: nib.Nifti1Image | None = None, backend_: Backend | None = None) -> None

Local (neighborhood-based) functional alignment across subjects.

Learns alignment transforms within local neighborhoods (searchlight spheres or parcels) and applies center-only aggregation to preserve orthogonality.

Parameters:

Attributes:

Methods:

####### Attributes##

Examples:

>>> import numpy as np
>>> import nibabel as nib
>>> from nltools.algorithms.alignment import LocalAlignment
>>> # Create synthetic multi-subject data (voxels, samples)
>>> data = [np.random.randn(1000, 100) for _ in range(5)]
>>> # Build a mask whose nonzero voxels match the 1000-voxel data
>>> mask = nib.Nifti1Image(np.ones((10, 10, 10), dtype=np.int8), np.eye(4))
>>> la = LocalAlignment(spatial_scale='searchlight', method='procrustes', radius_mm=10.0)
>>> la.fit(data, mask)
>>> aligned = la.transform(data)

aggregation¶

aggregation: str = 'center'

######## backend_

backend_: Backend | None = field(default=None, repr=False)

######## mask_

mask_: nib.Nifti1Image | None = field(default=None, repr=False)

######## max_memory_gb

max_memory_gb: float | None = None

######## method

method: str = 'procrustes'

######## n_features

n_features: int | None = None

######## n_iter

n_iter: int = 3

######## n_jobs

n_jobs: int = -1

######## n_neighborhoods_batch

n_neighborhoods_batch: int | None = None

######## n_voxels_

n_voxels_: int | None = field(default=None, repr=False)

######## neighborhoods_

neighborhoods_: SphereNeighborhoods | dict[int, np.ndarray] | None = field(default=None, repr=False)

######## parallel

parallel: str | None = 'cpu'

######## progress_bar

progress_bar: bool = False

######## radius_mm

radius_mm: float = 10.0

######## roi_mask

roi_mask: nib.Nifti1Image | None = None

######## spatial_scale

spatial_scale: str = 'searchlight'

######## template_

template_: dict[int, np.ndarray] | None = field(default=None, repr=False)

######## transforms_

transforms_: dict[int, list[np.ndarray]] | None = field(default=None, repr=False)

####### Functions##

fit¶

fit(data: list[np.ndarray], mask: nib.Nifti1Image) -> LocalAlignment

Fit local alignment on multi-subject data.

Parameters:

Parameters:

Parameters:

Returns:

######## fit_transform

fit_transform(data: list[np.ndarray], mask: nib.Nifti1Image) -> list[np.ndarray]

Fit alignment and transform data in one step.

Returns:

######## transform

transform(data: list[np.ndarray]) -> list[np.ndarray]

Apply local transforms to data.

For the searchlight scale with center-only aggregation: each voxel uses the transform from the neighborhood where it was the center.

For the roi scale: all voxels in each parcel use the same transform.

Returns:

SRM¶

SRM(*, n_iter: int = 10, features: int = 50, rand_seed: int = 0) -> None

Bases: BaseEstimator, TransformerMixin

Probabilistic Shared Response Model (SRM).

Given multi-subject data, factorize it as a shared response S among all subjects and an orthogonal transform W per subject:

Parameters:

Attributes:

Methods:

####### Attributes##

Examples:

Basic multi-subject SRM fitting:

>>> from nltools.algorithms import SRM
>>> import numpy as np
>>>
>>> # Create sample data (3 subjects)
>>> data = [np.random.randn(100, 50) for _ in range(3)]
>>>
>>> # Fit SRM with CPU parallelization (default)
>>> srm = SRM(n_iter=10, features=50)
>>> srm.fit(data, parallel="cpu", n_jobs=-1)
>>>
>>> # Transform to shared response space
>>> shared_responses = srm.transform(data)
>>>
>>> # Access fitted model components
>>> w = srm.w_  # Subject-specific transforms
>>> s = srm.s_  # Shared response

features¶

features = features

######## n_iter

n_iter = n_iter

######## rand_seed

rand_seed = rand_seed

####### Functions##

fit¶

fit(X: list[np.ndarray], y: Any | None = None, *, parallel: str | None = 'cpu', n_jobs: int = -1, pad_samples: bool = True) -> SRM

Compute the probabilistic Shared Response Model.

Parameters:

Parameters:

Parameters:

Returns:

######## transform

transform(X: list[np.ndarray], y: Any | None = None, *, parallel: str | None = 'cpu', n_jobs: int = -1) -> list[np.ndarray | None]

Use the model to transform matrix to Shared Response space.

Returns:

######## transform_subject

transform_subject(X: np.ndarray) -> np.ndarray

Transform a new subject using the existing model.

The subject is assumed to have received equivalent stimulation.

Returns:

Methods¶

align¶

align(data, method = 'deterministic_srm', n_features = None, axis = 0, *args, **kwargs)

Align subject data into a common response model.

This function is a convenience wrapper around HyperAlignment and SRM classes.

Can be used to hyperalign source data to target data using Hyperalignment from Dartmouth (i.e., procrustes transformation; see nltools.algorithms.procrustes) or Shared Response Model from Princeton (see nltools.algorithms.srm). (see nltools.data.BrainData.align for aligning a single Brain object to another). Common Model is shared response model or centered target data. Transformed data can be back projected to original data using Tranformation matrix. Inputs must be a list of BrainData instances or numpy arrays (observations by features).

Parameters:

Returns:

Examples:

• Hyperalign using procrustes transform:

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

• Align using shared response model:

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

• Project aligned data into original data:

  original_data = [np.dot(t.data,tm.T) for t,tm in zip(out[‘transformed’], out[‘transformation_matrix’])]

align_states¶

align_states(reference, target, *, metric = 'correlation', return_index = False, replace_zero_variance = False)

Align state weight maps by minimizing pairwise distance between group states.

This function uses the Hungarian algorithm for state alignment, which is different from aligning multiple subjects’ data.

Parameters:

Returns: If return_index=False (default): target[:, remapping], a single ndarray of the target’s columns reordered to match the reference, oriented pattern x state (same shape as target). If return_index=True: the remapping index array (ndarray) that reorders the target’s state columns.

procrustes_distance¶

procrustes_distance(mat1, mat2, *, n_permute = 5000, tail = 2, n_jobs = -1, random_state = None)

Test matrix similarity using Procrustes superposition.

Matrices need to match in size on their first dimension only, as the smaller matrix on the second dimension will be padded with zeros. After aligning two matrices using the Procrustes transformation, use the computed disparity between them (sum of squared error of elements) as a similarity metric. Shuffle the rows of one of the matrices and recompute the disparity to perform inference (Peres-Neto & Jackson, 2001).

Parameters: