cedalion.io.forward_model

Module for saving and loading forward model computation results.

Functions

load_Adot(fn)	Load Adot from a netCDF file.
load_fluence(fn)	Load forward model computation results.
save_Adot(fn, Adot)	Save Adot to a netCDF file.
save_fluence(fn, fluence_all, fluence_at_optodes)	Save forward model computation results (deprecated).

Classes

FluenceFile(fname[, mode])

Context-manager for reading and writing fluence HDF5 files.

cedalion.io.forward_model.save_Adot(fn: str, Adot: DataArray)

Save Adot to a netCDF file.

Parameters:

• fn (str) – File name to save the data to.

• Adot (xr.DataArray) – Data to save.

Returns:

None

cedalion.io.forward_model.load_Adot(fn: str)

Load Adot from a netCDF file.

Parameters:

fn (str) – File name to load the data from.

Returns:

Data loaded from the file.

Return type:

xr.DataArray

cedalion.io.forward_model.save_fluence(fn: str, fluence_all, fluence_at_optodes)

Save forward model computation results (deprecated).

Deprecated since version Use: FluenceFile instead. This function uses a lossy compression algorithm to reduce file size.

Parameters:

• fn – Path to the output HDF5 file.

• fluence_all – Full volumetric fluence DataArray (dims: label, wavelength, i, j, k).

• fluence_at_optodes – Optode-pair fluence DataArray (dims: optode1, optode2, wavelength).

cedalion.io.forward_model.load_fluence(fn: str)

Load forward model computation results.

Parameters:

fn (str) – File name to load the data from.

Returns:

Fluence data loaded from the file.

Return type:

Tuple[xr.DataArray, xr.DataArray]

class cedalion.io.forward_model.FluenceFile(fname: str | Path, mode='r')

Bases: object

Context-manager for reading and writing fluence HDF5 files.

Fluence files store the output of Monte Carlo photon simulations:

• fluence_all: the full volumetric fluence for each optode and wavelength, shape (n_optodes, n_wavelengths, i, j, k), stored with LZF compression.

• fluence_at_optodes: the fluence sampled at all optode positions, shape (n_optodes, n_optodes, n_wavelengths).

Use as a context manager to ensure the underlying HDF5 file is flushed and closed even if an exception occurs:

with FluenceFile("fluence.h5", mode="w") as ff:
    ff.create_fluence_dataset(optodes, wavelengths, shape, units)
    ...

file

The underlying open h5py.File object.

optode_labels

List of optode label strings (populated on read/create).

wavelengths

List of wavelength floats (populated on read/create).

create_fluence_dataset(

optode_pos: Annotated[DataArray, DataArraySchema(dims='label', coords='label', 'label', 'type')],

wavelengths: ndarray,

fluence_shape: tuple[int, int, int],

units: str,

)

Create and initialise the fluence_all dataset in the HDF5 file.

Must be called once after opening in write mode, before any calls to set_fluence_by_label() or set_fluence_by_index().

Parameters:

• optode_pos – Labeled optode positions; labels and types are stored as dataset attributes.

• wavelengths – Array of wavelength values (nm).

• fluence_shape – Voxel grid shape (ni, nj, nk) for the fluence volume.

• units – Physical units string for the fluence values (e.g. "mm^-2").

get_fluence(label: str, wavelength: float) → ndarray

Return the volumetric fluence for one optode and wavelength.

Parameters:

• label – Optode label string.

• wavelength – Wavelength value (must match one stored in the file).

Returns:

NumPy array of shape (ni, nj, nk).

set_fluence_by_label(label: str, wavelength: float, fluence: ndarray)

Write the volumetric fluence for one optode and wavelength (by label).

Parameters:

• label – Optode label string.

• wavelength – Wavelength value.

• fluence – Array of shape (ni, nj, nk) to store.

set_fluence_by_index(i_label: int, i_wl: int, fluence: ndarray)

Write the volumetric fluence for one optode and wavelength (by index).

Parameters:

• i_label – Zero-based optode index.

• i_wl – Zero-based wavelength index.

• fluence – Array of shape (ni, nj, nk) to store.

get_fluence_at_optodes()

Return the optode-pair fluence as an xr.DataArray.

Returns:

xr.DataArray with dims (optode1, optode2, wavelength).

set_fluence_at_optodes(fluence_at_optodes: DataArray)

Store the optode-pair fluence dataset.

Parameters:

fluence_at_optodes – DataArray with dims (optode1, optode2, wavelength) containing the fluence sampled at each optode position.

get_fluence_all()

Return the full volumetric fluence as an xr.DataArray.

Returns:

xr.DataArray with dims (label, wavelength, i, j, k) and label, type, and wavelength coordinates.