nltools.algorithms¶

Subjects to align; all elements must be the same type. Arrays are observations x features.

One of 'probabilistic_srm', 'deterministic_srm', or 'procrustes'. Defaults to 'deterministic_srm'.

Number of features in the common space (SRM only). None uses the smallest subject's size along the aligned axis (voxels for axis=0), the largest value every subject can support; an explicit value may not exceed that size for any subject. Must be None for 'procrustes'.

Axis to align on: 0 aligns timepoints (ISC computed per voxel), 1 aligns voxels (ISC computed per timepoint). Defaults to 0.

Number of _SRM/_DetSRM iterations; ignored by method='procrustes'. Defaults to 10.

Seed forwarded to the constructed _SRM/_DetSRM; ignored by method='procrustes'. Defaults to 0.

Keys 'transformed' (list of aligned subject data, same type as the input), 'transformation_matrix' (per-subject transforms, in the transformed = original @ T orientation on every input type, so back-projection is transformed @ T.T), 'common_model' (shared response or group template), and 'isc' (dict mapping each aligned unit to its mean intersubject correlation). With method='procrustes' also 'disparity' and 'scale'.

If data is not a same-typed list, method or axis is unknown, method='procrustes' is combined with axis=1 on BrainData input — that transform spans images on both axes and has no voxel axis to be returned on — or method='procrustes' is given BrainData subjects with different voxel counts, whose zero-padded results would not fit their own masks. Pass the subjects' .data arrays to get the zero-padded result instead; it has no mask that could describe it. An SRM n_features above any subject's voxel count also raises.

Reference pattern x state matrix.

Target pattern x state matrix to align to reference; must have the same shape.

Distance metric passed to sklearn.metrics.pairwise_distances. Defaults to 'correlation'.

If True return the remapping index instead of the reordered data. Defaults to False.

Replace zero-variance columns with uniform random numbers before computing distances; avoids NaNs with the correlation metric. Integer inputs are converted to float so the replacement noise survives. Defaults to False.

If return_index=False (default), target[:, remapping] — 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 that reorders the target's state columns.

Number of samples between beats (typically the R-R interval).

Sampling frequency in Hz.

Beats per minute for the time interval.

(available, info). available is True when a CUDA or MPS device is usable. info has keys 'backend' ('torch' or 'numpy'), 'device' ('cpu', 'cuda', or 'mps'), and 'device_name' (human-readable device name).

Time series, shape (n_samples,) or (n_samples, n_features).

Shift amount: an int for 1D data, or an array of length n_features (one shift per column) for 2D data. Shifts wrap, so a shift at or beyond the series length is the same as its remainder. None draws random shift(s). Defaults to None.

Random seed used when shift_amount is None.

Circularly shifted data with the same shape as the input.

NIfTI mask image defining the brain region

Radius of spheres in millimeters (default: 10.0)

_SphereNeighborhoods with precomputed adjacency matrix

If the mask is not 3-D, or has no non-zero voxels

First data array, shape (n_samples1, n_features).

Second data array, shape (n_samples2, n_features).

'correlation' (or 'pearson'), 'spearman' (or 'rank_correlation'), 'dot_product', or 'cosine'. Defaults to 'correlation'.

Similarities of shape (n_samples1, n_samples2), squeezed: a 1D array when either input has a single row, a scalar when both do.

Data to permute, shape (n_samples,) for a single feature or (n_samples, n_features) for several.

Data to correlate with, same shape as data1.

Number of permutations. Defaults to 5000.

'pearson' (linear), 'spearman' (rank-based, monotonic), or 'kendall' (tau-b, ordinal association, tie-corrected). Defaults to 'pearson'.

2 or 'two' for a two-tailed test (r != 0); 1 or 'one' for a one-tailed test of r > 0 (negate one variable for the other direction; the fixed direction keeps multiple-comparison correction valid). Defaults to 2.

Also return the full null distribution. Defaults to False.

Number of joblib workers, -1 = all cores. Defaults to -1. Results are identical at every worker count.

Random seed for reproducibility.

Show a progress bar over permutations. Defaults to False.

Keys 'correlation' (float, or np.ndarray of shape (n_features,) for 2D inputs: the observed correlation), 'p' (float or np.ndarray, the matching p-values), and 'null_dist' (np.ndarray of shape (n_permute,) or (n_permute, n_features)) when return_null=True.

