nifreeze.model.gqi module

Classes and functions for generalized q-sampling

nifreeze.model.gqi.DEFAULT_RIDGE = 0.3

Default ridge \(\lambda\) of the prediction, in units of the Gram matrix averaged over the sphere (see GeneralizedQSamplingFit.predict()); see The ridge and its default for the experiment justifying it.

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, ridge=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. See Generalized q-Sampling Imaging (GQI) for the construction.

The prediction is kernel ridge regression on the GQI basis, around an unpenalized mean per shell:

\[\hat{\mathbf{y}}_o = \mathbf{G}_o (\mathbf{G} + \lambda\mathbf{I})^{-1} (\mathbf{y} - \mathbf{m}) + \mathbf{m}_o,\]

with \(\mathbf{G} = \mathbf{K}\mathbf{K}^{\mathsf T} / n_v\) the Gram matrix of the fitted gradients averaged over the \(n_v\) vertices of the sphere (sphere_gram()), \(\mathbf{G}_o\) that of the predicted gradients with the fitted ones, \(\mathbf{m}\) the mean of each fitted volume’s shell, and \(\mathbf{m}_o\) the mean of the fitted shell nearest to each predicted b-value (shells are b-values rounded to SHELL_DECIMALS). As \(\lambda \to 0\) the prediction interpolates the fitted data, and as \(\lambda \to \infty\) it returns the shell mean; at every \(\lambda\) it keeps the shell’s amplitude.

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

Parameters:

  • gtab (GradientTable) – Gradients of the predicted signal.

  • S0 (ndarray, optional) – Unused.

  • ridge (float, optional) – Ridge \(\lambda\), in units of \(\mathbf{G}\). Defaults to the model’s ridge.

Returns:

The predicted signal, shaped (n_predicted,) for a single voxel or (n_voxels, n_predicted) for a masked volume.

Return type:

ndarray

class nifreeze.model.gqi.GeneralizedQSamplingModel(self, gtab, *, method='standard', sampling_length=1.2, sphere=None, recursion_level=5, ridge=0.3)[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).

  • ridge (float, optional) – Ridge \(\lambda\) of the signal prediction (see GeneralizedQSamplingFit.predict()). Defaults to DEFAULT_RIDGE.

fit(data, *, mask=None)[source]
nifreeze.model.gqi.SHELL_DECIMALS = -2

Decimals to which b-values are rounded to group the volumes into shells.

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.shell_bvalues(bvals)[source]

The b-value of each volume’s shell: its b-value rounded to SHELL_DECIMALS.

Examples

>>> shell_bvalues([5, 995, 1010, 1990, 3020])
array([   0., 1000., 1000., 2000., 3000.])
nifreeze.model.gqi.sphere_gram(kernel, other=None)[source]

Gram matrix of GQI kernels, averaged over the vertices of the sphere.

Averaging over the \(n_v\) vertices, rather than summing, keeps the ridge of GeneralizedQSamplingFit.predict() independent of the density of the sphere.

Parameters:

  • kernel (ndarray) – A forward GQI kernel (gqi_kernel()), shape (n_a, n_vertices).

  • other (ndarray, optional) – Another kernel on the same sphere, shape (n_b, n_vertices) (kernel itself if not given).

Returns:

\(\mathbf{K}_a \mathbf{K}_b^{\mathsf T} / n_v\), shape (n_a, n_b).

Return type:

ndarray