nifreeze.model.base module

Base infrastructure for nifreeze’s models.

class nifreeze.model.base.BaseModel(self, dataset, **kwargs)

Bases: ABC

Defines the interface and default methods.

Implements the interface of dipy.reconst.base.ReconstModel. Instead of inheriting from the abstract base, this implementation follows type adaptation principles, as it is easier to maintain and to read (see https://www.youtube.com/watch?v=3MNVP9-hglc).

Base initialization.

abstract fit_predict(index: int | None = None, **kwargs) → ndarray | None

Fit and predict the indicated index of the dataset (abstract signature).

In the default Leave-One-Volume-Out (LOVO) mode, index names the volume to hold out: the model is fit on every other volume and used to predict the held-out one. This held-out independence sets a base to claim that predictions are unbiased.

If index is None, the model is executed in single-fit mode: it is fit once on all available data (no volume held out). The fit is locked (_locked_fit evaluates to true), such that later calls reuse the fit object without refitting.

Parameters:

index (int, optional) – The volume index to hold out and predict (LOVO mode). If None, single-fit mode is used and no held-out prediction is produced.

single_fit_is_canary: bool = False

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

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

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

Return the expectation map.

Parameters:

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

nifreeze.model.base.MASK_ABSENCE_WARN_MSG = 'No mask provided; consider using a mask to avoid issues in model optimization.'

Mask warning message.

class nifreeze.model.base.ModelFactory(self, /, *args, **kwargs)

Bases: object

A factory for instantiating data models.

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

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.

Returns:

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

Return type:

ReconstModel

nifreeze.model.base.PREDICTED_MAP_ERROR_MSG = 'This model requires the predicted map at initialization'

Oracle requirement error message.

nifreeze.model.base.SINGLE_FIT_CANARY_MSG = 'Single-fit for this model is a self-consistency check (canary): the held-out volume is also in the training set, so it is reproduced near-perfectly. It validates the implementation rather than being a genuine prediction.'

Single-fit canary warning message.

exception nifreeze.model.base.SingleFitCanaryWarning

Bases: UserWarning

Single-fit for this model only makes sense as a self-consistency canary.

class nifreeze.model.base.TrivialModel(self, dataset, predicted=None, **kwargs)

Bases: BaseModel

A trivial model that returns a given map always.

Implement object initialization.

fit_predict(*_, **kwargs) → ndarray | None

Return the reference map.

nifreeze.model.base.UNSUPPORTED_MODEL_ERROR_MSG = 'Unsupported model <{model}>.'

Unsupported model error message