brainsmash.mapgen package

Submodules

brainsmash.mapgen.base module

Generate spatial autocorrelation-preserving surrogate maps.

class brainsmash.mapgen.base.Base(x, D, deltas=array([0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]), kernel='exp', pv=25, nh=25, resample=False, b=None, seed=None, n_jobs=1)

Bases: object

Base implementation of map generator.

Parameters

  • x ((N,) np.ndarray or filename) – Target brain map

  • D ((N,N) np.ndarray or filename) – Pairwise distance matrix

  • deltas (np.ndarray or List[float], default [0.1,0.2,..,0.9]) – Proportion of neighbors to include for smoothing, in (0, 1]

  • kernel (str, default 'exp') –

    Kernel with which to smooth permuted maps:

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

  • pv (int, default 25) – Percentile of the pairwise distance distribution at which to truncate during variogram fitting

  • nh (int, default 25) – Number of uniformly spaced distances at which to compute variogram

  • resample (bool, default False) – Resample surrogate maps’ values from target brain map

  • b (float or None, default None) – Gaussian kernel bandwidth for variogram smoothing. If None, set to three times the spacing between variogram x-coordinates.

  • seed (None or int or np.random.RandomState instance (default None)) – Specify the seed for random number generation (or random state instance)

  • n_jobs (int (default 1)) – Number of jobs to use for parallelizing creation of surrogate maps

Notes

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

property D

Pairwise distance matrix

Type

(N,N) np.ndarray

property b

Gaussian kernel bandwidth

Type

numeric

compute_smooth_variogram(x, return_h=False)

Compute smoothed variogram values (1/2 squared pairwise differences)

Parameters

  • x ((N,) np.ndarray) – Brain map scalar array

  • return_h (bool, default False) – Return distances at which the smoothed variogram was computed

Returns

  • (self.nh,) np.ndarray – Smoothed variogram values

  • (self.nh) np.ndarray – Distances at which smoothed variogram was computed (returned only if return_h is True)

property deltas

proportions of nearest neighbors

Type

np.ndarray or List[float]

property h

distances at which smoothed variogram is computed

Type

np.ndarray

property kernel

smoothing kernel function

Notes

When setting kernel, use name of kernel as defined in config.py.

Type

Callable

property nh

number of variogram distance intervals

Type

int

property nmap

length of brain map

Type

int

permute_map(i=1)

Return randomly permuted brain map.

Returns

Random permutation of target brain map

Return type

(N,) np.ndarray

property pv

percentile of pairwise distances at which to truncate

Type

int

regress(x, y)

Linearly regress x onto y.

Parameters

  • x ((N,) np.ndarray) – Independent variable

  • y ((N,) np.ndarray) – Dependent variable

Returns

  • alpha (float) – Intercept term (offset parameter)

  • beta (float) – Regression coefficient (scale parameter)

  • res (float) – Sum of squared residuals

property resample

whether to resample surrogate maps from target map

Type

bool

smooth_map(x, delta)

Smooth x using delta proportion of nearest neighbors.

Parameters

  • x ((N,) np.ndarray) – Brain map scalars

  • delta (float) – Proportion of neighbors to include for smoothing, in (0, 1)

Returns

Smoothed brain map

Return type

(N,) np.ndarray

property x

brain map scalar array

Type

(N,) np.ndarray

brainsmash.mapgen.eval module

Evaluation metrics for randomly generated surrogate maps.

brainsmash.mapgen.eval.base_fit(x, D, nsurr=100, return_data=False, **params)

Evaluate variogram fits for Base class.

Parameters

  • x ((N,) np.ndarray or filename) – Target brain map

  • D ((N,N) np.ndarray or filename) – Pairwise distance matrix between regions in x

  • nsurr (int, default 100) – Number of simulated surrogate maps from which to compute variograms

  • return_data (bool, default False) – if True, return: 1, the smoothed variogram values for the target brain map; 2, the distances at which the smoothed variograms values were computed; and 3, the surrogate maps’ smoothed variogram values

  • params – Keyword arguments for brainsmash.mapgen.base.Base

Returns

  • if and only if return_data is True

  • emp_var ((M,) np.ndarray) – empirical smoothed variogram values

  • u0 ((M,) np.ndarray) – distances at which variogram values were computed

  • surr_var ((nsurr, M) np.ndarray) – surrogate maps’ smoothed variogram values

Notes

