brainspace.null_models.variogram.SampledSurrogateMaps

class brainspace.null_models.variogram.SampledSurrogateMaps(ns=500, pv=70, nh=25, knn=1000, b=None, deltas=None, kernel='exp', resample=False, n_rep=100, random_state=None, verbose=False)[source]

Spatial autocorrelation-preserving surrogate brain maps wih sampling.

Parameters:
  • ns (int, optional) – Take a subsample of ns rows from D when fitting variograms. Default is 500.
  • 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.
  • knn (int, optional) – Number of nearest regions to keep in the neighborhood of each region. Default is 1000.
  • b (float or None, default None) – Gaussian kernel bandwidth for variogram smoothing. if None, three times the distance interval spacing is used.
  • resample (bool, optional) – Resample surrogate maps’ values from target brain map. Default is False.
  • 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.
  • verbose (bool, default False) – Print surrogate count each time new surrogate map created

Notes

Passing resample=True will preserve the distribution of values in the target map, at the expense of worsening simulated surrogate maps’ variograms fits. This worsening will increase as the empirical map more strongly deviates from normality.

__init__(ns=500, pv=70, nh=25, knn=1000, b=None, deltas=None, kernel='exp', resample=False, n_rep=100, random_state=None, verbose=False)[source]

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

Methods

__init__([ns, pv, nh, knn, b, deltas, …]) Initialize self.
compute_variogram(x, idx) Compute variogram of x using pairs of regions indexed by idx.
fit(dist, index) Prepare data for surrogate map generation.
get_params([deep]) Get parameters for this estimator.
permute_map(x) Return a random permutation of x.
randomize(x[, n_rep]) Generate surrogate maps from x.
regress(x, y) Linearly regress x onto y.
sample(n) Randomly sample (without replacement) brain areas for variogram computation.
set_params(**params) Set the parameters of this estimator.
smooth_map(x, k) Smooth x using k nearest neighboring regions.
smooth_variogram(u, v[, return_h]) Smooth a variogram.

Attributes

h distances at which variogram is evaluated
compute_variogram(x, idx)[source]

Compute variogram of x using pairs of regions indexed by idx.

Parameters:
  • x (1D ndarray) – Brain map
  • idx (ndarray[int], shape (ns,)) – Indices of randomly sampled brain regions
Returns:

v (ndarray, shape (ns,ns)) – Variogram y-coordinates, i.e. 0.5 * (x_i - x_j) ^ 2, for i,j in idx

fit(dist, index)[source]

Prepare data for surrogate map generation.

Parameters:
  • dist (ndarray or memmap, shape (N,N)) – Pairwise distance matrix. Each row of dist should be sorted. Indices used to sort each row are passed to through the index argument. See brainspace.variogram.txt2memmap.
  • index (filename or ndarray or memmap, shape(N,N)) – Indices used to sort each row of dist.
Returns:

self (object) – Returns self.

h

distances at which variogram is evaluated

Type:1D ndarray
permute_map(x)[source]

Return a random permutation of x.

Parameters:x (1D ndarray) – Brain map
Returns:1D ndarray – Random permutation of target brain map
randomize(x, n_rep=None)[source]

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)[source]

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

sample(n)[source]

Randomly sample (without replacement) brain areas for variogram computation.

Returns:ndarray, shape (ns,) – Indices of randomly sampled areas
smooth_map(x, k)[source]

Smooth x using k nearest neighboring regions.

Parameters:
  • x (1D ndarray) – Brain map
  • k (float) – Number of nearest neighbors to include for smoothing
Returns:

x_smooth (1D ndarray) – Smoothed brain map

Notes

Assumes dist provided at runtime has been sorted.

smooth_variogram(u, v, return_h=False)[source]

Smooth a variogram.

Parameters:
  • u (1D ndarray) – Pairwise distances, ie variogram x-coordinates
  • v (1D ndarray) – Squared differences, ie variogram y-coordinates
  • return_h (bool, default False) – Return distances at which smoothed variogram is computed
Returns:

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

Raises:

ValueError : u and v are not identically sized