mrsiprep.connectivity.connectivity

Perturbation-based metabolite connectivity.

Builds a per-parcel feature vector from many CRLB-scaled noise perturbations of each metabolite map (z-scored per metabolite before parcel averaging, so no single metabolite's scale dominates the correlation), then correlates parcels over that vector. This mirrors the statistical approach used in the mrsitoolbox MetSiM pipeline (Randomize.perturbate + MeSiM.parcellate_vectorized), but is a from-scratch, vectorized implementation rather than a port of that code.

Functions

build_parcel_indexer(atlas_3d, parcel_ids)

Map each voxel to a 0-based row index into parcel_ids (or -1 if the voxel's label isn't in parcel_ids), so per-parcel reductions for every metabolite/perturbation can share one np.bincount call per array instead of one scipy.ndimage pass per metabolite per parcel.

compute_metabolic_profiles(metabolite_maps, ...)

CRLB-scaled Monte Carlo perturbation of every metabolite map, z-scored and parcellated n_perturbations times (Instrella & Juchem 2024 uncertainty propagation), yielding the augmented per-parcel feature matrix that both regional-profile consumers and compute_metabolite_connectivity build on.

compute_metabolite_connectivity(...[, ...])

Convenience wrapper: profile estimation immediately followed by correlation.

correlate_metabolic_profiles(profiles[, method])

Metabolic similarity matrix from an already-computed MetabolicProfileResult -- the optional add-on step over profile estimation.

parcellate_means(image_4d, atlas_3d, parcel_ids)

Per-metabolite, per-parcel mean that skips NaN voxels (matching the reference implementation's np.nanmean over a boolean mask), computed for all metabolites in one vectorized pass via np.bincount rather than one scipy.ndimage label-reduction pass per metabolite.

parcellate_zscored(perturbed_4d, atlas_3d, ...)

perturb_metabolite_map(signal, crlb, brainmask)

Classes

ConnectivityResult(similarity, ...)

MetabolicProfileResult(features, ...)

Perturbation-augmented regional metabolic profiles (features), the shared input to any downstream analysis that treats a parcel's metabolite panel as a single feature vector -- notably connectivity (compute_metabolite_connectivity), but reusable independently of it.
class mrsiprep.connectivity.connectivity.ConnectivityResult(similarity: 'pd.DataFrame', parcel_concentrations: 'np.ndarray', metabolites: 'list[str]', parcel_ids: 'np.ndarray', method: 'str', n_perturbations: 'int', sigma_scale: 'float', gm_weighted: 'bool')[source]

Bases: object

Parameters:

  • similarity (DataFrame)

  • parcel_concentrations (ndarray)

  • metabolites (list[str])

  • parcel_ids (ndarray)

  • method (str)

  • n_perturbations (int)

  • sigma_scale (float)

  • gm_weighted (bool)

gm_weighted: bool
metabolites: list[str]
method: str
n_perturbations: int
parcel_concentrations: ndarray
parcel_ids: ndarray
sigma_scale: float
similarity: DataFrame
class mrsiprep.connectivity.connectivity.MetabolicProfileResult(features, parcel_concentrations, metabolites, parcel_ids, n_perturbations, sigma_scale, gm_weighted)[source]

Bases: object

Perturbation-augmented regional metabolic profiles (features), the shared input to any downstream analysis that treats a parcel's metabolite panel as a single feature vector -- notably connectivity (compute_metabolite_connectivity), but reusable independently of it.

Parameters:

  • features (ndarray)

  • parcel_concentrations (ndarray)

  • metabolites (list[str])

  • parcel_ids (ndarray)

  • n_perturbations (int)

  • sigma_scale (float)

  • gm_weighted (bool)

features: ndarray
gm_weighted: bool
metabolites: list[str]
n_perturbations: int
parcel_concentrations: ndarray
parcel_ids: ndarray
sigma_scale: float
mrsiprep.connectivity.connectivity.build_parcel_indexer(atlas_3d, parcel_ids)[source]

Map each voxel to a 0-based row index into parcel_ids (or -1 if the voxel's label isn't in parcel_ids), so per-parcel reductions for every metabolite/perturbation can share one np.bincount call per array instead of one scipy.ndimage pass per metabolite per parcel.

Parameters:

  • atlas_3d (ndarray)

  • parcel_ids (ndarray)

Return type:

ndarray

mrsiprep.connectivity.connectivity.compute_metabolic_profiles(metabolite_maps, crlb_maps, brainmask_path, atlas_path, parcel_ids, n_perturbations=50, sigma_scale=2.0, nthreads=1, seed=None, gm_fraction_path=None)[source]

CRLB-scaled Monte Carlo perturbation of every metabolite map, z-scored and parcellated n_perturbations times (Instrella & Juchem 2024 uncertainty propagation), yielding the augmented per-parcel feature matrix that both regional-profile consumers and compute_metabolite_connectivity build on.

Parameters:

  • metabolite_maps (dict[str, Path])

  • crlb_maps (dict[str, Path])

  • brainmask_path (Path)

  • atlas_path (Path)

  • parcel_ids (list[int])

  • n_perturbations (int)

  • sigma_scale (float)

  • nthreads (int)

  • seed (int | None)

  • gm_fraction_path (Path | None)

Return type:

MetabolicProfileResult

mrsiprep.connectivity.connectivity.compute_metabolite_connectivity(metabolite_maps, crlb_maps, brainmask_path, atlas_path, parcel_ids, method='spearman', n_perturbations=50, sigma_scale=2.0, nthreads=1, seed=None, gm_fraction_path=None)[source]

Convenience wrapper: profile estimation immediately followed by correlation. Prefer calling compute_metabolic_profiles() once and reusing its result across multiple --connectivity-method values, or when profiles are needed without a similarity matrix.

Parameters:

  • metabolite_maps (dict[str, Path])

  • crlb_maps (dict[str, Path])

  • brainmask_path (Path)

  • atlas_path (Path)

  • parcel_ids (list[int])

  • method (str)

  • n_perturbations (int)

  • sigma_scale (float)

  • nthreads (int)

  • seed (int | None)

  • gm_fraction_path (Path | None)

Return type:

ConnectivityResult

mrsiprep.connectivity.connectivity.correlate_metabolic_profiles(profiles, method='spearman')[source]

Metabolic similarity matrix from an already-computed MetabolicProfileResult -- the optional add-on step over profile estimation.

Parameters:
Return type:

ConnectivityResult

mrsiprep.connectivity.connectivity.parcellate_means(image_4d, atlas_3d, parcel_ids, parcel_index=None, voxel_weights=None)[source]

Per-metabolite, per-parcel mean that skips NaN voxels (matching the reference implementation's np.nanmean over a boolean mask), computed for all metabolites in one vectorized pass via np.bincount rather than one scipy.ndimage label-reduction pass per metabolite.

If voxel_weights is given (e.g. a GM partial-volume fraction map), the per-parcel value is a weighted mean instead of a plain mean — voxels with low GM fraction (partial WM/CSF contamination at the parcel boundary) contribute proportionally less, since chimera cortical parcels are GM structures and connectivity should reflect GM signal specifically.

Parameters:

  • image_4d (ndarray)

  • atlas_3d (ndarray)

  • parcel_ids (ndarray)

  • parcel_index (ndarray | None)

  • voxel_weights (ndarray | None)

Return type:

ndarray

mrsiprep.connectivity.connectivity.parcellate_zscored(perturbed_4d, atlas_3d, parcel_ids, parcel_index=None, voxel_weights=None)[source]
Parameters:

  • perturbed_4d (ndarray)

  • atlas_3d (ndarray)

  • parcel_ids (ndarray)

  • parcel_index (ndarray | None)

  • voxel_weights (ndarray | None)

Return type:

ndarray

mrsiprep.connectivity.connectivity.perturb_metabolite_map(signal, crlb, brainmask, sigma_scale=2.0, rng=None)[source]
Parameters:

  • signal (ndarray)

  • crlb (ndarray)

  • brainmask (ndarray)

  • sigma_scale (float)

  • rng (Generator | None)

Return type:

ndarray