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
See also
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.
- 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
-
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: 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