ID01Loader#

class cdiutils.io.ID01Loader(experiment_file_path, scan=None, sample_name=None, detector_name=None, flat_field=None, alien_mask=None, **kwargs)[source]#

Bases: H5TypeLoader

Data loader for ESRF ID01 beamline (BLISS acquisition).

Handles HDF5 master files produced by BLISS control software at ID01, supporting Maxipix and Eiger2M detectors. Provides detector calibration, motor angles, and beam energy from scan metadata.

This loader is for modern BLISS-based experiments. For legacy SPEC format data (pre-2020), use SpecLoader instead.

angle_names#

Mapping from canonical names to ID01 motor names:

  • sample_outofplane_angle -> "eta"

  • sample_inplane_angle -> "phi"

  • detector_outofplane_angle -> "delta"

  • detector_inplane_angle -> "nu"

authorised_detector_names#

Tuple of supported detectors: ("mpxgaas", "mpx1x4", "eiger2M").

Examples

Basic usage with factory pattern:

>>> from cdiutils.io import Loader
>>> loader = Loader.from_setup(
...     beamline_setup="id01",
...     scan=42,
...     sample_name="PtNP",
...     experiment_file_path="/data/id01/sample.h5"
... )

Direct instantiation:

>>> from cdiutils.io.id01 import ID01Loader
>>> loader = ID01Loader(
...     experiment_file_path="/data/id01/sample.h5",
...     scan=42,
...     sample_name="PtNP",
...     detector_name="eiger2M"
... )

Load data with preprocessing:

>>> data, angles = loader.load_data(
...     roi=(100, 400, 150, 450),
...     rocking_angle_binning=2
... )

See also

SpecLoader for legacy SPEC format data. Loader for factory method and base class documentation.

The ID01Loader class handles data loading from the ESRF ID01 beamline. It is typically used internally by BcdiPipeline.

See Loader for inherited methods.

angle_names = {'detector_inplane_angle': 'nu', 'detector_outofplane_angle': 'delta', 'sample_inplane_angle': 'phi', 'sample_outofplane_angle': 'eta'}#
authorised_detector_names = ('mpxgaas', 'mpx1x4', 'eiger2M')#
__init__(experiment_file_path, scan=None, sample_name=None, detector_name=None, flat_field=None, alien_mask=None, **kwargs)[source]#

Initialise ID01 data loader with experiment file and metadata.

Parameters:

  • experiment_file_path (str) – Path to BLISS HDF5 master file (typically sample_name.h5). File must contain scan groups in format {sample}_{scan}.1/.

  • scan (int) – Scan number to load. If None, must be specified in subsequent load_data() calls.

  • sample_name (str) – Sample identifier matching HDF5 group names. Required to construct scan paths.

  • detector_name (str) – Detector identifier ("mpxgaas", "mpx1x4", or "eiger2M"). If None, automatically detected from first available scan.

  • flat_field (ndarray | str) – Flat-field correction array or path to .npy/.npz file. Shape must match detector’s 2D frame. Applied multiplicatively to raw data.

  • alien_mask (ndarray | str) – Bad pixel mask array or path. Binary mask with 1 = bad pixel, 0 = good pixel. Combined with detector’s chip gap mask.

  • **kwargs – Additional parameters (currently unused, reserved for future extensions).

Raises:

  • FileNotFoundError – If experiment_file_path does not exist.

  • ValueError – If detector_name is not in authorised_detector_names.

  • KeyError – If scan or sample_name do not match HDF5 structure.

Examples

Minimal setup (auto-detect detector):

>>> loader = ID01Loader(
...     experiment_file_path="/data/id01/PtNP.h5",
...     scan=42,
...     sample_name="PtNP"
... )

With flat-field and detector specification:

>>> loader = ID01Loader(
...     experiment_file_path="/data/id01/sample.h5",
...     scan=100,
...     sample_name="sample",
...     detector_name="eiger2M",
...     flat_field="/path/to/flatfield.npy"
... )
get_detector_name(*args, **kwargs)#

Get canonical detector identifier for this beamline.

Returns the first name from authorised_detector_names, which is the standard identifier for detector geometry calculations.

Returns:

Detector name string (e.g., "Eiger2M", "Maxipix", "Lambda750k").

load_det_calib_params(*args, **kwargs)#

Load detector calibration parameters from experiment file.

Must be implemented by beamline-specific subclass. Typically reads values stored during detector alignment procedure.

Returns:

Calibration parameters with keys:

  • "direct_beam": (y, x) pixel coordinates of direct beam position

  • "detector_distance": sample-to-detector distance in metres

  • "outofplane_angle": detector rotation delta or gamma in degrees

  • "inplane_angle": detector rotation nu in degrees

Return type:

dict

See also

Detector Geometry Calibration for calibration procedures and parameter definitions.

load_detector_shape(*args, **kwargs)#

Load detector’s native pixel array shape.

Must be implemented by beamline-specific subclass if detector shape cannot be determined from data files.

Returns:

Detector shape as (n_rows, n_columns) tuple, or None if shape is determined from data.

load_detector_data(*args, **kwargs)#
load_motor_positions(*args, **kwargs)#
load_energy(*args, **kwargs)#

Load X-ray beam energy for the scan.

Must be implemented by beamline-specific subclass.

Returns:

Beam energy in keV.

show_scan_attributes(*args, **kwargs)#
load_measurement_parameters(*args, **kwargs)#
load_instrument_parameters(*args, **kwargs)#
load_sample_parameters(*args, **kwargs)#
load_plotselect_parameter(*args, **kwargs)#
get_start_time(*args, **kwargs)#

Examples#

The loader is used automatically by BcdiPipeline:

from cdiutils.pipeline import BcdiPipeline

# Configure pipeline for ID01 in YAML file:
# beamline: "ID01"
# sample_name: "S123"
# scan: 42
# data_dir: "/data/id01/inhouse/sample123"

pipeline = BcdiPipeline(param_file_path="config.yml")
pipeline.preprocess()  # automatically uses ID01Loader

See Also#

Loader : Base loader class BcdiPipeline : Uses loaders to load data