If return_data is False, this function generates and shows a matplotlib plot instance illustrating the fit of the surrogates’ variograms to the target map’s variogram. If return_data is True, this function returns the data needed to generate such a plot (i.e., the variogram values and the corresponding distances).

brainsmash.mapgen.eval.sampled_fit(x, D, index, nsurr=10, return_data=False, **params)

Evaluate variogram fits for Sampled class.

Parameters

  • x ((N,) np.ndarray) – Target brain map

  • D ((N,N) np.ndarray or np.memmap) – Pairwise distance matrix between elements of x

  • index ((N,N) np.ndarray or np.memmap) – See brainsmash.mapgen.sampled.Sampled

  • nsurr (int, default 10) – Number of simulated surrogate maps from which to compute variograms

  • return_data (bool, default False) – if True, return: 1, the smoothed variogram values for the target brain map; 2, the distances at which the smoothed variograms values were computed; and 3, the surrogate maps’ smoothed variogram values

  • params – Keyword arguments for brainsmash.mapgen.sampled.Sampled

Returns

  • if and only if return_data is True

  • emp_var ((M,) np.ndarray) – empirical smoothed variogram values

  • u0 ((M,) np.ndarray) – distances at which variogram values were computed

  • surr_var ((nsurr, M) np.ndarray) – surrogate maps’ smoothed variogram values

Notes

If return_data is False, this function generates and shows a matplotlib plot instance illustrating the fit of the surrogates’ variograms to the target map’s variogram. If return_data is True, this function returns the data needed to generate such a plot (i.e., the variogram values and the corresponding distances).

brainsmash.mapgen.kernels module

Kernels used to smooth randomly permuted brain maps.

brainsmash.mapgen.kernels.gaussian(d)

Gaussian kernel which truncates at one standard deviation.

Parameters

d ((N,) or (M,N) np.ndarray) – one- or two-dimensional array of distances

Returns

Gaussian kernel weights

Return type

(N,) or (M,N) np.ndarray

:raises TypeError : d is not array_like:

brainsmash.mapgen.kernels.exp(d)

Exponentially decaying kernel which truncates at e^{-1}.

Parameters

d ((N,) or (M,N) np.ndarray) – one- or two-dimensional array of distances

Returns

Exponential kernel weights

Return type

(N,) or (M,N) np.ndarray

Notes

Characteristic length scale is set to d.max(axis=-1), i.e. the maximum distance within each row.

:raises TypeError : d is not array_like:

brainsmash.mapgen.kernels.invdist(d)

Inverse distance kernel.

Parameters

d ((N,) or (M,N) np.ndarray) – One- or two-dimensional array of distances

Returns

Inverse distance, i.e. d^{-1}

Return type

(N,) or (M,N) np.ndarray

:raises ZeroDivisionError : d includes zero value: :raises TypeError : d is not array_like:

brainsmash.mapgen.kernels.uniform(d)

Uniform (i.e., distance independent) kernel.

Parameters

d ((N,) or (M,N) np.ndarray) – One- or two-dimensional array of distances

Returns

Uniform kernel weights

Return type

(N,) or (M,N) np.ndarray

Notes

Each element is normalized to 1/N such that columns sum to unity.

:raises TypeError : d is not array_like:

brainsmash.mapgen.kernels.check_kernel(kernel)

Check that a valid kernel was specified.

Parameters

kernel ('exp' or 'gaussian' or 'invdist' or 'uniform') – Kernel selection

Returns

Return type

Callable

Notes

If kernel is included in config.py, a function with the same name must be defined in mapgen.kernels.py.

:raises NotImplementedError : kernel is not included in config.py:

brainsmash.mapgen.memmap module

Convert large data files written to disk to memory-mapped arrays for memory- efficient data retrieval.

brainsmash.mapgen.memmap.txt2memmap(dist_file, output_dir, maskfile=None, delimiter=' ')

Export distance matrix to memory-mapped array.

Parameters

  • dist_file (filename) – Path to delimiter-separated distance matrix file

  • output_dir (filename) – Path to directory in which output files will be written

  • maskfile (filename or np.ndarray or None, default None) – Path to a neuroimaging/txt file containing a mask, or a mask represented as a numpy array. Mask scalars are cast to boolean, and all elements not equal to zero will be masked.

  • delimiter (str) – Delimiting character in dist_file

Returns

