neuromodes.basis.decompose

neuromodes.basis.decompose(data: ArrayLike, emodes: ArrayLike, method: str = 'project', mass: spmatrix | ArrayLike | None = None, check_ortho: bool = True) → NDArray

Calculate the decomposition of the given data onto a basis set.

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 maps.
emodesarray-like: The vectors array of shape (n_verts, n_modes), where n_modes is the number of basis 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.
check_orthobool, optional: Whether to check if emodes are mass-orthonormal before using the ‘project’ method. Default is True.

Returns

numpy.ndarray: The beta coefficients array of shape (n_modes, n_maps), obtained from the decomposition.

Raises

ValueError: If emodes does not have shape (n_verts, n_modes), where n_verts ≥ n_modes.
ValueError: If data does not have shape (n_verts,) or (n_verts, n_maps).
ValueError: If method=’project’ and emodes columns do not form an orthonormal basis set (when check_ortho=True).
ValueError: If method is not ‘project’ or ‘regress’.