neuromodes.basis.reconstruct

neuromodes.basis.reconstruct(data: ArrayLike, emodes: ArrayLike, method: str = 'project', mass: spmatrix | ArrayLike | None = None, mode_counts: ArrayLike | None = None, metric: _MetricCallback | _MetricKind | None = 'correlation', check_ortho: bool = True, **cdist_kwargs) → Tuple[NDArray, NDArray, list[NDArray]]

Calculate and score the reconstruction of the given independent data using the provided orthogonal vectors (e.g., geometric eigenmodes).

Parameters

dataarray-like

The input data array of shape (n_verts,) or (n_verts, n_maps), where n_verts is the number of vertices and n_maps is the number of brain maps.

emodesarray-like

The vectors array of shape (n_verts, n_modes), where n_modes is the number of orthogonal vectors.

methodstr, optional

The method used for the decomposition, either ‘project’ to project data into a mass-orthonormal space or ‘regress’ for least-squares fitting. Note that the beta values from ‘regress’ tend towards those from ‘project’ when more basis vectors are provided. For a non-orthonormal basis set, ‘regress’ must be used. Default is ‘project’.

massarray-like, optional

The mass matrix of shape (n_verts, n_verts) used for the decomposition when method is ‘project’. If vectors are orthonormal in Euclidean space, leave as None. See eigen.is_orthonormal_basis for more details. Default is None.

mode_countsarray-like, optional

The sequence of vectors to be used for reconstruction. For example, mode_counts=np.array([10,20,30]) will run three analyses: with the first 10 vectors, with the first 20 vectors, and with the first 30 vectors. Default is None, which uses all vectors provided.

metricstr, optional

The metric used for calculating reconstruction error. Should be one of the options from scipy.spatial.distance.cdist, or None if no scoring is required. Default is ‘correlation’.

check_orthobool, optional

Whether to check if emodes are mass-orthonormal before using the ‘project’ method. Default is True.

**cdist_kwargs

Additional keyword arguments to pass to scipy.spatial.distance.cdist.

Returns

reconnumpy.ndarray

The reconstructed data array of shape (n_verts, nq, n_maps), where nq is the number of different reconstructions ordered in mode_counts. Each slice is the independent reconstruction of each map. Note that if mode_counts includes any constant vector (e.g., the first geometric eigenmode), the reconstructions will be constant for that value of mode_counts (this may also result in warnings/nans for recon_error).

recon_errornumpy.ndarray

The reconstruction error array of shape (nq, n_maps). Each value represents the reconstruction error of one map. If metric is None, this will be empty.

betalist of numpy.ndarray

A list of beta coefficients calculated for each vector.

Raises

ValueError

If mode_counts is not a 1D array of integers within the range [1, n_modes].