nifreeze.model package

Data models.

class nifreeze.model.AverageDWIModel(self, dataset: nifreeze.data.dmri.base.DWI, stat: str = 'median', atol_low: float = 100.0, atol_high: float = 100.0, detrend: bool = False, **kwargs)[source]

Bases: ExpectationModel

A trivial model that returns an average DWI volume.

Implement object initialization.

Parameters:

  • dataset (DWI) – Reference to a DWI object.

  • stat (str, optional) – Whether the summary statistic to apply is "mean" or "median".

  • atol_low (float, optional) – A lower bound for the b-value corresponding to the diffusion weighted images that will be averaged.

  • atol_low (float, optional) – An upper bound for the b-value corresponding to the diffusion weighted images that will be averaged.

  • detrend (bool, optional) – Whether the overall distribution of each diffusion weighted image will be standardized and centered around the src.nifreeze.model.base.DEFAULT_CLIP_PERCENTILE percentile.

fit_predict(index: int | None = None, *_, **kwargs) → ndarray[source]

Return the average map.

class nifreeze.model.BSplinePETModel(self, dataset: nifreeze.data.pet.base.PET, n_ctrl: int = 3, order: int = 3, **kwargs)[source]

Bases: BasePETModel

A PET imaging realignment model based on B-Spline approximation.

Create the B-Spline interpolating matrix.

Parameters:

  • n_ctrl (int, optional) – Number of internal B-Spline control points that determine the flexibility of the temporal fit. Given a hold-out index, all frames except the held-out one are used in a least-squares fit against the B-spline basis. n_ctrl sets the number of degrees of freedom of that basis. Fewer control points produce a smoother approximation; more control points allow the curve to track finer temporal detail. Boundary knots (order + 1 at each end) are added automatically to ensure proper edge behavior.

  • order (int, optional) – Order of the B-Spline approximation.

fit_predict(index: int | None = None, **kwargs) → ndarray | None[source]

Return the corrected volume using B-spline interpolation.

Predictions for times earlier than the configured start time will return the prediction for the start time.

class nifreeze.model.DKIModel(self, dataset: nifreeze.data.dmri.base.DWI, max_b: float | int | None = None, **kwargs)[source]

Bases: BaseDWIModel

A wrapper of DiffusionKurtosisModel.

Initialization.

Parameters:

dataset (DWI) – Reference to a DWI object.

applicable_schemes: frozenset[str] = frozenset({'multi-shell'})

Acquisition schemes (as labelled by find_shelling_scheme()) the model supports.

requires_multishell: bool = True

Whether the model requires more than one non-zero shell.

class nifreeze.model.DTIModel(self, dataset: nifreeze.data.dmri.base.DWI, max_b: float | int | None = None, **kwargs)[source]

Bases: BaseDWIModel

A wrapper of dipy.reconst.dti.TensorModel.

Initialization.

Parameters:

dataset (DWI) – Reference to a DWI object.

applicable_schemes: frozenset[str] = frozenset({'multi-shell', 'single-shell'})

Acquisition schemes (as labelled by find_shelling_scheme()) the model supports.

class nifreeze.model.ExpectationModel(self, dataset, stat='median', **kwargs)[source]

Bases: BaseModel

A trivial model that returns an expectation map (for example, average).

Initialize a new model.

fit_predict(index: int | None = None, **kwargs) → ndarray[source]

Return the expectation map.

Parameters:

index (int) – The volume index that is left-out in fitting, and then predicted.

class nifreeze.model.GPLOOModel(self, dataset: nifreeze.data.dmri.base.DWI, hyperparameters: str | pathlib.Path | Mapping[str, Any] | NoneType = None, **kwargs)[source]

Bases: ClosedFormLOVOMixin, GPModel

A Gaussian process with exact, closed-form leave-one-volume-out prediction.

With hyperparameters held fixed across folds, the GP posterior mean is a linear smoother of the other volumes (see nifreeze.model.lovo), so all LOVO predictions come from one matrix instead of one GP fit per volume. Hyperparameters are either loaded (hyperparameters), e.g., pooled across the subjects of an acquisition protocol, or fitted once on a random voxel subsample of all volumes.

Initialization.