Keys are ‘D’ and ‘index’; values are absolute paths to the corresponding binary files on disk.

Return type

dict

Notes

Each row of the distance matrix is sorted before writing to file. Thus, a second mem-mapped array is necessary, the i-th row of which contains argsort(d[i]). If maskfile is not None, a binary mask.txt file will also be written to the output directory.

:raises IOError : output_dir doesn’t exist: :raises ValueError : Mask image and distance matrix have inconsistent sizes:

brainsmash.mapgen.memmap.load_memmap(filename)

Load a memory-mapped array.

Parameters

filename (str) – path to memory-mapped array saved as npy file

Returns

Return type

np.memmap

brainsmash.mapgen.sampled module

Generate spatial autocorrelation-preserving surrogate maps from memory-mapped arrays with random subsampling.

class brainsmash.mapgen.sampled.Sampled(x, D, index, ns=500, pv=70, nh=25, knn=1000, b=None, deltas=array([0.3, 0.5, 0.7, 0.9]), kernel='exp', resample=False, verbose=False, seed=None, n_jobs=1)

Bases: object

Sampling implementation of map generator.

Parameters

  • x (filename or 1D np.ndarray) – Target brain map

  • D (filename or (N,N) np.ndarray or np.memmap) – Pairwise distance matrix between elements of x. Each row of D should be sorted. Indices used to sort each row are passed to the index argument. See brainsmash.mapgen.memmap.txt2memmap or the online documentation for more details (brainsmash.readthedocs.io)

  • index (filename or (N,N) np.ndarray or np.memmap) – See above

  • ns (int, default 500) – Take a subsample of ns rows from D when fitting variograms

  • deltas (np.ndarray or List[float], default [0.3, 0.5, 0.7, 0.9]) – Proportions of neighbors to include for smoothing, in (0, 1]

  • kernel (str, default 'exp') – Kernel with which to smooth permuted maps - ‘gaussian’ : gaussian function - ‘exp’ : exponential decay function - ‘invdist’ : inverse distance - ‘uniform’ : uniform weights (distance independent)

  • pv (int, default 70) – Percentile of the pairwise distance distribution (in D) at which to truncate during variogram fitting

  • nh (int, default 25) – Number of uniformly spaced distances at which to compute variogram

  • knn (int, default 1000) – Number of nearest regions to keep in the neighborhood of each region

  • b (float or None, default None) – Gaussian kernel bandwidth for variogram smoothing. if None, three times the distance interval spacing is used.

  • resample (bool, default False) – Resample surrogate map values from the target brain map

  • verbose (bool, default False) – Print surrogate count each time new surrogate map created

  • seed (None or int or np.random.RandomState instance (default None)) – Specify the seed for random number generation (or random state instance)

  • n_jobs (int (default 1)) – Number of jobs to use for parallelizing creation of surrogate maps

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.

:raises ValueError : x and D have inconsistent sizes:

property D

Pairwise distance matrix

Type

(N,N) np.memmap

property b

Gaussian kernel bandwidth

Type

numeric

compute_variogram(x, idx)

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

Parameters

  • x ((N,) np.ndarray) – Brain map

  • idx ((ns,) np.ndarray[int]) – Indices of randomly sampled brain regions

Returns

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

Return type

(ns,ns) np.ndarray

property deltas

proportions of nearest neighbors

Type

np.ndarray or List[float]

property h

distances at which variogram is evaluated

Type

np.ndarray

property index

indexes used to sort each row of dist. matrix

Type

(N,N) np.memmap

property kernel

smoothing kernel function

Notes

When setting kernel, use name of kernel as defined in config.py.

Type

Callable

property knn

number of nearest neighbors included in distance matrix

Type

int

property nh

number of variogram distance intervals

Type

int

property nmap

length of brain map

Type

int

property ns

number of randomly sampled regions used to construct map

Type

int

permute_map()

Return a random permutation of the target brain map.

Returns

Random permutation of target brain map

Return type

(N,) np.ndarray

property pv

percentile of pairwise distances at which to truncate

Type

int

regress(x, y)

Linearly regress x onto y.

Parameters

  • x ((N,) np.ndarray) – Independent variable

  • y ((N,) np.ndarray) – Dependent variable

Returns

  • alpha (float) – Intercept term (offset parameter)

  • beta (float) – Regression coefficient (scale parameter)

  • res (float) – Sum of squared residuals

property resample

whether to resample surrogate map values from target maps

