cedalion.dot.image_recon

Solver for the image reconstruction problem.

Module Attributes

REG_PAPER_MUA_SBF	Optimal set of regularization parameters according to an optimization study for a ball squeezing dataset.
SBF_GAUSSIANS_DENSE	Optimal set of Gaussian SBF parameters according to an optimization study for a ball squeezing dataset.
SBF_GAUSSIANS_SPARSE	A sparse set of gaussians SBFs.

Functions

estimate_alpha_meas(C_meas[, K])

Implements a heuristic for choosing alpha_meas.

Classes

GaussianSpatialBasisFunctions(head_model, ...)	Gaussian Spatial Basis Functions.
ImageRecon(Adot, *[, alpha_meas, ...])	Implements image reconstruction methods for diffuse optical tomography.
OriginalGaussianSpatialBasisFunctions(...)
SpatialBasisFunctions()	Base for SBF implementations.

cedalion.dot.image_recon.REG_PAPER_MUA_SBF = {'alpha_meas': 10000.0, 'alpha_spatial': 0.01, 'apply_c_meas': True, 'lambda_R_conc': 1e-06}

Optimal set of regularization parameters according to an optimization study for a ball squeezing dataset. Carlton et al. [CAK+26].

cedalion.dot.image_recon.SBF_GAUSSIANS_DENSE = {'mask_threshold': -2, 'sigma_brain': <Quantity(1, 'millimeter')>, 'sigma_scalp': <Quantity(5, 'millimeter')>, 'threshold_brain': <Quantity(1, 'millimeter')>, 'threshold_scalp': <Quantity(5, 'millimeter')>}

Optimal set of Gaussian SBF parameters according to an optimization study for a ball squeezing dataset. Carlton et al. [CAK+26].

cedalion.dot.image_recon.SBF_GAUSSIANS_SPARSE = {'mask_threshold': -2, 'sigma_brain': <Quantity(5, 'millimeter')>, 'sigma_scalp': <Quantity(20, 'millimeter')>, 'threshold_brain': <Quantity(5, 'millimeter')>, 'threshold_scalp': <Quantity(20, 'millimeter')>}

A sparse set of gaussians SBFs.

cedalion.dot.image_recon.estimate_alpha_meas(C_meas, K=0.01)

Implements a heuristic for choosing alpha_meas.

The strength of the regularization is determined by the relative scale of the C and R regularization matrices, which is encoded in the ratio:

K = median(eig( lambda_meas C )) / max(eig( lambda_R A R A’))

In past analyses K was about 0.01 .. 0.1. With this a heuristic for choosing alpha_meas can be formed:

alpha_meas = K / median(eig(C_meas))

Parameters:

• C_meas – diagonal values of C_meas matrix

• K – relative scale of C and R regularization matrices

class cedalion.dot.image_recon.SpatialBasisFunctions

Bases: ABC

Base for SBF implementations.

abstract property H: DataArray

The sensitivity in kernel space.

abstractmethod kernel_to_image_space_conc(

conc_img: DataArray,

) → DataArray

Transform an image from kernel to image space in recon. mode ‘conc’.

abstractmethod kernel_to_image_space_mua(

mua_img: DataArray,

) → DataArray

Transform an image from kernel to image space in recon. mode ‘mua’.

abstractmethod to_file(fname: Path | str)

Serialize prepared spatial basis functions into a file.

Parameters:

fname – path of the output file.

abstractmethod classmethod from_file(

fname: Path | str,

) → SpatialBasisFunctions

Load prepared spatial basis functions from a file.

Parameters:

fname – path of the file to read from.

Returns:

Loaded spatial basis functions instance.

Return type:

SpatialBasisFunctions

class cedalion.dot.image_recon.OriginalGaussianSpatialBasisFunctions(

head_model: TwoSurfaceHeadModel,

Adot: DataArray,

threshold_brain: Annotated[Quantity, '[length]'],

threshold_scalp: Annotated[Quantity, '[length]'],

sigma_brain: Annotated[Quantity, '[length]'],

sigma_scalp: Annotated[Quantity, '[length]'],

mask_threshold: float,

)

Bases: object

kernel_to_image_space_mua(

X: ndarray,

) → ndarray

Convert kernel space reconstructions to image space for mua.

Parameters:

X – Reconstruction values in kernel space. shape (kernel, …)

Returns:

Reconstruction values in image space.

Return type:

np.ndarray

kernel_to_image_space_conc(X) → ndarray

Convert kernel space reconstructions to image space for concentration.

Parameters:

X – Reconstruction values in kernel space.

Returns:

Reconstruction values in image space with HbO/HbR split.

Return type:

np.ndarray

to_file(fname: Path | str)

Serialize prepared Gaussian spatial basis functions to HDF5 file.

Parameters:

fname – path of the output file.

classmethod from_file(

fname: Path | str,

) → OriginalGaussianSpatialBasisFunctions

Load prepared Gaussian spatial basis functions from HDF5 group.

Parameters:

fname – path of the file to read from.

Returns:

Loaded instance.

Return type:

GaussianSpatialBasisFunctions

