svd

svd

SVD-based deconvolution for DSC-MRI.

This module implements Singular Value Decomposition (SVD) based deconvolution methods for estimating the residue function, cerebral blood flow (CBF, OSIPI: Q.PH1.003), mean transit time (MTT, OSIPI: Q.PH1.006), and arterial delay (Ta, OSIPI: Q.PH1.007) from DSC-MRI concentration data.

GPU/CPU Agnostic: Uses xp.linalg.svd where xp is numpy or cupy depending on input. When input arrays are CuPy arrays, all computations including SVD run on GPU. Results are returned on the same device as input.

NO scipy dependency - uses xp.linalg for SVD (numpy.linalg or cupy.linalg).

For general-purpose deconvolution operations, see also: - osipy.common.convolution.deconv: Matrix-based deconvolution with TSVD/Tikhonov - osipy.common.convolution.convmat: Convolution matrix construction - osipy.common.convolution.invconvmat: Regularized matrix inversion

References

.. [1] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/ .. [2] Ostergaard L et al. (1996). High resolution measurement of cerebral blood flow using intravascular tracer bolus passages. Part I: Mathematical approach and statistical analysis. Magn Reson Med 36(5):715-725. .. [3] Wu O et al. (2003). Tracer arrival timing-insensitive technique for estimating flow in MR perfusion-weighted imaging using singular value decomposition with a block-circulant deconvolution matrix. Magn Reson Med 50(1):164-174. .. [4] Dickie BR et al. MRM 2024. doi:10.1002/mrm.30101

SVDDeconvolutionParams dataclass

SVDDeconvolutionParams(
    method="oSVD",
    threshold=0.2,
    oscillation_index=0.035,
    block_circulant=True,
    regularization="truncation",
)

Parameters for SVD deconvolution.

ATTRIBUTE	DESCRIPTION
method	Deconvolution method: 'sSVD', 'cSVD', or 'oSVD'. TYPE: str
threshold	SVD truncation threshold (fraction of max singular value). Default 0.2 for standard SVD. TYPE: float
oscillation_index	Target oscillation index for oSVD. Default 0.035. TYPE: float
block_circulant	Use block-circulant matrix (for cSVD/oSVD). Default True for cSVD/oSVD methods. TYPE: bool
regularization	Regularization method: 'truncation' or 'tikhonov'. TYPE: str

DeconvolutionResult dataclass

DeconvolutionResult(
    residue_function, cbf, mtt, delay, threshold_used
)

Result of deconvolution.

ATTRIBUTE	DESCRIPTION
residue_function	Estimated residue function R(t), shape (..., n_timepoints). TYPE: NDArray
cbf	Cerebral blood flow (OSIPI: Q.PH1.003), max of scaled R(t), shape (...). Units depend on input scaling. TYPE: NDArray
mtt	Mean transit time (OSIPI: Q.PH1.006), area/max of R(t), shape (...). Units are same as time input. TYPE: NDArray
delay	Arterial delay Ta (OSIPI: Q.PH1.007) relative to AIF, shape (...). TYPE: NDArray
threshold_used	Actual SVD threshold used. TYPE: float

StandardSVDDeconvolver

Bases: BaseDeconvolver

Standard SVD (sSVD) deconvolution strategy.

Uses a lower-triangular Toeplitz matrix for causal convolution. Sensitive to bolus arrival time delays.

name property

name

Return human-readable component name.

reference property

reference

Return primary literature citation.

deconvolve

deconvolve(concentration, aif, time, mask=None, **kwargs)

Perform sSVD deconvolution to recover the residue function.

CircularSVDDeconvolver

Bases: BaseDeconvolver

Circular SVD (cSVD) deconvolution strategy.

Uses a block-circulant matrix to make deconvolution insensitive to bolus arrival time delays (OSIPI: Q.PH1.007).

name property

name

Return human-readable component name.

reference property

reference

Return primary literature citation.

deconvolve

deconvolve(concentration, aif, time, mask=None, **kwargs)

Perform cSVD deconvolution to recover the residue function.

OscillationSVDDeconvolver

Bases: BaseDeconvolver

Oscillation-index SVD (oSVD) deconvolution strategy.

Automatically selects the SVD truncation threshold to minimize oscillations in the residue function while preserving CBF (OSIPI: Q.PH1.003) estimates.

name property

name

Return human-readable component name.

reference property

reference

Return primary literature citation.

deconvolve

deconvolve(concentration, aif, time, mask=None, **kwargs)

Perform oSVD deconvolution to recover the residue function.

deconvolve_oSVD

deconvolve_oSVD(
    concentration, aif, time, mask=None, params=None
)

Oscillation-index SVD (oSVD) deconvolution.

The oSVD method automatically selects the SVD truncation threshold to minimize oscillations in the residue function while preserving the CBF estimate.

GPU/CPU agnostic - uses xp.linalg.svd where xp matches input arrays.

PARAMETER	DESCRIPTION
concentration	Tissue concentration curves. TYPE: NDArray[floating]
aif	Arterial input function. TYPE: NDArray[floating]
time	Time points in seconds. TYPE: NDArray[floating]
mask	Brain mask. TYPE: NDArray[bool_] | None DEFAULT: None
params	Deconvolution parameters. TYPE: SVDDeconvolutionParams | None DEFAULT: None

RETURNS	DESCRIPTION
DeconvolutionResult	Deconvolution results.

deconvolve_cSVD

deconvolve_cSVD(
    concentration, aif, time, mask=None, params=None
)

Circular SVD (cSVD) deconvolution.

Uses block-circulant matrix to make deconvolution insensitive to bolus arrival time delays.

GPU/CPU agnostic - uses xp.linalg.svd where xp matches input arrays.

PARAMETER	DESCRIPTION
concentration	Tissue concentration curves. TYPE: NDArray[floating]
aif	Arterial input function. TYPE: NDArray[floating]
time	Time points in seconds. TYPE: NDArray[floating]
mask	Brain mask. TYPE: NDArray[bool_] | None DEFAULT: None
params	Deconvolution parameters. TYPE: SVDDeconvolutionParams | None DEFAULT: None

RETURNS	DESCRIPTION
DeconvolutionResult	Deconvolution results.