base

base

Base classes for model fitting algorithms.

This module provides the abstract base class for all fitting algorithms. Fitters operate on FittableModel instances — models with all independent variables already bound so only free parameters remain.

The BaseFitter.fit_image() concrete method handles mask extraction, chunking, GPU transfer, and ParameterMap assembly. Subclasses only need to implement fit_batch().

BaseFitter

Bases: ABC

Abstract base class for model fitting algorithms.

Subclasses implement fit_batch() for the core optimization. fit_image() is a concrete method that handles image-level boilerplate (masking, chunking, GPU, ParameterMap assembly).

fit_batch abstractmethod

fit_batch(model, observed_batch, bounds_override=None)

Core fitting algorithm for a batch of voxels.

PARAMETER	DESCRIPTION
model	Model with all independent variables bound. TYPE: FittableModel
observed_batch	Observed data, shape (n_observations, n_voxels). TYPE: NDArray
bounds_override	Per-parameter bound overrides. TYPE: dict DEFAULT: None

RETURNS	DESCRIPTION
params	Fitted parameters, shape (n_params, n_voxels). TYPE: NDArray
r2	R-squared values, shape (n_voxels,). TYPE: NDArray
converged	Convergence flags, shape (n_voxels,). TYPE: NDArray

fit_image

fit_image(
    model,
    data,
    mask=None,
    bounds_override=None,
    progress_callback=None,
)

Fit model to entire image volume.

Concrete method that handles mask extraction, chunking, GPU transfer, and ParameterMap assembly. Calls fit_batch() per chunk.

PARAMETER	DESCRIPTION
model	Model with all independent variables bound. TYPE: FittableModel
data	Image data, shape (x, y, z, n_observations). TYPE: NDArray
mask	Boolean mask of voxels to fit, shape (x, y, z). TYPE: NDArray[bool_] | None DEFAULT: None
bounds_override	Per-parameter bound overrides. TYPE: dict DEFAULT: None
progress_callback	Progress callback (0.0 to 1.0). TYPE: Callable[[float], None] | None DEFAULT: None

RETURNS	DESCRIPTION
dict[str, ParameterMap]	Mapping of parameter names to ParameterMap objects.