Parameters:

  • dataset (DWI) – Reference to a DWI object.

  • hyperparameters (os.pathlike or Mapping, optional) – A hyperparameter record (see save_hyperparameters()). When given, no hyperparameter is fitted at run time.

  • nvox_prefit (int, optional) – Number of voxels used to fit the hyperparameters (all if None).

  • random_state (int, optional) – Seed for the voxel subsample.

class nifreeze.model.GPModel(self, dataset: nifreeze.data.dmri.base.DWI, max_b: float | int | None = None, **kwargs)[source]

Bases: BaseDWIModel

A wrapper of GaussianProcessModel.

The Gaussian process does not follow the DIPY Model(gtab).fit(data) convention that BaseDWIModel implements: it is constructed from a kernel_model and receives the gradient table at fit time, fitting all voxels at once (vectorized across GP targets). _fit/fit_predict are therefore overridden here rather than reusing the chunked DIPY path.

Initialization.

Parameters:

dataset (DWI) – Reference to a DWI object.

applicable_schemes: frozenset[str] = frozenset({'multi-shell', 'single-shell'})

Acquisition schemes (as labelled by find_shelling_scheme()) the model supports.

fit_predict(index: int | None = None, **kwargs) → ndarray | None[source]

Fit the GP (LOVO or single-fit) and predict the held-out orientation.

single_fit_is_canary: bool = True

Whether single-fit only makes sense as a self-consistency canary (see _warn_single_fit_canary()).

class nifreeze.model.GQIKRRModel(self, dataset: nifreeze.data.dmri.base.DWI, krr_lambda: float | None = 0.3, krr_lambda_grid: Sequence[float] = (np.float64(0.0001), np.float64(0.00031622776601683794), np.float64(0.001), np.float64(0.0031622776601683794), np.float64(0.01), np.float64(0.03162277660168379), np.float64(0.1), np.float64(0.31622776601683794), np.float64(1.0), np.float64(3.1622776601683795), np.float64(10.0), np.float64(31.622776601683793), np.float64(100.0)), **kwargs)[source]

Bases: ClosedFormLOVOMixin, GQIModel

GQI with closed-form leave-one-volume-out prediction.

The prediction of GQIModel is kernel ridge regression on the GQI basis, around a mean per shell (see predict()). With the same ridge \(\lambda\), the predictions of all volumes come from one matrix, built from \(\mathbf{A} = \mathbf{G} + \lambda \mathbf{I}\), instead of one fit per volume. Both models share their default ridge.

Initialization.

Parameters:

  • dataset (DWI) – Reference to a DWI object.

  • krr_lambda (float, optional) – Ridge \(\lambda\), the ridge of GQIModel (which takes precedence when given). Defaults to DEFAULT_RIDGE. If None, it is chosen from krr_lambda_grid by closed-form LOVO error on a random voxel subsample, on the dataset the model is built on; the ridge chosen then changes with the motion in the data.

  • krr_lambda_grid (Sequence of float, optional) – Candidate ridge strengths.

  • nvox_prefit (int, optional) – Number of voxels used to choose the ridge strength, when krr_lambda is None (all if None).

  • random_state (int, optional) – Seed for the voxel subsample.

class nifreeze.model.ModelFactory(self, /, *args, **kwargs)[source]

Bases: object

A factory for instantiating data models.

static init(model: str | None = None, **kwargs)[source]

Instantiate a diffusion model.

Parameters:

model (str) – Diffusion model. Options: "DTI", "DKI", "GQI", "GP", "S0", "AverageDWI". "GP" (aliases "GPR", "GaussianProcess") builds a GPModel; pass kernel_model through kwargs to select the covariance. "GP-LOO" (GPLOOModel) and "GQI-KRR" (GQIKRRModel) predict each held-out volume in closed form (see nifreeze.model.lovo).

Returns:

model – A model object compliant with DIPY’s interface.

Return type:

ReconstModel

class nifreeze.model.TrivialModel(self, dataset, predicted=None, **kwargs)[source]

Bases: BaseModel

A trivial model that returns a given map always.

Implement object initialization.

fit_predict(*_, **kwargs) → ndarray | None[source]

Return the reference map.

Submodules