nifreeze.model.gqi module

Classes and functions for generalized q-sampling

nifreeze.model.gqi.DEFAULT_SPHERE_RECURSION_LEVEL = 5

Default icosahedral subdivision level of the ODF sampling sphere (1026 vertices); see Sphere density and the default recursion level for the experiment justifying it.

nifreeze.model.gqi.FREE_WATER_DIFFUSIVITY_6D = 0.01506

\(6 D\) where \(D\) is the free-water diffusion coefficient; the GQI scaling factor \(\sqrt{6 D \tau}\) with \(\tau\) folded into the b-value.

class nifreeze.model.gqi.GeneralizedQSamplingFit(self, model, data)[source]

Bases: OdfFit

Store the model and signal data for a fitted voxel (or voxels).

Parameters:

  • model (GeneralizedQSamplingModel) – The GQI model instance this fit belongs to.

  • data (ndarray) – Signal values, shaped (n_gradients,) for a single voxel or (n_voxels, n_gradients) for a masked volume.

odf(sphere=None)[source]

Compute the discrete orientation distribution function (ODF/SDF).

Applies the forward GQI kernel to the fitted signal, implementing the signal-to-SDF transform of Yeh et al. (2010). This satisfies the OdfFit contract shared by DIPY’s ODF models and is distinct from predict(), which maps signal back to signal.

Parameters:

sphere (Sphere, optional) – ODF sampling sphere. When None (default), the model’s sphere is reused and the pre-computed forward kernel is applied directly, avoiding recomputation.

Returns:

The discrete ODF, shaped (n_vertices,) for a single voxel or (n_voxels, n_vertices) for a masked volume. Unlike predict(), the result is not clamped to non-negative values (matching DIPY).

Return type:

ndarray

predict(gtab, *, S0=None)[source]

Predict the diffusion signal on gtab from the fitted data.

Note

This signal-to-signal prediction is a NiFreeze extension of GQI; Yeh et al. (2010) defines only the forward signal-to-SDF transform. It maps the fitted signal to the SDF and back via a Tikhonov-regularized reconstruction kernel (prediction_kernel()). See Generalized q-Sampling Imaging (GQI) for the construction.

The result is clamped to non-negative values. S0 is accepted for API compatibility with the other NiFreeze DWI models but is unused.

Notes

The kernel round-trip approximately preserves signal scale for the "standard" (sinc) kernel, but not for "gqi2"; prefer "standard" when the predicted amplitude matters. See Reconstruction fidelity and the intercept behaviour.

class nifreeze.model.gqi.GeneralizedQSamplingModel(self, gtab, *, method='standard', sampling_length=1.2, sphere=None, recursion_level=5)[source]

Bases: OdfModel

Generalized Q-Sampling Imaging.

Parameters:

  • gtab (GradientTable) – Gradient table of the data to fit.

  • method ({“standard”, “gqi2”}, optional) – GQI reconstruction variant. Defaults to "standard" (the sinc basis of Yeh et al., 2010, Eq. 6/9).

    Note

    This default deliberately deviates from DIPY, whose GQI model defaults to "gqi2". NiFreeze uses GQI as a signal predictor, and "standard" round-trips the diffusion signal more faithfully than "gqi2" (see Reconstruction fidelity and the intercept behaviour). Anyone cross-referencing DIPY should note the changed default.

  • sampling_length (float, optional) – Diffusion sampling length \(\sigma\) (lambda in Yeh Eq. 9); recommended range 1–1.3.

  • sphere (Sphere, optional) – ODF sampling sphere. When given, recursion_level is ignored.

  • recursion_level (int, optional) – Subdivision level of the icosahedral ODF sampling sphere built when sphere is not provided; higher values give a denser sphere. Defaults to DEFAULT_SPHERE_RECURSION_LEVEL. See Sphere density and the default recursion level for the experiment justifying the default (past the fidelity knee for both single-shell and grid acquisitions, while denser spheres only keep paying off for grid/multi-shell data).

fit(data, *, mask=None)[source]
nifreeze.model.gqi.INVERSE_LAMBDA = 1e-06

Tikhonov regularization weight \(\lambda_0\) for the reconstruction kernel \((\mathbf{K}\mathbf{K}^{\mathsf T} + \lambda_0\mathbf{I})^{-1}\mathbf{K}\) (see prediction_kernel()).

nifreeze.model.gqi.gqi_kernel(gtab, param_lambda, sphere, method='standard')[source]

Forward GQI kernel, shape (n_gradients, n_vertices).

Ported from DIPY’s dipy.reconst.gqi, modularized as a function.

Parameters:

  • gtab (GradientTable) – The gradient table for which the kernel is computed.

  • param_lambda (float) – The GQI sampling length (\(\lambda\)).

  • sphere (Sphere) – The sphere whose vertices define the ODF sampling directions.

  • method ({“standard”, “gqi2”}, optional) – GQI variant. "standard" implements the sinc reconstruction of Yeh et al. (2010), Eq. 6/9 (verified to machine precision against the paper and DIPY); "gqi2" uses the \(L^2\)-weighted basis of Eq. 8 (squared_radial_component(), imported from DIPY). An unknown value falls back to "standard" with a warning.

Returns:

The forward GQI kernel with shape (n_gradients, n_vertices).

Return type:

ndarray

nifreeze.model.gqi.prediction_kernel(gtab, param_lambda, sphere, method='standard')[source]

Compute the Tikhonov-regularized reconstruction kernel for GQI.

Parameters:

  • gtab (GradientTable) – The gradient table for which the kernel is computed.

  • param_lambda (float) – The GQI sampling length (\(\lambda\)).

  • sphere (Sphere) – The sphere whose vertices define the ODF sampling directions.

  • method (str, optional) – GQI variant, either "standard" or "gqi2".

Returns:

The reconstruction kernel with shape (n_gradients, n_vertices).

Return type:

ndarray

Notes

With the forward GQI kernel \(\mathbf{K} \in \mathbb{R}^{n_g \times n_v}\), the reconstruction kernel is

\[\mathbf{K}^{+} = (\mathbf{K} \mathbf{K}^T + \lambda_0 \mathbf{I})^{-1} \mathbf{K}\]

where \(\lambda_0 = 10^{-6}\) (INVERSE_LAMBDA) regularizes the inversion and \(\mathbf{I}\) is the \(n_g \times n_g\) identity.