spectralbrain.statistics.surrogates#

Surrogate data, null models, and synthetic data generators.

Three pillars:

Bootstrap — resampling with CI (percentile + BCa).
Null models — 6 hypothesis-specific null generators.
Synthetic generators — descriptors, meshes, point clouds from real data or 22 parametric distributions.

Null models#

Eigenvalue permutation — tests spectral ordering.
Phase randomisation — tests vertex-specific structure.
Spin permutation — tests beyond spatial autocorrelation.
Subject permutation — tests group difference.
Edge rewiring — tests network topology.
Parametric — tests beyond marginal distribution.

Distributions#

normal, beta, gamma, cauchy, dirichlet, exponential, halfcauchy, halfnormal, poisson, inversegamma, laplace, kumaraswamy, studentt, negativebinomial, binomial, logistic, mixture, pareto, uniform, wald, vonmises, weibull.

Functions

`bootstrap_ci`(data, statistic, *[, ...])	Bootstrap confidence interval for a scalar statistic.
`bootstrap_paired_difference`(a, b, *[, ...])	Bootstrap confidence interval for paired mean difference.
`null_edge_rewiring`(connectome, *[, ...])	Null 5: degree-preserving edge rewiring (Maslov & Sneppen 2002).
`null_eigenvalue_permutation`(eigenvalues, ...)	Null 1: permute eigenvalues, keep eigenvectors.
`null_parametric`(descriptor, *[, ...])	Null 6: matched Gaussian surrogate.
`null_phase_randomisation`(descriptor, ...[, ...])	Null 2: randomise phases in spectral domain.
`null_spin_permutation`(descriptor, ...[, ...])	Null 3: spin permutation (Alexander-Bloch 2018).
`null_subject_permutation`(descriptors, labels, *)	Null 4: permute group labels.

Classes

`SyntheticDescriptors`([reference, ...])	Generate synthetic spectral descriptor matrices.
`SyntheticMesh`([reference_vertices, ...])	Generate synthetic triangle meshes (sphere, ellipsoid, torus).
`SyntheticPointCloud`([reference, ...])	Generate synthetic point clouds (sphere, ellipsoid, blob, multi-cluster).

class spectralbrain.statistics.surrogates.SyntheticDescriptors(reference=None, distribution=None, dist_params=None, seed=None)[source]#

Bases: object

Generate synthetic spectral descriptor matrices.

Parameters:

reference (ndarray, optional) – Real data to match.
distribution (str, optional) – Parametric family (default "normal").
dist_params (dict, optional)
seed (int)

Examples

>>> gen = SyntheticDescriptors(distribution="gamma", dist_params={"shape": 2})
>>> data = gen.generate(n_subjects=50, n_vertices=1000, n_scales=20)

generate(n_subjects=20, n_vertices=500, n_scales=10)[source]#: Returns shape (n_subjects, n_vertices, n_scales).

generate_global(n_subjects=20, n_features=50)[source]#: Returns shape (n_subjects, n_features).

class spectralbrain.statistics.surrogates.SyntheticMesh(reference_vertices=None, distribution=None, dist_params=None, seed=None)[source]#

Bases: object

Generate synthetic triangle meshes (sphere, ellipsoid, torus).

Parameters:

reference_vertices (ndarray, optional)
distribution (as above.)
dist_params (as above.)
seed (as above.)

ellipsoid(radii=(50, 30, 20), n_lat=30, n_lon=60, noise=0.0)[source]#

Generate an ellipsoid mesh.

Parameters:

radii (tuple of float) – Semi-axis lengths (a, b, c).
n_lat (int) – Latitude and longitude subdivisions.
n_lon (int) – Latitude and longitude subdivisions.
noise (float) – Noise scale.

Returns:

vertices (ndarray, shape (V, 3))
faces (ndarray, shape (F, 3))

sphere(n_lat=30, n_lon=60, radius=50.0, noise=0.0)[source]#

Generate a UV-sphere mesh.

Parameters:

n_lat (int) – Latitude and longitude subdivisions.
n_lon (int) – Latitude and longitude subdivisions.
radius (float) – Sphere radius.
noise (float) – Noise scale (0 = no noise).

Returns:

vertices (ndarray, shape (V, 3))
faces (ndarray, shape (F, 3))

torus(R=40.0, r=15.0, n_major=40, n_minor=20, noise=0.0)[source]#

Generate a torus mesh.

Parameters:

R (float) – Major radius (center of tube to center of torus).
r (float) – Minor radius (tube radius).
n_major (int) – Subdivisions along major and minor circles.
n_minor (int) – Subdivisions along major and minor circles.
noise (float) – Noise scale.

Returns:

vertices (ndarray, shape (V, 3))
faces (ndarray, shape (F, 3))

class spectralbrain.statistics.surrogates.SyntheticPointCloud(reference=None, distribution=None, dist_params=None, seed=None)[source]#

Bases: object

Generate synthetic point clouds (sphere, ellipsoid, blob, multi-cluster).

Parameters:

