brainspace.null_models.variogram.SurrogateMaps

class brainspace.null_models.variogram.SurrogateMaps(deltas=None, kernel='exp', pv=25, nh=25, resample=False, b=None, n_rep=100, random_state=None)

Spatial autocorrelation-preserving surrogate brain maps.

Parameters:

• deltas (1D ndarray or List[float], optional) – Proportion of neighbors to include for smoothing, in (0, 1] Default is [0.1,0.2,…,0.9].
• kernel (str, optional) –

  Kernel with which to smooth permuted maps:

  ’gaussian’ : Gaussian function. ‘exp’ : Exponential decay function. ‘invdist’ : Inverse distance. ‘uniform’ : Uniform weights (distance independent).

  Default is ‘exp’.

• pv (int, optional) – Percentile of the pairwise distance distribution at which to truncate during variogram fitting. Default is 25.
• nh (int, optional) – Number of uniformly spaced distances at which to compute variogram. Default is 25.
• resample (bool, optional) – Resample surrogate maps’ values from target brain map. Default is False.
• b (float or None, optional) – Gaussian kernel bandwidth for variogram smoothing. If None, set to three times the spacing between variogram x-coordinates. Default is None.
• n_rep (int, optional) – Number of randomizations (i.e., surrogate maps). Default is 100.
• random_state (int or None, optional) – Random state. Default is None.

See also

SampledSurrogateMaps, SpinPermutations, MoranRandomization

Notes

Passing resample=True preserves the distribution of values in the target map, with the possibility of worsening the simulated surrogate maps’ variograms fits.

__init__(deltas=None, kernel='exp', pv=25, nh=25, resample=False, b=None, n_rep=100, random_state=None)

Initialize self. See help(type(self)) for accurate signature.

Methods

__init__([deltas, kernel, pv, nh, resample, …])	Initialize self.
compute_variogram(x)	Compute variogram values (i.e., one-half squared pairwise differences).
fit(dist)	Prepare data for sorrugate map generation..
get_params([deep])	Get parameters for this estimator.
permute_map(x)	Return randomly permuted brain map.
randomize(x[, n_rep])	Generate surrogate maps from x.
regress(x, y)	Linearly regress x onto y.
set_params(**params)	Set the parameters of this estimator.
smooth_map(x, delta)	Smooth x using delta proportion of nearest neighbors.
smooth_variogram(v[, return_h])	Smooth a variogram.

Attributes

h	distances at which smoothed variogram is computed

compute_variogram(x)

Compute variogram values (i.e., one-half squared pairwise differences).

Parameters:x (1D ndarray) – Brain map scalar array Returns:v (ndarray, shape (N(N-1)/2,)) – Variogram y-coordinates, i.e. 0.5 * (x_i - x_j) ^ 2

fit(dist)

Prepare data for sorrugate map generation..

Parameters:dist (filename or ndarray, shape (N,N)) – Pairwise (geodesic) distance matrix. Returns:self (object) – Returns self.

h

distances at which smoothed variogram is computed

Type:1D ndarray

permute_map(x)

Return randomly permuted brain map.

Parameters:x (1D masked ndarray) – Brain map scalars Returns:1D ndarray – Random permutation of target brain map

randomize(x, n_rep=None)

Generate surrogate maps from x.

Parameters:

• x (filename or 1D ndarray) – Target brain map
• n_rep (int or None, optional) – Number of surrogates maps to randomly generate. If None, use the default n_rep.

Returns:

output (ndarray, shape = (n_rep, n_verts)) – Randomly generated map(s) with matched spatial autocorrelation.

regress(x, y)

Linearly regress x onto y.

Parameters:

• x (1D ndarray) – Independent variable
• y (1D ndarray) – Dependent variable

Returns:

• alpha (float) – Intercept term (offset parameter)
• beta (float) – Regression coefficient (scale parameter)
• res (float) – Sum of squared residuals

smooth_map(x, delta)

Smooth x using delta proportion of nearest neighbors.

Parameters:

• x (1D ndarray) – Brain map scalars
• delta (float) – Proportion of neighbors to include for smoothing, in (0, 1)

Returns:

1D ndarray – Smoothed brain map

smooth_variogram(v, return_h=False)

Smooth a variogram.

Parameters:

• v (1D ndarray) – Variogram values, i.e. 0.5 * (x_i - x_j) ^ 2
• return_h (bool, default False) – Return distances at which the smoothed variogram was computed

Returns:

• 1D ndarray, shape (nh,) – Smoothed variogram values
• 1D ndarray, shape (nh,) – Distances at which smoothed variogram was computed (returned only if return_h is True)

Raises:

ValueError : v has unexpected size.