bayesian

bayesian

Bayesian model fitting for osipy.

This module provides Bayesian inference for model fitting with uncertainty estimation via maximum a posteriori (MAP) estimation.

GPU/CPU agnostic using the xp array module pattern. NO scipy dependency - uses custom bounded optimization implementation.

BayesianFitter

BayesianFitter(
    n_samples=100,
    prior_std=None,
    noise_std=None,
    chunk_size=None,
    compute_uncertainty=False,
    tolerance=1e-06,
)

Bases: BaseFitter

Bayesian fitter with uncertainty estimation.

Uses maximum a posteriori (MAP) estimation with Laplace approximation for posterior uncertainty estimation.

GPU/CPU is automatic via xp = get_array_module().

PARAMETER	DESCRIPTION
n_samples	Maximum number of MAP iterations. TYPE: int DEFAULT: 100
prior_std	Per-parameter standard deviations for Gaussian priors, shape (n_params,). TYPE: NDArray DEFAULT: None
noise_std	Assumed noise standard deviation. If None, estimated from data. TYPE: float | None DEFAULT: None
chunk_size	Number of voxels per processing chunk. TYPE: int | None DEFAULT: None
compute_uncertainty	If True, add {param}_std ParameterMap objects to the fit_image() result via Laplace approximation at the MAP estimate. TYPE: bool DEFAULT: False
tolerance	Convergence tolerance for relative cost change. TYPE: float DEFAULT: 1e-06

fit_batch

fit_batch(
    model,
    observed_batch,
    bounds_override=None,
    initial_params=None,
)

Fit a batch of voxels using vectorized MAP estimation.

Same structure as LM fit_batch() but with a prior penalty in the cost function.

PARAMETER	DESCRIPTION
model	Model with 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
initial_params	Initial parameter values, shape (n_params, n_voxels). If provided, used instead of model.get_initial_guess_batch(). Also serves as the prior mean. TYPE: NDArray 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 image with optional uncertainty maps.

Calls super().fit_image() for MAP fitting, then adds {param}_std ParameterMap objects via Laplace approximation when compute_uncertainty is True.

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

RETURNS	DESCRIPTION
dict[str, ParameterMap]	Parameter maps, plus {param}_std maps if uncertainty estimation is enabled.