1d or 2d array of observations by features.

1d or 2d array of observations by features.

If True, U-center the distance matrices; if False, double-center them, which gives a biased estimate that converges to 1 as the number of dimensions grows. Must be True when ttest=True. Defaults to True.

Perform a t-test on the bias-corrected distance correlation. Defaults to False.

Key 'dcorr' (float, distance correlation); with bias_corrected=True also 'dcorr_squared' (float, the U-centered statistic, which can be negative); with ttest=True also 't', 'p', and 'df'.

If arrays are not 1d or 2d, or if ttest=True and bias_corrected=False.

Data to downsample.

Sampling frequency of the data in Hz.

Downsampling target.

Unit of target, one of 'samples', 'seconds', or 'hz'. Defaults to 'samples'.

Aggregation within each bin, 'mean' or 'median'. Defaults to 'mean'.

Downsampled data (same type as input).

Vector of p-values.

False discovery rate level. Defaults to 0.05.

The p-value threshold; -1 when no p-value survives correction.

4D functional data.

Cutoff in standard deviations for spikes in the per-TR global mean signal; None skips this detector. Defaults to 3.

Cutoff in standard deviations for spikes in the per-TR mean absolute frame-to-frame difference; None skips this detector. The difference is attributed to the later of the two volumes, as framewise displacement is. Defaults to 3.

Repetition time in seconds; sets the returned DesignMatrix's sampling_freq for downstream .append() / .convolve(). Pass at most one of TR and sampling_freq.

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

One indicator column per detected spike TR, named .nl_global_spike{n} / .nl_diff_spike{n} in the reserved namespace for generated columns (see RESERVED_PREFIX) and pre-marked as confounds. Row position is the time axis. A volume flagged by both detectors yields identical one-hot columns, so only the .nl_global_spike* one is kept. Without TR / sampling_freq the result has sampling_freq=None and can still be appended to a DesignMatrix that has one.

If both cutoffs are None, if data is neither a BrainData nor a nibabel.Nifti1Image, if a NIfTI is not 4-D once trailing singleton axes are dropped, or if both TR and sampling_freq are given.

Correlation coefficient(s).

Fisher z-transformed correlation(s).

Fisher z value(s).

Correlation coefficient(s).

Vector of p-values.

Family-wise alpha level. Defaults to 0.05.

The p-value threshold; -1 when no p-value survives correction.

Observations by subjects, shape (n_observations, n_subjects), with ISC computed across the columns; or (n_observations, n_subjects, n_voxels) for a per-voxel result, in which case 'isc', 'p' and both 'ci' bounds are arrays of length n_voxels. DataFrame inputs are 2D only.

Number of bootstrap draws or surrogate permutations. Defaults to 5000.

'median' (default) or 'mean'.

Which cross-subject comparison to summarize. 'pairwise' (default) correlates every pair of subjects, O(n_subjects²); 'leave-one-out' correlates each subject with the mean of the others, O(n_subjects). Leave-one-out gives systematically larger values because the averaged reference is less noisy than a single subject (Chen et al., 2016, Figure 3).

'bootstrap' (default), 'circle_shift', or 'phase_randomize'.

Confidence-interval width in percent. Defaults to 95.

Set self-correlations (the same subject bootstrapped twice) to NaN. Applies to the pairwise statistic only. Defaults to True.

2 or 'two' (two-tailed, default) or 1 or 'one' (one-tailed, ISC > 0).

Pairwise similarity metric; any metric accepted by sklearn's pairwise_distances. Applies to the pairwise statistic only. Defaults to 'correlation'.

Include the null distribution in the result. Defaults to False.

CPU workers for the resamples; -1 (default) picks the count from available memory.

Seed or generator for the resampling.

Display a progress bar. Defaults to False.

Keys 'isc' (observed ISC), 'p', and 'ci' (tuple (lower, upper)) — floats for 2D data, arrays of length n_voxels for 3D — and, when return_null=True, 'null_dist' (np.ndarray), holding every draw with NaN where a draw was undefined.

Observations by subjects for the first group.

Observations by subjects for the second group (same number of observations).

Number of permutations or bootstrap draws. Defaults to 5000.

'median' (default) or 'mean'.

'permute' (default) or 'bootstrap'.

Confidence-interval width in percent. Defaults to 95.

In the bootstrap, set self-correlations to NaN. Defaults to True.

Include the null distribution in the result. Defaults to False.