class cedalion.dot.image_recon.GaussianSpatialBasisFunctions(

head_model: TwoSurfaceHeadModel,

Adot: DataArray,

threshold_brain: Annotated[Quantity, '[length]'],

threshold_scalp: Annotated[Quantity, '[length]'],

sigma_brain: Annotated[Quantity, '[length]'],

sigma_scalp: Annotated[Quantity, '[length]'],

mask_threshold: float,

verbose: bool = True,

)

Bases: SpatialBasisFunctions

Gaussian Spatial Basis Functions.

Parameters:

• head_model – a TwoSurfaceHeadModel with brain and scalp surfaces

• Adot – the sensitivity matrix

• threshold_brain – the distance between kernel centers on the brain

• threshold_scalp – the distance between kernel centers on scalp

• sigma_brain – the width of the gaussians on the brain

• sigma_scalp – the width of the gaussians on the scalp

• mask_threshold – log10(sensitivity) threshold for vertices to be considered

• verbose – controls visibility of status messages and progress bar

property H

The sensitivity in kernel space.

kernel_to_image_space_mua(

X: ndarray,

) → ndarray

Convert kernel space reconstructions to image space for mua.

Parameters:

X – Reconstruction values in kernel space. shape (kernel, …)

Returns:

Reconstruction values in image space.

Return type:

np.ndarray

kernel_to_image_space_conc(X) → ndarray

Convert kernel space reconstructions to image space for concentration.

Parameters:

X – Reconstruction values in kernel space.

Returns:

Reconstruction values in image space with HbO/HbR split.

Return type:

np.ndarray

to_file(fname: Path | str)

Serialize prepared Gaussian spatial basis functions to HDF5 file.

Parameters:

fname – path of the output file.

classmethod from_file(

fname: Path | str,

) → GaussianSpatialBasisFunctions

Load prepared Gaussian spatial basis functions from HDF5 group.

Parameters:

fname – path of the file to read from.

Returns:

Loaded instance.

Return type:

GaussianSpatialBasisFunctions

class cedalion.dot.image_recon.ImageRecon(

Adot,

*,

alpha_meas: float = 0.001,

alpha_spatial: float | None = None,

lambda_R_conc: float | None = None,

apply_c_meas: bool = False,

recon_mode: Literal['conc', 'mua', 'mua2conc'] = 'mua',

brain_only: bool = False,

spatial_basis_functions: SpatialBasisFunctions | None = None,

)

Bases: object

Implements image reconstruction methods for diffuse optical tomography.

Parameters:

• Adot – the sensitivity matrix

• recon_mode –

  select reconstruction method

  • ’conc’: directly reconstruct hemoglobin concentrations from OD

    measurements at different wavelengths

  • ’mua’: reconstruct absorption changes from OD measurements for each

    wavelength separately.

  • ’mua2conc’: reconstruct absorption changes for each wavelength separately.

    Afterwards transform these to hemoglobin concentration changes.

• brain_only – if set to true, scalp vertices in Adot are ignored and the reconstruction is constrained to brain vertices

• alpha_meas – regularization parameter to adjust the balance between image noise and spatial resolution.

• alpha_spatial – regularization parameter that controls the effective depth of the reconstruction by controlling how strongly the vertex sensitivities are rescaled. A smaller alpha_spatial will more strongly suppress activation that is reconstructed on the scalp.

• lambda_R_conc – regularization parameter that sets the expected magnitude of the image covariance.

• apply_c_meas – controls whether the provided measurement covariance should be used for measurement regularization.

• spatial_basis_functions – if given reconstruct in the kernel space defined by the provided spatial-basis-function implementation. The result is returned in image space.

reconstruct(

y: Annotated[DataArray, DataArraySchema(dims='time', coords='time', 'time', 'samples')],

c_meas: DataArray | None = None,

) → Annotated[DataArray, DataArraySchema(dims='time', coords='time', 'time', 'samples')]

Reconstruct images from measurement data.

Parameters:

• y – optical density time series or time point data.

• c_meas – Diagonal elements of the measurement covariance matrix (optional). dims: wavelength x channel.

Returns:

Reconstructed images.

get_image_noise(c_meas: DataArray)

Compute image noise/variance estimates.

Parameters:

c_meas – Measurement covariance matrix.

Returns:

Image noise estimates.

Return type:

xr.DataArray

get_image_noise_posterior(

c_meas: DataArray | None = None,

)

Compute posterior variance of reconstructed images.

Calculates the diagonal of the posterior covariance matrix: Cov(X|y) = R - R * A^T @ (F + λ*C)^(-1) @ A * R where R is the spatial prior. Returns only the diagonal (variance at each vertex).

Parameters:

c_meas – Measurement covariance matrix.

Returns:

Posterior variance of reconstructed images.

Return type:

xr.DataArray

compute_lambda_R_indirect()

Compute wavelength-specific prior scaling parameter for indirect recon.

Scales lambda_R to ensure consistency between direct (chromophore space) and indirect (wavelength space) methods. Uses extinction coefficients to relate chromophore regularization strength to OD regularization.

Returns:

xr.DataArray Wavelength-specific parameter with dimension (wavelength,). Scaled to match direct method’s effective regularization strength.

Return type:

lambda_R_indirect