reference (ndarray, optional)
distribution (as above.)
dist_params (as above.)
seed (as above.)

blob(n_points=1000, center=(0, 0, 0), scale=(10, 10, 10))[source]#

Generate a Gaussian blob point cloud.

Parameters:

n_points (int)
center (tuple of float)
scale (tuple of float)

Returns:

ndarray, shape (n_points, 3)

ellipsoid(n_points=1000, radii=(50, 30, 20), noise=0.5)[source]#

Generate random points on an ellipsoid surface.

Parameters:

n_points (int)
radii (tuple of float) – Semi-axis lengths (a, b, c).
noise (float)

Returns:

ndarray, shape (n_points, 3)

from_reference(n_points=None)[source]#

Generate points matching the reference distribution.

Parameters:: n_points (int, optional) – Number of points (default: same as reference).
Returns:: ndarray, shape (n_points, 3)

multi_cluster(n_points=1000, n_clusters=5, spread=30.0, cluster_std=5.0)[source]#

Generate a multi-cluster point cloud.

Parameters:

n_points (int)
n_clusters (int)
spread (float) – Spatial extent for cluster centres.
cluster_std (float) – Standard deviation within each cluster.

Returns:

ndarray, shape (~n_points, 3)

sphere(n_points=1000, radius=50.0, noise=0.5)[source]#

Generate random points on a sphere surface.

Parameters:

n_points (int)
radius (float)
noise (float) – Gaussian jitter magnitude.

Returns:

ndarray, shape (n_points, 3)

spectralbrain.statistics.surrogates.bootstrap_ci(data, statistic, *, n_bootstrap=10000, ci=0.95, method='percentile', seed=None, n_jobs=1)[source]#

Bootstrap confidence interval for a scalar statistic.

Parameters:

data (ndarray) – Input data array.
statistic (callable) – Function that maps data to a scalar.
n_bootstrap (int) – Number of bootstrap replicates.
ci (float) – Confidence level (e.g. 0.95 for 95% CI).
method ("percentile" or "bca") – CI method. BCa (bias-corrected and accelerated) is more accurate but slower.
seed (int, optional) – RNG seed.
n_jobs (int) – Parallel workers for bootstrap replicates (1 = sequential, -1 = all cores). Requires joblib.

Returns:

estimate (float) – The statistic computed on the original data.
ci_low (float) – Lower bound of the confidence interval.
ci_high (float) – Upper bound of the confidence interval.

Return type:

tuple[float, float, float]

spectralbrain.statistics.surrogates.bootstrap_paired_difference(a, b, *, n_bootstrap=10000, ci=0.95, seed=None)[source]#

Bootstrap confidence interval for paired mean difference.

Computes the CI of mean(a - b) via bootstrap resampling on the paired differences.

Parameters:

a (ndarray) – Paired observations (same length).
b (ndarray) – Paired observations (same length).
n_bootstrap (int) – Number of bootstrap replicates.
ci (float) – Confidence level.
seed (int, optional) – RNG seed.

Returns:

estimate (float) – Mean paired difference.
ci_low, ci_high (float) – Confidence interval bounds.

Return type:

tuple[float, float, float]

spectralbrain.statistics.surrogates.null_edge_rewiring(connectome, *, n_surrogates=1000, n_swaps_per_edge=10, seed=None, n_jobs=1)[source]#

Null 5: degree-preserving edge rewiring (Maslov & Sneppen 2002). Tests network topology.

Each surrogate is keyed to an independent, reproducible child RNG via numpy.random.SeedSequence, so results are identical whether run sequentially (``n_jobs=1``) or in parallel (n_jobs=-1 uses all cores). Rewiring is the expensive null (an inner swap loop per surrogate), so parallelism gives a near-linear speedup.

spectralbrain.statistics.surrogates.null_eigenvalue_permutation(eigenvalues, eigenvectors, *, n_surrogates=1000, seed=None)[source]#: Null 1: permute eigenvalues, keep eigenvectors. Tests spectral ordering.

spectralbrain.statistics.surrogates.null_parametric(descriptor, *, n_surrogates=1000, seed=None)[source]#: Null 6: matched Gaussian surrogate. Tests beyond marginal distribution.

spectralbrain.statistics.surrogates.null_phase_randomisation(descriptor, eigenvectors, *, n_surrogates=1000, seed=None)[source]#: Null 2: randomise phases in spectral domain. Tests vertex-level structure.

spectralbrain.statistics.surrogates.null_spin_permutation(descriptor, sphere_coords, *, n_surrogates=1000, seed=None, n_jobs=1)[source]#

Null 3: spin permutation (Alexander-Bloch 2018). Tests beyond spatial autocorrelation.

Each spin is keyed to an independent, reproducible child RNG, so results are identical for n_jobs=1 (sequential) and n_jobs=-1 (all cores). The per-spin nearest-neighbour query over all vertices is the cost that parallelism amortises.

spectralbrain.statistics.surrogates.null_subject_permutation(descriptors, labels, *, n_surrogates=5000, seed=None)[source]#: Null 4: permute group labels. Classic permutation test.