2 or 'two' (two-tailed, default) or 1 or 'one' (one-tailed, group1 > group2).

Pairwise similarity metric; any metric accepted by sklearn's pairwise_distances. Defaults to 'correlation'.

CPU workers for the resamples; -1 (default) picks the count from available memory.

Random seed for reproducibility.

Display a progress bar. Defaults to False.

Keys 'isc_group_difference' (float, observed difference), 'p' (float), 'ci' (tuple (lower, upper)), and — when return_null=True — 'null_dist' (np.ndarray), holding every draw with NaN where a draw was undefined.

One matrix per subject, each (n_observations, n_features) with identical shapes.

Only 'average' (leave-one-out) is implemented.

Parallel workers; -1 (default) uses all cores, 1 runs serially.

Unused. ISFC's leave-one-out computation is deterministic and draws no random samples; the parameter exists for signature parity with the rest of the ISC family (isc, isc_group).

Display a progress bar over subjects. Defaults to False.

One (n_features, n_features) ISFC matrix per subject.

Observations by subjects.

Sampling frequency in Hz. Defaults to 0.5.

Lower band-pass cutoff in Hz. Defaults to 0.04.

Upper band-pass cutoff in Hz. Defaults to 0.07.

Butterworth filter order. Defaults to 5.

Compute on pairwise phase-angle differences instead of the raw phase angles. Defaults to False.

Keys 'average_angle' (np.ndarray, mean phase angle per time point), 'vector_length' (np.ndarray, mean resultant length per time point), and 'p' (np.ndarray, Rayleigh-test p-value per time point).

Number of observations (e.g. TRs).

Seconds between observations (the TR), SPM's RT. The number of bases is trunc(2 * nsamples * sampling_interval / filter_length + 1), minus the constant. DesignMatrix stores a sampling frequency, so DesignMatrix.add_dct_basis inverts it and passes 1 / DesignMatrix.sampling_freq.

Filter length in seconds.

Scale the basis functions to the range [-1, 1]. Defaults to True.

Number of leading (slowest) bases to drop after the constant is removed; drop=2 removes the first two. Defaults to 0, which keeps the linear/sigmoidal drift basis that SPM discards.

Basis matrix of shape (nsamples, n_bases).

First square matrix (n×n).

Second square matrix (n×n).

Number of permutations. Defaults to 5000.

Correlation metric, one of 'pearson', 'spearman', or 'kendall'. Defaults to 'pearson'.

Which elements to compare: 'upper' (upper triangle; assumes symmetric matrices), 'lower' (lower triangle), or 'full' (all elements, see include_diag). Defaults to 'upper'.

Include diagonal elements (only when how='full'). Defaults to False.

2 or 'two' for a two-tailed test (r != 0); 1 or 'one' for a one-tailed test of r > 0 (negate one matrix for the other direction). Defaults to 2.

Also return the null distribution. Defaults to False.

Number of joblib workers, -1 = all cores. Defaults to -1. Results are identical at every worker count.

Random seed for reproducibility.

Show a progress bar over permutations. Defaults to False.

Keys 'correlation' (float, observed correlation), 'p' (float, Phipson-Smyth corrected p-value), and 'null_dist' (np.ndarray) when return_null=True.

Statistic image (e.g. t-values or betas).

P-value image with the same voxels as t_map.

P-value thresholds to apply.

Cumulative map. Positive values count how many thresholds a positive statistic passed; negative values count the same for negative statistics.

If either image is not a BrainData, if thresh is not a list, or if the two images do not cover the same voxels on the same grid.

Data to test, shape (n_samples,) for a single feature or (n_samples, n_features) for voxel-wise data. May contain NaN observations.

Number of permutations. Defaults to 5000.

2 or 'two' (default) for a two-tailed test (mean != 0); 1 or 'one' for a one-tailed test of mean > 0 (negate the data for the other direction — the fixed direction keeps multiple-comparison correction valid).

If True, include the full null distribution in the result. Defaults to False.

Number of joblib workers. Defaults to -1 (all cores). Results are identical at every worker count.

Random seed for reproducibility.

Whether to display a progress bar. Defaults to False.

Keys 'mean' (float or np.ndarray, observed mean(s)), 'p' (float or np.ndarray, p-value(s)), and — when return_null=True — 'null_dist' (np.ndarray, shape (n_permute,) or (n_permute, n_features)).