Type

bool

sample()

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

Returns

Indices of randomly sampled areas

Return type

(self.ns,) np.ndarray

smooth_map(x, k)

Smooth x using k nearest neighboring regions.

Parameters

  • x ((N,) np.ndarray) – Brain map

  • k (float) – Number of nearest neighbors to include for smoothing

Returns

x_smooth – Smoothed brain map

Return type

(N,) np.ndarray

Notes

Assumes D provided at runtime has been sorted.

smooth_variogram(u, v, return_h=False)

Smooth a variogram.

Parameters

  • u ((N,) np.ndarray) – Pairwise distances, ie variogram x-coordinates

  • v ((N,) np.ndarray) – Squared differences, ie ariogram y-coordinates

  • return_h (bool, default False) – Return distances at which smoothed variogram is computed

Returns

  • (nh,) np.ndarray – Smoothed variogram samples

  • (nh,) np.ndarray – Distances at which smoothed variogram was computed (returned if return_h is True)

:raises ValueError : u and v are not identically sized:

property x

brain map scalars

Type

(N,) np.ndarray

brainsmash.mapgen.stats module

Functions for performing statistical inference using surrogate maps.

brainsmash.mapgen.stats.spearmanr(X, Y)

Multi-dimensional Spearman rank correlation between rows of X and Y.

Parameters

  • X ((N,P) np.ndarray) –

  • Y ((M,P) np.ndarray) –

Returns

Return type

(N,M) np.ndarray

:raises TypeError : X or Y is not array_like: :raises ValueError : X and Y are not same size along second axis:

brainsmash.mapgen.stats.pearsonr(X, Y)

Multi-dimensional Pearson correlation between rows of X and Y.

Parameters

  • X ((N,P) np.ndarray) –

  • Y ((M,P) np.ndarray) –

Returns

Return type

(N,M) np.ndarray

:raises TypeError : X or Y is not array_like: :raises ValueError : X and Y are not same size along second axis:

brainsmash.mapgen.stats.pairwise_r(X, flatten=False)

Compute pairwise Pearson correlations between rows of X.

Parameters

  • X ((N,M) np.ndarray) –

  • flatten (bool, default False) – If True, return flattened upper triangular elements of corr. matrix

Returns

Pearson correlation coefficients

Return type

(N*(N-1)/2,) or (N,N) np.ndarray

brainsmash.mapgen.stats.nonparp(stat, dist)

Compute two-sided non-parametric p-value.

Compute the fraction of elements in dist which are more extreme than stat.

Parameters

  • stat (float) – Test statistic

  • dist ((N,) np.ndarray) – Null distribution for test statistic

Returns

Fraction of elements in dist which are more extreme than stat

Return type

float

Module contents

class brainsmash.mapgen.Base(x, D, deltas=array([0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]), kernel='exp', pv=25, nh=25, resample=False, b=None, seed=None, n_jobs=1)

Bases: object

Base implementation of map generator.

Parameters

  • x ((N,) np.ndarray or filename) – Target brain map

  • D ((N,N) np.ndarray or filename) – Pairwise distance matrix

  • deltas (np.ndarray or List[float], default [0.1,0.2,..,0.9]) – Proportion of neighbors to include for smoothing, in (0, 1]

  • kernel (str, default 'exp') –

    Kernel with which to smooth permuted maps:

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

  • pv (int, default 25) – Percentile of the pairwise distance distribution at which to truncate during variogram fitting

  • nh (int, default 25) – Number of uniformly spaced distances at which to compute variogram

  • resample (bool, default False) – Resample surrogate maps’ values from target brain map

  • b (float or None, default None) – Gaussian kernel bandwidth for variogram smoothing. If None, set to three times the spacing between variogram x-coordinates.

  • seed (None or int or np.random.RandomState instance (default None)) – Specify the seed for random number generation (or random state instance)

  • n_jobs (int (default 1)) – Number of jobs to use for parallelizing creation of surrogate maps

Notes

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

property D

Pairwise distance matrix

Type

(N,N) np.ndarray

property b

Gaussian kernel bandwidth

Type

numeric

compute_smooth_variogram(x, return_h=False)

Compute smoothed variogram values (1/2 squared pairwise differences)

Parameters

  • x ((N,) np.ndarray) – Brain map scalar array

  • return_h (bool, default False) – Return distances at which the smoothed variogram was computed

