neuromodes.basis.reconstruct_timeseries

neuromodes.basis.reconstruct_timeseries(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, NDArray, NDArray, list[NDArray]]

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

Parameters

dataarray-like

The input data array of shape (n_verts, n_timepoints), where n_verts is the number of vertices and n_timepoints is the number of timepoints.

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

fc_reconnumpy.ndarray

The functional connectivity reconstructed data array of shape (n_edges, nq), where n_edges = n_verts*(n_verts-1)/2 and nq is the number of different reconstructions ordered in mode_counts. The FC matrix returned is r-to-z (arctanh) transformed and vectorized. 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).

fc_recon_errornumpy.ndarray

The functional reconstruction accuracy of shape (nq,). If metric is None, this will be empty.

reconnumpy.ndarray

The reconstructed data array of shape (n_verts, nq, n_timepoints), where nq is the number of different reconstructions ordered in mode_counts. Each slice is the independent reconstruction of each timepoint. 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_timepoints). Each value represents the reconstruction error at one timepoint. If metric is None, this will be empty.

betalist of numpy.ndarray

A list of beta coefficients calculated for each vector.

Raises

ValueError

If data does not have shape (n_verts, n_timepoints).