Time series, shape (n_samples,) or (n_samples, n_features).

Random seed for reproducibility.

Phase-randomized data with the same shape as the input.

1d or 2d array; must have the same number of rows as mat2.

1d or 2d array; must have the same number of rows as mat1.

Number of permutation iterations. Defaults to 5000.

2 or 'two' for a two-tailed test (default); 1 or 'one' for one-tailed (similarity greater than chance).

Number of CPUs for the permutations; -1 (default) uses all.

Seed or generator for the row shuffling. Defaults to None.

Keys 'similarity' (float in [0, 1], one minus the Procrustes disparity) and 'p' (permutation p-value).

Design matrix, shape (n_samples, n_regressors).

Response, shape (n_samples,) or (n_samples, n_targets).

'full' returns the 6-tuple below, 'betas' returns just b, 'tstats' returns (b, t). Defaults to 'full'.

2 or 'two' for two-tailed p-values (default); 1 or 'one' for a one-tailed test of beta > 0 (negate a regressor for the other direction).

(b, se, t, p, df, res) when stats='full': coefficients, standard errors, t-statistics, p-values (per tail), residual degrees of freedom, and residuals. stats='betas' returns just b; stats='tstats' returns (b, t).

Statistic image (e.g. betas or t-values).

P-value image with the same voxels as stat.

P-value threshold; voxels with p < thr are kept. Defaults to 0.05.

Also return the binary thresholding mask. Defaults to False.

The thresholded image, or the tuple (thresholded, mask) when return_mask=True.

If either argument is not a BrainData, or if the two images do not cover the same voxels on the same grid.

Data, shape (n_samples, n_features).

Target labels, shape (n_samples,) or (n_samples, 2). A second column groups the samples; pairs from different groups are skipped.

(X_trans, y_trans). X_trans has shape (k, n_features) with one row per retained pair (k is at most n_samples * (n_samples - 1) / 2; pairs are formed within groups when given). y_trans holds the labels in {-1, +1}, shape (k,), or (k, 2) with the group in the second column when y had two columns.

Data to trim.

A dictionary with keys {'std': [low, high]} or {'quantile': [low, high]}.

Trimmed data (outliers replaced with NaN), the same type as the input.

If data is not Polars, if cutoff has neither key, or if a quantile cutoff is asked of a column with no present values.

Group 1 data, shape (n_samples1,) for a single feature or (n_samples1, n_features) for voxel-wise data. May contain NaN observations.

Group 2 data, shape (n_samples2,) or (n_samples2, n_features); must have the same number of features as data1. May contain NaN observations.

Number of permutations. Defaults to 5000.

2 or 'two' (default) for a two-tailed test (mean1 != mean2); 1 or 'one' for a one-tailed test of mean1 > mean2 (swap the groups for the other direction — the fixed direction keeps multiple-comparison correction valid).

If True, include the full null distribution in the result. Defaults to False.

Number of joblib workers. Defaults to -1 (all cores). Results are identical at every worker count.

Random seed for reproducibility.

Whether to display a progress bar. Defaults to False.

Keys 'mean_diff' (float or np.ndarray, observed mean(data1) - mean(data2)), 'p' (float or np.ndarray, p-value(s)), and — when return_null=True — 'null_dist' (np.ndarray, shape (n_permute,) or (n_permute, n_features)).

Data to upsample. Non-numeric columns are dropped from a DataFrame; Boolean columns count as numeric and are interpolated as 0/1.

Sampling frequency of the data in Hz.

Upsampling target.

Unit of target, one of 'samples', 'seconds', or 'hz'.

Interpolation method, one of 'linear', 'nearest', 'zero', 'slinear', 'quadratic', or 'cubic'; 'zero', 'slinear', 'quadratic' and 'cubic' refer to spline interpolation of zeroth, first, second or third order (default: 'linear').

Upsampled data, the same type as the input.

If data is not Polars, if method or target_type is unknown, or if the frame has no numeric columns to interpolate.

Data to winsorize.

A dictionary with keys {'std': [low, high]} or {'quantile': [low, high]}.

If True, replace outliers with the cutoff value; if False, replace them with the closest existing values (default: True).

Winsorized data, the same type as the input.

If data is not Polars, if cutoff has neither key, or if a quantile cutoff is asked of a column with no present values.

Data to z-score.

Same shape as the input, each column z-scored with the sample standard deviation (ddof=1).