Returns

  • (self.nh,) np.ndarray – Smoothed variogram values

  • (self.nh) np.ndarray – Distances at which smoothed variogram was computed (returned only if return_h is True)

property deltas

proportions of nearest neighbors

Type

np.ndarray or List[float]

property h

distances at which smoothed variogram is computed

Type

np.ndarray

property kernel

smoothing kernel function

Notes

When setting kernel, use name of kernel as defined in config.py.

Type

Callable

property nh

number of variogram distance intervals

Type

int

property nmap

length of brain map

Type

int

permute_map(i=1)

Return randomly permuted brain map.

Returns

Random permutation of target brain map

Return type

(N,) np.ndarray

property pv

percentile of pairwise distances at which to truncate

Type

int

regress(x, y)

Linearly regress x onto y.

Parameters

  • x ((N,) np.ndarray) – Independent variable

  • y ((N,) np.ndarray) – Dependent variable

Returns

  • alpha (float) – Intercept term (offset parameter)

  • beta (float) – Regression coefficient (scale parameter)

  • res (float) – Sum of squared residuals

property resample

whether to resample surrogate maps from target map

Type

bool

smooth_map(x, delta)

Smooth x using delta proportion of nearest neighbors.

Parameters

  • x ((N,) np.ndarray) – Brain map scalars

  • delta (float) – Proportion of neighbors to include for smoothing, in (0, 1)

Returns

Smoothed brain map

Return type

(N,) np.ndarray

property x

brain map scalar array

Type

(N,) np.ndarray

class brainsmash.mapgen.Sampled(x, D, index, ns=500, pv=70, nh=25, knn=1000, b=None, deltas=array([0.3, 0.5, 0.7, 0.9]), kernel='exp', resample=False, verbose=False, seed=None, n_jobs=1)

Bases: object

Sampling implementation of map generator.

Parameters

  • x (filename or 1D np.ndarray) – Target brain map

  • D (filename or (N,N) np.ndarray or np.memmap) – Pairwise distance matrix between elements of x. Each row of D should be sorted. Indices used to sort each row are passed to the index argument. See brainsmash.mapgen.memmap.txt2memmap or the online documentation for more details (brainsmash.readthedocs.io)

  • index (filename or (N,N) np.ndarray or np.memmap) – See above

  • ns (int, default 500) – Take a subsample of ns rows from D when fitting variograms

  • deltas (np.ndarray or List[float], default [0.3, 0.5, 0.7, 0.9]) – Proportions of neighbors to include for smoothing, in (0, 1]

  • kernel (str, default 'exp') – Kernel with which to smooth permuted maps - ‘gaussian’ : gaussian function - ‘exp’ : exponential decay function - ‘invdist’ : inverse distance - ‘uniform’ : uniform weights (distance independent)

  • pv (int, default 70) – Percentile of the pairwise distance distribution (in D) at which to truncate during variogram fitting

  • nh (int, default 25) – Number of uniformly spaced distances at which to compute variogram

  • knn (int, default 1000) – Number of nearest regions to keep in the neighborhood of each region

  • b (float or None, default None) – Gaussian kernel bandwidth for variogram smoothing. if None, three times the distance interval spacing is used.

  • resample (bool, default False) – Resample surrogate map values from the target brain map

  • verbose (bool, default False) – Print surrogate count each time new surrogate map created

  • seed (None or int or np.random.RandomState instance (default None)) – Specify the seed for random number generation (or random state instance)

  • n_jobs (int (default 1)) – Number of jobs to use for parallelizing creation of surrogate maps

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.

:raises ValueError : x and D have inconsistent sizes:

property D

Pairwise distance matrix

Type

(N,N) np.memmap

property b

Gaussian kernel bandwidth

Type

numeric

compute_variogram(x, idx)

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

Parameters

  • x ((N,) np.ndarray) – Brain map

  • idx ((ns,) np.ndarray[int]) – Indices of randomly sampled brain regions

Returns

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

Return type

(ns,ns) np.ndarray

property deltas

proportions of nearest neighbors

Type

np.ndarray or List[float]

property h

distances at which variogram is evaluated

Type

np.ndarray

property index

indexes used to sort each row of dist. matrix

Type

(N,N) np.memmap

property kernel

smoothing kernel function

Notes

When setting kernel, use name of kernel as defined in config.py.

Type

Callable

property knn

number of nearest neighbors included in distance matrix

