signal_to_conc

signal_to_conc

DSC signal-to-concentration conversion.

This module converts DSC-MRI T2-weighted signal to contrast agent concentration via delta-R2 (OSIPI: Q.EL1.009), the change in transverse relaxation rate.

The TE (OSIPI: Q.MS1.005) is required for the conversion from signal intensity to delta-R2*.

GPU/CPU agnostic using the xp array module pattern. NO scipy dependency - uses custom Levenberg-Marquardt implementation.

References

.. [1] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/ .. [2] Rosen BR et al. (1990). Contrast agents and cerebral hemodynamics. Magn Reson Med 14(2):249-265. .. [3] Ostergaard L et al. (1996). High resolution measurement of cerebral blood flow using intravascular tracer bolus passages. Magn Reson Med 36(5):715-725. .. [4] Dickie BR et al. MRM 2024. doi:10.1002/mrm.30101

DSCAcquisitionParams dataclass

DSCAcquisitionParams(
    te=30.0, tr=1500.0, field_strength=1.5, r2_star=32.0
)

Acquisition parameters for DSC-MRI.

ATTRIBUTE	DESCRIPTION
te	Echo time TE (OSIPI: Q.MS1.005) in milliseconds. TYPE: float
tr	Repetition time (TR) in milliseconds. TYPE: float
field_strength	Main magnetic field strength in Tesla. TYPE: float
r2_star	T2* relaxivity of contrast agent (1/s/mM). Default is for Gd-DTPA at 1.5T. TYPE: float

signal_to_delta_r2

signal_to_delta_r2(
    signal,
    te,
    baseline_frames=10,
    baseline_indices=None,
    baseline_end=None,
)

Convert DSC signal intensity to delta-R2* (OSIPI: Q.EL1.009).

The conversion uses the relationship: S(t) = S0 * exp(-TE * dR2*(t))

Therefore: dR2*(t) = -ln(S(t)/S0) / TE

where TE is the echo time (OSIPI: Q.MS1.005).

PARAMETER	DESCRIPTION
signal	DSC signal intensity, shape (..., n_timepoints). Last dimension is time. TYPE: NDArray[floating]
te	Echo time (OSIPI: Q.MS1.005) in milliseconds. TYPE: float
baseline_frames	Number of initial frames to use for baseline estimation. Ignored if baseline_indices or baseline_end is provided. TYPE: int DEFAULT: 10
baseline_indices	Specific indices to use for baseline calculation. Overrides baseline_frames if provided. TYPE: NDArray[intp] | None DEFAULT: None
baseline_end	End index for baseline (uses frames 0 to baseline_end). Alias for baseline_frames. Overrides baseline_frames if provided. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
NDArray[floating]	Delta-R2* values in 1/s, same shape as input.

RAISES	DESCRIPTION
DataValidationError	If signal contains invalid values.

References

.. [1] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/

Examples:

>>> import numpy as np
>>> from osipy.dsc.concentration import signal_to_delta_r2
>>> signal = np.random.rand(64, 64, 20, 60) * 1000
>>> delta_r2 = signal_to_delta_r2(signal, te=30.0)

delta_r2_to_concentration

delta_r2_to_concentration(
    delta_r2, r2_star=32.0, field_strength=1.5
)

Convert ΔR2* to contrast agent concentration.

Assumes a linear relationship: C(t) = ΔR2(t) / r2

where r2* is the transverse relaxivity of the contrast agent.

PARAMETER	DESCRIPTION
delta_r2	ΔR2* values in s⁻¹. TYPE: NDArray[floating]
r2_star	T2* relaxivity in s⁻¹ mM⁻¹. Default is 32 s⁻¹ mM⁻¹ (typical for Gd-DTPA at 1.5T). TYPE: float DEFAULT: 32.0
field_strength	Field strength in Tesla. Used to scale relaxivity if significantly different from 1.5T. TYPE: float DEFAULT: 1.5

RETURNS	DESCRIPTION
NDArray[floating]	Contrast agent concentration in mM.

Notes

The relaxivity scales approximately linearly with field strength for T2 effects: r2(B) ≈ r2*(1.5T) × (B / 1.5)

Examples:

>>> import numpy as np
>>> delta_r2 = np.random.rand(64, 64, 20, 60) * 10
>>> concentration = delta_r2_to_concentration(delta_r2, r2_star=32.0)

gamma_variate_fit

gamma_variate_fit(concentration, time, baseline_end=None)

Fit gamma-variate function for recirculation removal.

The gamma-variate function models the first-pass bolus: C(t) = K × (t - t0)^α × exp(-(t - t0)/β) for t > t0 C(t) = 0 for t ≤ t0

This allows separation of the first-pass bolus from recirculation.

Uses the shared LevenbergMarquardtFitter via BoundGammaVariateModel.

PARAMETER	DESCRIPTION
concentration	Concentration-time curve, shape (n_timepoints,). TYPE: NDArray[floating]
time	Time points in seconds. TYPE: NDArray[floating]
baseline_end	Index of baseline end. If None, auto-detected. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
tuple[NDArray[floating], dict[str, float]]	First-pass concentration curve and fitted parameters dict.

References

Thompson HK et al. (1964). Indicator Transit Time Considered as a Gamma Variate. Circ Res 14:502-515.

Examples:

>>> import numpy as np
>>> time = np.arange(60) * 1.5  # seconds
>>> concentration = np.random.rand(60) * 5
>>> first_pass, params = gamma_variate_fit(concentration, time)