eigenstrapping.fit.surface_fit

eigenstrapping.fit.surface_fit(x, D=None, index=None, nsurrs=10, num_modes=100, return_data=False, extra_diags=False, surrs=None, **params)[source]

Evaluate variogram fits for :class: eigenstrapping.SurfaceEigenstrapping to determine how many modes to decompose surface map with. Returns two plots:

left - variogram fit middle - surrogate pairwise correlation with original map x right - histogram of surrogate residuals with original map x

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 :method:`variogram.variogram`

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

  • return_data (bool, default False) – if True, return the surrogates

  • extra_diags (bool, default False) –

    if True, return extra diagnostics

    1. modal power spectra of original and surrogates

    2. Local Moran’s I of original and surrogates

  • surrs ((m,N) np.ndarray or np.memmap or path to file) – If not None, skips null generation and calculates the variogram for the given set of surrogates in surrs. Expects these to be of shape (m,N) in array-like or str of path to file (in .txt or .npy format) containing this array.

  • params – Keyword arguments for :class: eigenstrapping.SurfaceEigenstrapping or :method: variogram.variogram. If eigenmodes and eigenvalues have been precomputed for the surface that x exists on, then pass them as evals and emodes. If they’re not given, then a surface must be given. See :class: eigenstrapping.Eigenstrapping for more details.

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).