Type

int

property nh

number of variogram distance intervals

Type

int

property nmap

length of brain map

Type

int

property ns

number of randomly sampled regions used to construct map

Type

int

permute_map()

Return a random permutation of the target brain map.

Returns

Random permutation of target brain map

Return type

(N,) np.ndarray

property pv

percentile of pairwise distances at which to truncate

Type

int

regress(x, y)

Linearly regress x onto y.

Parameters

  • x ((N,) np.ndarray) – Independent variable

  • y ((N,) np.ndarray) – Dependent variable

Returns

  • alpha (float) – Intercept term (offset parameter)

  • beta (float) – Regression coefficient (scale parameter)

  • res (float) – Sum of squared residuals

property resample

whether to resample surrogate map values from target maps

Type

bool

sample()

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

Returns

Indices of randomly sampled areas

Return type

(self.ns,) np.ndarray

smooth_map(x, k)

Smooth x using k nearest neighboring regions.

Parameters

  • x ((N,) np.ndarray) – Brain map

  • k (float) – Number of nearest neighbors to include for smoothing

Returns

x_smooth – Smoothed brain map

Return type

(N,) np.ndarray

Notes

Assumes D provided at runtime has been sorted.

smooth_variogram(u, v, return_h=False)

Smooth a variogram.

Parameters

  • u ((N,) np.ndarray) – Pairwise distances, ie variogram x-coordinates

  • v ((N,) np.ndarray) – Squared differences, ie ariogram y-coordinates

  • return_h (bool, default False) – Return distances at which smoothed variogram is computed

Returns

  • (nh,) np.ndarray – Smoothed variogram samples

  • (nh,) np.ndarray – Distances at which smoothed variogram was computed (returned if return_h is True)

:raises ValueError : u and v are not identically sized:

property x

brain map scalars

Type

(N,) np.ndarray

brainsmash.mapgen.base_fit(x, D, nsurr=100, return_data=False, **params)

Evaluate variogram fits for Base class.

Parameters

  • x ((N,) np.ndarray or filename) – Target brain map

  • D ((N,N) np.ndarray or filename) – Pairwise distance matrix between regions in x

  • nsurr (int, default 100) – Number of simulated surrogate maps from which to compute variograms

  • return_data (bool, default False) – if True, return: 1, the smoothed variogram values for the target brain map; 2, the distances at which the smoothed variograms values were computed; and 3, the surrogate maps’ smoothed variogram values

  • params – Keyword arguments for brainsmash.mapgen.base.Base

Returns

  • if and only if return_data is True

  • emp_var ((M,) np.ndarray) – empirical smoothed variogram values

  • u0 ((M,) np.ndarray) – distances at which variogram values were computed

  • surr_var ((nsurr, M) np.ndarray) – surrogate maps’ smoothed variogram values

Notes

If return_data is False, this function generates and shows a matplotlib plot instance illustrating the fit of the surrogates’ variograms to the target map’s variogram. If return_data is True, this function returns the data needed to generate such a plot (i.e., the variogram values and the corresponding distances).

brainsmash.mapgen.sampled_fit(x, D, index, nsurr=10, return_data=False, **params)

Evaluate variogram fits for Sampled class.

Parameters

  • x ((N,) np.ndarray) – Target brain map

  • D ((N,N) np.ndarray or np.memmap) – Pairwise distance matrix between elements of x

  • index ((N,N) np.ndarray or np.memmap) – See brainsmash.mapgen.sampled.Sampled

  • nsurr (int, default 10) – Number of simulated surrogate maps from which to compute variograms

  • return_data (bool, default False) – if True, return: 1, the smoothed variogram values for the target brain map; 2, the distances at which the smoothed variograms values were computed; and 3, the surrogate maps’ smoothed variogram values

  • params – Keyword arguments for brainsmash.mapgen.sampled.Sampled

Returns

  • if and only if return_data is True

  • emp_var ((M,) np.ndarray) – empirical smoothed variogram values

  • u0 ((M,) np.ndarray) – distances at which variogram values were computed

  • surr_var ((nsurr, M) np.ndarray) – surrogate maps’ smoothed variogram values

Notes

If return_data is False, this function generates and shows a matplotlib plot instance illustrating the fit of the surrogates’ variograms to the target map’s variogram. If return_data is True, this function returns the data needed to generate such a plot (i.e., the variogram values and the corresponding distances).