CHAP.common.models package

This subpackage contains Pydantic model configuration classes for PipelineItems that are common to various processing workflows.

common: Common Pydantic model configuration classes.
integration:: pyFAI integration related Pydantic model configuration classes.
map: Map related Pydantic model configuration classes.

Submodules

CHAP.common.models.common module

Common Pydantic model configuration classes.

class BinarizeConfig[source]

Bases: CHAPBaseModel

Configuration class to binarize a dataset in a 2D or 3D array-like object or a NeXus style NXdata or NXfield object.

Variables:

method (Literal[ 'CHAP', 'isodata', 'minimum', 'otsu', 'yen']) – Binarization method, defaults to ‘CHAP’ (CHAP’s internal implementation of Otzu’s method).
num_bin (int, optional) – The number of bins used to calculate the histogram in the binarization algorithms, defaults to 256.
nxpath (str, optional) – The path to a specific NeXus style NXdata or NXfield object in the NeXus file tree to read the input data from (ignored for non-NeXus input objects).
remove_original_data (bool, optional) – Removes the original data field (ignored for non-NeXus input objects), defaults to False.

method: Literal['CHAP', 'isodata', 'minimum', 'otsu', 'yen'] | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

num_bin: Annotated[int, None, Interval(gt=None, ge=0, lt=None, le=None), None] | None

nxpath: str | None

remove_original_data: bool | None

class ImageProcessorConfig[source]

Bases: CHAPBaseModel

Class representing the configuration of various image selection and visualization types of processors.

Variables:

animation (bool, optional) – Create an animation for an image stack (ignored for a single image), defaults to False.
axis (int or str, optional) – Axis direction or name for the image slice(s), defaults to 0.
basename (str, optional) – Basename of each file when saving a set of ‘tif’ images (only used when ‘fileformat’ = ‘fit’), defaults to ‘image’.
coord_range (float or list[float], optional) – Coordinate value range of the selected image slice(s), up to three floating point numbers (start, end, step), defaults to None, which enables index_range to select the image slice(s). Include only coord_range or index_range, not both.
index_range (int or list[int], optional) – Array index range of the selected image slice(s), up to three integers (start, end, step). Set index_range to -1 to select the center image slice of an image stack in the axis direction. Only used when coord_range = None. Defaults to None, which will include all slices.
fileformat (Literal[ 'gif', 'jpeg', 'png', 'tif' 'tifstack'], optional) – Image (stack) return file type, defaults to ‘png’ for a single image, ‘tif’ for a (set of) ‘tif’ image(s), or ‘gif’ for an animation. Set to ‘tifstack’ for a single ‘tif’ image stack.
vrange (list[float, float]) – Data value range in image slice(s), defaults to None, which uses the full data value range in the slice(s). Specify as [None, float] or [float, None] to set only the upper or lower limit of the value range.

animation: bool | None

axis: Annotated[int, None, Interval(gt=None, ge=0, lt=None, le=None), None] | Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)] | None

basename: Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)] | None

coord_range: Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, AllowInfNan(allow_inf_nan=False)] | Annotated[list[Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, AllowInfNan(allow_inf_nan=False)]], Len(min_length=2, max_length=3)] | None

fileformat: Literal['gif', 'jpeg', 'png', 'tif', 'tifstack'] | None

index_range: int | Annotated[list[None | int], Len(min_length=2, max_length=3)] | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod validate_index_range(index_range)[source]

Validate the index_range.

Variables:: index_range – Array index range of the selected image slice(s), defaults to None.
Returns:: Validated index_range.
Return type:: list[int]

classmethod validate_vrange(vrange, info)[source]

Validate the vrange.

Variables:: vrange – Data value range in image slice(s), defaults to None.
Returns:: Validated vrange.
Return type:: list[float, float]

vrange: Annotated[list[None | Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, AllowInfNan(allow_inf_nan=False)]], Len(min_length=2, max_length=2)] | None

class UnstructuredToStructuredConfig[source]

Bases: CHAPBaseModel

Configuration class to reshape data in an NXdata from an “unstructured” to a “structured” representation.

Variables:

nxpath (str, optional) – Path to a specific NeXus style NXdata object in the NeXus file tree to read the input data from.
signals (str or list[str], optional) – Paths to the dataset’s signal-like fields to reshape (in addition to possible ones in the optional nxpath object).
unstructured_axes (str or list[str], optional) – Names of the dataset’s unstructured axes fields. Defaults to the ‘unstructured axis’ attribute of the default NeXus style NXdata object or that specified in nxpath if present. If nxpath is unspecified and there is no default NeXus style NXdata object, the unstructured_axes is required and has to contain full paths to the unstructured axes fields.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

nxpath: str | None

signals: str | Annotated[list[str], Len(min_length=1, max_length=None)] | None

unstructured_axes: str | Annotated[list[str], Len(min_length=1, max_length=None)] | None

classmethod validate_nxpath(nxpath)[source]

Validate nxpath.

Parameters:: nxpath (str) – Path to a specific NeXus style NXdata object in the NeXus file tree to read the input data from.
Returns:: Validated nxpath.
Return type:: str

classmethod validate_signals(signals)[source]

Validate signals.

Parameters:: signals (str or list[str]) – The (additional) dataset’s signal-like fields.
Returns:: Validated signals.
Return type:: list[str]

classmethod validate_unstructured_axes(unstructured_axes)[source]

Validate unstructured_axes.

Parameters:: unstructured_axes (str or list[str]) – The dataset’s unstructured axes.
Returns:: Validated unstructured axes.
Return type:: list[str]

CHAP.common.models.integration module

pyFAI integration related Pydantic model configuration classes.

class AzimuthalIntegratorConfig[source]

Bases: Detector, CHAPBaseModel

Azimuthal integrator configuration class to represent a single detector used in the experiment.

Variables:

mask_file (FilePath, optional) – Path to the mask file.
poni_file (FilePath, optional) – Path to the PONI file, specify either poni_file or params, not both.
params (dict, optional) – Azimuthal integrator configuration parameters, specify either poni_file or params, not both.

property ai

Return the azimuthal integrator.

Type:: AzimuthalIntegrator

property mask_data

Return the mask array to use for this detector from the data in the file specified with the mask_file field. Return None if mask_file is None.

Type:: numpy.ndarray

mask_file: Annotated[Path, PathType(path_type=file)] | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

params: dict | None

poni_file: Annotated[Path, PathType(path_type=file)] | None

validate_ai()[source]

Set the default azimuthal integrator.

Returns:: Validated configuration class.
Return type:: AzimuthalIntegratorConfig

classmethod validate_root(data)[source]

Make sure data contains either poni_file _or_ params, not both, and that the field that is used defines a valid pyFAI.azimuthalIntegrator.AzimuthalIntegrator object.

Parameters:: data (dict) – Pydantic validator data object.
Returns:: Currently validated class attributes.
Return type:: dict

class Integrate1dConfig[source]

Bases: _IntegrateConfig

Class with the input parameters to perform 1D azimuthal integration with pyFAI.

Variables:

method (str or tuple, optional) – For pyFAI.azimuthalIntegrator.AzimuthalIntegrator a registered integration method or a 3-tuple (splitting, algorithm, implementation), defaults to csr. For pyFAI.multi_geometry.MultiGeometry a registered integration method, defaults to splitpixel.
npt (int, optional) – Number of integration points, defaults to 1800.

method: str | Annotated[list[Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)]], Len(min_length=3, max_length=3)] | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

npt: Annotated[int, None, Interval(gt=0, ge=None, lt=None, le=None), None] | None

class Integrate2dConfig[source]

Bases: _IntegrateConfig

Class with the input parameters to perform 2D azimuthal (cake) integration with pyFAI.

Variables:

method (str, optional) – Registered integration method, defaults to bbox for pyFAI.azimuthalIntegrator.AzimuthalIntegrator or splitpixel for pyFAI.multi_geometry.MultiGeometry.
npt_azim (int, optional) – Number of points for the integration in the azimuthal direction, defaults to 3600.
npt_rad (int, optional) – Number of points for the integration in the radial direction, defaults to 1800.

method: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

npt_azim: Annotated[int, None, Interval(gt=0, ge=None, lt=None, le=None), None] | None

npt_rad: Annotated[int, None, Interval(gt=0, ge=None, lt=None, le=None), None] | None

class IntegrateRadialConfig[source]

Bases: _IntegrateConfig, MultiGeometryConfig

Class with the input parameters to perform radial integration with pyFAI.

Variables:

method (str, optional) – Registered integration method, defaults to csr.
radial_unit (str, optional) – Unit used for radial representation, defaults to ‘q_A^-1’.
npt (int, optional) – Number of integration points, defaults to 1800.

method: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

npt: Annotated[int, None, Interval(gt=0, ge=None, lt=None, le=None), None] | None

radial_unit: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)] | None

class MultiGeometryConfig[source]

Bases: CHAPBaseModel

Class representing the configuration for treating simultaneously multiple detector configuration within a single integration

Variables:

ais (str or list[str]) – List of detector IDs of azimuthal integrators.
azimuth_range (list[float, float] or tuple[float, float], optional) – Common azimuthal range for integration, defaults to [-180.0, 180.0].
radial_range (list[float, float] or tuple[float, float], optional) – Common range for integration, defaults to [0.0, 180.0].
unit (str, optional) – Output unit, defaults to ‘q_A^-1’.
chi_disc (int, optional) – chi discontinuity value, defaults to 180.
empty (float, optional) – Value for empty pixels, defaults to 0.
wavelength (float, optional) – Wave length used in meters.

ais: Annotated[list[Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)]], Len(min_length=1, max_length=None)]

azimuth_range: Annotated[list[Annotated[float, None, Interval(gt=None, ge=-180, lt=None, le=360), None, AllowInfNan(allow_inf_nan=False)]], Len(min_length=2, max_length=2)] | None

chi_disc: int | None

empty: Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, AllowInfNan(allow_inf_nan=False)] | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

radial_range: Annotated[list[Annotated[float, None, Interval(gt=None, ge=0, lt=None, le=180), None, AllowInfNan(allow_inf_nan=False)]], Len(min_length=2, max_length=2)] | None

unit: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)] | None

classmethod validate_ais(ais)[source]

Validate the detector IDs of the azimuthal integrators.

Parameters:: ais (str, list[str]) – Detector IDs.
Returns:: Detector ais.
Return type:: list[str]

wavelength: Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, AllowInfNan(allow_inf_nan=False)] | None

class PyfaiIntegrationConfig[source]

Bases: CHAPBaseModel

Class defining components needed for performing one or more integrations on the same set of 2D input data with PyfaiIntegrationProcessor.

Variables:

azimuthal_integrators (list[AzimuthalIntegratorConfig]) – List of single-detector azimuthal integrator configurations.
integrations (list[PyfaiIntegratorConfig]) – Azimuthal integrator configurations.
sum_axes (bool, optional) – Sum the detector data over the independent coordinates before integration, defaults to False.

azimuthal_integrators: Annotated[list[AzimuthalIntegratorConfig], Len(min_length=1, max_length=None)] | None

integrations: Annotated[list[PyfaiIntegratorConfig], Len(min_length=1, max_length=None)]

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

sum_axes: bool | None

classmethod validate_config(data)[source]

Ensure that a valid configuration was provided and finalize PONI filepaths.

Parameters:: data (dict) – Pydantic validator data object.
Returns:: Currently validated class attributes.
Return type:: dict

zarr_tree(dataset_shape, dataset_chunks='auto')[source]

Return a dictionary representing a zarr.group that can be used to contain results from PyfaiIntegrationProcessor.

Returns:: A zarr.group that can be used to contain the integration results.
Return type:: dict

class PyfaiIntegratorConfig[source]

Bases: CHAPBaseModel

Class representing the configuration for detector data integrator for pyFAI.

Variables:

name (str) – Integration type name, e.g. cake, or wedge.
integration_method (Literal[ 'integrate1d', 'integrate2d', 'integrate_radial', 'integrate2d_grazing_incidence']) – Integration method.
multi_geometry (MultiGeometryConfig) – Multiple detector configuration.
integration_params (Integrate1dConfig or Integrate2dConfig or IntegrateRadialConfig) – Integration parameter configuration.
right_handed (bool, optional) – For radial and cake integration, reverse the direction of the azimuthal coordinate from pyFAI’s convention, defaults to True.

get_axes_indices(dataset_ndims)[source]

Return the index of each coordinate orienting a single frame of results from this integration.

Type:: dict

get_placeholder_data(ais)[source]

Return empty input data of the correct shape for use in init_placeholder_data.

Type:: dict

init_placeholder_results(ais)[source]: Get placeholder results for this integration so we can fill in the datasets for results of coordinates when setting up a zarr tree for holding results of PyfaiIntegrationProcessor.

integrate(azimuthal_integrators, data)[source]

Perform the integration and return the results.

Parameters:

azimuthal_integrators (list[AzimuthalIntegratorConfig]) – List of single-detector azimuthal integrator configurations.
data (dict[str, np.ndarray]) – Dictionary of 2D detector frames to be integrated.

Returns:

Integrated intensities and coordinates for every frame (or set of frames) in data.

Return type:

dict[str, object]

integration_method: Literal['integrate1d', 'integrate2d', 'integrate_radial']

integration_params: Integrate1dConfig | Integrate2dConfig | IntegrateRadialConfig | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

multi_geometry: MultiGeometryConfig | None

name: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)]

property result_coords

Return a dictionary representing the zarr.array objects for the coordinates of a single frame of results from this integration.

Type:: dict

property result_shape

Return shape of one frame of results from this integration.

Type:: tuple

right_handed: bool

classmethod validate_config(data)[source]

Validate the input integration configuration.

Parameters:: data (dict) – Pydantic validator data object.
Returns:: Currently validated class attributes.
Return type:: dict

zarr_tree(dataset_shape, dataset_chunks='auto')[source]

Return a dictionary representing a zarr.group that can be used to contain results from this integration.

Returns:: A zarr.group that can be used to contain the integration results.
Return type:: dict

CHAP.common.models.map module

Map related Pydantic model configuration classes.

class CHAPSlice[source]

Bases: CHAPBaseModel

Class representing a slice configuration for any particular dimension of a data set.

Variables:

start (int, optional) – Starting index for slicing, defaults to 0.
end (int, optional) – Ending index for slicing.
step (int, optional) – Slicing step, defaults to 1.

end: int | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

start: int | None

step: Annotated[int, None, Interval(gt=0, ge=None, lt=None, le=None), None] | None

tolist()[source]

Return the slice configuration as a list.

Returns:: Slice configuration.
Return type:: list

toslice()[source]

Return the slice configuration as a slice object.

Returns:: Slice configuration.
Return type:: slice

class CorrectionsData[source]

Bases: PointByPointScanData

Class representing the special instances of PointByPointScanData that are used by certain kinds of Correction tools.

Variables:

label (Literal['dwell_time_actual', 'postsample_intensity', 'presample_intensity']) – One of the reserved values required by the Correction tool configurations.
data_type (Literal['scan_column', 'smb_par']) – Represents how these data were recorded at time of data collection.

data_type: Literal['scan_column', 'smb_par']

label: Literal['dwell_time_actual', 'postsample_intensity', 'presample_intensity']

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod reserved_labels()[source]

Return a list of all the labels reserved for corrections-related scalar data.

Returns:: Reserved labels.
Return type:: list[str]

class Detector[source]

Bases: CHAPBaseModel

Class representing a single detector.

Variables:

id (str) – Detector ID (e.g. name or channel index).
shape (tuple[int,int], optional) – Detector’s raw data shape.
attrs (dict, optional) – Additional detector configuration attributes.

attrs: dict | None

get_id()[source]

Return the detector ID

Type:: str

id_: Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)]

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

shape: tuple[int, int] | None

validate_detector_after()[source]

Validate any additional detector configuration attributes.

Raises:: ValueError – Invalid attribute.
Returns:: The validated detector class properties.
Return type:: Detector

classmethod validate_id(id_)[source]

Validate the detector ID.

Parameters:: id (int, str) – Detector ID (e.g. name or channel index).
Returns:: Validated detector ID.
Return type:: str

class DetectorConfig(*, detectors: Annotated[list[Detector], Len(min_length=0, max_length=None)], roi: Annotated[list[CHAPSlice], Len(min_length=2, max_length=2)] | None = None)[source]

Bases: CHAPBaseModel

Class representing a detector configuration.

Variables:

detectors (list[Detector]) – Detector list.
roi (list[CHAPSlice, CHAPSlice], optional) – Detector ROI.

detectors: Annotated[list[Detector], Len(min_length=0, max_length=None)]

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

roi: Annotated[list[CHAPSlice], Len(min_length=2, max_length=2)] | None

roitoslice()[source]

Return the Detector ROI as a slice object.

Returns:: Slice configuration.
Return type:: [slice, slice]

tolist()[source]

Return the Detector ROI as a list.

Returns:: Slice configuration.
Return type:: [list, list]

classmethod validate_roi(roi)[source]

Validate the detector ROI.

Parameters:: roi (list[CHAPSlice, CHAPSlice]) – Detector ROI.
Returns:: Validated detector ROI
Return type:: list[CHAPSlice, CHAPSlice]

class DwellTimeActual[source]

Bases: CorrectionsData

Class representing a source of raw data for the actual dwell time at each scan point in SPEC (with some scan types, this value can vary slightly point-to-point from the dwell time specified in the command).

Variables:

label (Literal['dwell_time_actual']) – Must be ‘dwell_time_actual’.
units (Literal['s']) – Must be ‘s’.

label: Literal['dwell_time_actual']

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

units: Literal['s']

class IndependentDimension[source]

Bases: PointByPointScanData

Class representing the source of data to identify the coordinate values along one dimension of a MapConfig.

Variables:

start (int, optional) – Starting index for slicing all datasets of a MapConfig along this axis, defaults to 0.
end (int, optional) – Ending index for slicing all datasets of a MapConfig along this axis, defaults to the total number of unique values along this axis in the associated MapConfig.
step (int, optional) – Step for slicing all datasets of a MapConfig along this axis, defaults to 1.

end: int | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

start: Annotated[int, None, Interval(gt=None, ge=0, lt=None, le=None), None] | None

step: Annotated[int, None, Interval(gt=0, ge=None, lt=None, le=None), None] | None

class MapConfig[source]

Bases: CHAPBaseModel

Class representing an experiment consisting of one or more SPEC scans.

Variables:

did (str, optional) – FOXDEN data identifier.
title (str) – Map configuration title.
station (Literal['id1a3', 'id3a', 'id3b', 'id4b']) – Name of the station at which the data was collected.
experiment_type (Literal[ 'EDD', 'GIWAXS', 'HDRM', 'SAXSWAXS', 'TOMO', 'XRF']) – Experiment type.
sample (CHAP.commom.models.map.Sample) – Sample metadata configuration.
spec_scans (list[SpecScans]) – SPEC scans that compose the map.
scalar_data (list[PointByPointScanData], optional) – All sources of data representing other scalar raw data values collected at each point on the map. In the NeXus file representation of the map, datasets for these values will be included, defaults to [].
independent_dimensions (list[PointByPointScanData]) – Data sources representing the raw values of each independent dimension of the map.
presample_intensity (PresampleIntensity, optional) – Source of point-by-point presample beam intensity data. Required when applying certain kinds of Correction tools.
dwell_time_actual (DwellTimeActual, optional) – Source of point-by-point actual dwell times for SPEC scans. Required when applying certain kinds of Correction tools.
postsample_intensity (PresampleIntensity, optional) – Source of point-by-point postsample beam intensity data. Required when applying certain kinds of Correction tools.
attrs (dict, optional) – Additional map configuration configuration attributes.

property all_scalar_data

Return a list of all instances of PointByPointScanData for which this map configuration will collect dataset-like data (as opposed to axes-like data).

This will be any and all of the items in the corrections-data-related fields, as well as any additional items in the optional scalar_data field.

Type:: list

attrs: dict

property coords

Return a dictionary of the values of each independent dimension across the map.

Type:: list

did: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=None, ascii_only=None)] | None

property dims

Return a list of the independent dimension labels for the map.

Type:: list

dwell_time_actual: DwellTimeActual | None

experiment_type: Literal['EDD', 'GIWAXS', 'HDRM', 'SAXSWAXS', 'TOMO', 'XRF']

get_coords(map_index)[source]

Return a dictionary of the coordinate names and values of each independent dimension for a given point on the map.

Parameters:: map_index (tuple) – Map index to return coordinates for.
Returns:: Coordinate values.
Return type:: dict

get_detector_data(detector_name, map_index)[source]

Return detector data collected by this map for a given point on the map.

Parameters:

detector_name (str) – Name of the detector for which to return data. Usually the value of the detector’s EPICS areaDetector prefix macro, $P.
map_index (tuple) – Map index to return detector data for.

Returns:

One frame of raw detector data.

Return type:

np.ndarray

get_scan_step_index(map_index)[source]

Return parameters to identify a single SPEC scan step that corresponds to the map point at the index provided.

Parameters:: map_index (tuple) – Map point index to identify as a specific SPEC scan step index.
Returns:: SpecScans configuration, scan number, and scan step index.
Return type:: tuple[SpecScans, int, int]

static get_smb_par_attr(class_fields, label, units='-', name=None, unique=True)[source]

Read a SMB-style par file attribute.

Parameters:

class_fields (Any) – Map configuration class fields.
label (str) – Attribute’s field key, the user-defined label for referring to this data in the NeXus file and in other tools.
units (str) – Attribute’s field unit, defaults to ‘-’.
name (str, optional.) – Attribute’s field name, the name with which these raw data were recorded at time of data collection, defaults to label.

get_value(data, map_index)[source]

Return the raw data collected by a single device at a single point in the map.

Parameters:

data (PointByPointScanData) – Device configuration to return a value of raw data for.
map_index (tuple) – Map index to return raw data for.

Returns:

Raw data value.

Return type:

float

independent_dimensions: Annotated[list[IndependentDimension], Len(min_length=1, max_length=None)]

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

postsample_intensity: PostsampleIntensity | None

presample_intensity: PresampleIntensity | None

sample: Sample

scalar_data: Annotated[list[PointByPointScanData], Len(min_length=0, max_length=None)] | None

property scan_step_indices

Return an ordered list in which we can look up the SpecScans object, the scan number, and scan step index for every point on the map.

Type:: list

property shape

Return the shape of the map – a tuple representing the number of unique values of each dimension across the map.

Type:: tupple

spec_scans: Annotated[list[SpecScans], Len(min_length=1, max_length=None)]

station: Literal['id1a3', 'id3a', 'id3b', 'id4b']

title: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)]

classmethod validate_attrs(attrs, info)[source]

Validate any additional attributes depending on the values for the station and experiment_type fields.

Parameters:

attrs (dict) – Any additional attributes to the MapConfig
info (pydantic.ValidationInfo) – Model parameter validation information.

Raises:

ValueError – Invalid attribute.

Returns:

Validated attrs fields.

Return type:

dict

classmethod validate_before(data)[source]

Ensure that the attrs parameter is initialized.

Parameters:: data (dict) – Pydantic validator data object.
Returns:: Currently validated class attributes.
Return type:: dict

validate_data_present: bool

classmethod validate_experiment_type(experiment_type, info)[source]

Ensure values for the station and experiment_type fields are compatible.

Parameters:

experiment_type (Literal[ 'EDD', 'GIWAXS', 'HDRM', 'SAXSWAXS', 'TOMO', 'XRF']) – experiment_type value to validate.
info (pydantic.ValidationInfo) – Model parameter validation information.

Raises:

ValueError – Invalid experiment type.

Returns:

Validated experiment_type value.

Return type:

str

classmethod validate_mapconfig_before(data, info)[source]

Ensure that a valid configuration was provided and finalize spec_file filepaths.

Parameters:: data (dict) – Pydantic validator data object.
Returns:: Currently validated class attributes.
Return type:: dict

class PointByPointScanData[source]

Bases: CHAPBaseModel

Class representing a source of raw scalar-valued data for which a value was recorded at every point in a MapConfig.

Variables:

label (str) – User-defined label for referring to this data in the NeXus file and in other tools.
units (str) – Units in which the data were recorded.
data_type (Literal[ 'expression', 'detector_log_timestamps', 'scan_column', 'scan_start_time', 'scan_step_index', 'smb_par', 'spec_motor', 'spec_motor_absolute', 'spec_motor_static']) – Represents how these data were recorded at time of data collection.
name (str) – Represents the name with which these raw data were recorded at time of data collection.
ndigits (int, optional) – Round SPEC motor values to the specified number of decimals if set.

data_type: Literal['expression', 'detector_log_timestamps', 'scan_column', 'scan_start_time', 'scan_step_index', 'smb_par', 'spec_motor', 'spec_motor_absolute', 'spec_motor_static']

get_value(spec_scans, scan_number, scan_step_index=0, scalar_data=None, relative=True, static=False, ndigits=None)[source]

Return the value recorded for this instance of PointByPointScanData at a specific scan step.

Parameters:

spec_scans (SpecScans) – An instance of SpecScans in which the requested scan step occurs.
scan_number (int) – Number of the scan in which the requested scan step occurs.
scan_step_index (int, optional) – Index of the requested scan step, defaults to 0.
scalar_data (list[PointByPointScanData], optional) – Scalar data configurations used to get values for PointByPointScanData objects with data_type == ‘expression’.
relative (bool, optional) – Whether to return a relative value or not, defaults to True (only applies to SPEC motor values).
static (bool, optional) – Wether to return just a static motor postion even if the motor is scanned (in which case: return the first position of the motor in the scan), defaults to False.

Params ndigits:

Round SPEC motor values to the specified number of decimals if set.

Returns:

Value recorded of the data represented by this instance of PointByPointScanData at the scan step requested.

Return type:

float

label: Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)]

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)]

ndigits: Annotated[int, None, Interval(gt=None, ge=0, lt=None, le=None), None] | None

units: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)]

validate_for_scalar_data(scalar_data)[source]

Used for PointByPointScanData objects with a data_type of ‘expression’. Validate that the scalar_data field of ai MapConfig object contains all the items necessary for evaluating the expression.

Parameters:: scalar_data (list[PointByPointScanData]) – The scalar_data field of a MapConfig that this PointByPointScanData object will be validated against.
Raises:: ValueError – if scalar_data does not contain items needed for evaluating the expression.

validate_for_spec_scans(spec_scans, scan_step_index='all')[source]

Validate this instance of PointByPointScanData for a list of SpecScans.

Parameters:

spec_scans (list[SpecScans]) – List of SpecScans’s whose raw data will be checked for the presence of the data represented by this instance of PointByPointScanData.
scan_step_index (int or Literal['all'], optional) – Specific scan step index to validate, defaults to ‘all’.

Raises:

RuntimeError – If the data represented by this instance of PointByPointScanData is missing for the specified scan steps.

validate_for_station(station)[source]

Validate this instance of PointByPointScanData for a certain choice of station (beamline).

Parameters:

station (Literal['id1a3', 'id3a', 'id3b', 'id4b']) – Name of the station at which the data was collected.
experiment_type (Literal[ 'EDD', 'GIWAXS', 'HDRM', 'SAXSWAXS', 'TOMO', 'XRF']) – Experiment type.

Raises:

TypeError – If the station is not compatible with the value of the data_type attribute for this instance of PointByPointScanData.

classmethod validate_label(label)[source]

Validate that the supplied label does not conflict with any of the values for label reserved for certain data needed to perform corrections.

Parameters:: label (str) – Input value of label.
Raises:: ValueError – If label is one of the reserved values.
Returns:: Originally supplied value label.
Return type:: str

class PostsampleIntensity[source]

Bases: CorrectionsData

Class representing a source of raw data for the intensity of the beam that has passed through the sample.

Variables:

label (Literal['postsample_intensity']) – Must be ‘postsample_intensity’.
units (Literal['counts']) – Must be ‘counts’.

label: Literal['postsample_intensity']

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

units: Literal['counts']

class PresampleIntensity[source]

Bases: CorrectionsData

Class representing a source of raw data for the intensity of the beam that is incident on the sample.

Variables:

label (Literal['presample_intensity']) – Must be ‘presample_intensity”.
units (Literal['counts']) – Must be ‘counts’.

label: Literal['presample_intensity']

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

units: Literal['counts']

class Sample[source]

Bases: CHAPBaseModel

Class representing a sample metadata configuration.

Variables:

name (str) – Sample name.
description (str, optional) – Sample description.

description: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)]

class SpecConfig[source]

Bases: CHAPBaseModel

Class representing the raw data for one or more SPEC scans.

Variables:

station (Literal['id1a3', 'id3a', 'id3b', 'id4b']) – Name of the station at which the data was collected.
experiment_type (Literal[ 'EDD', 'GIWAXS', 'HDRM', 'SAXSWAXS', 'TOMO', 'XRF']) – Experiment type.
spec_scans (list[SpecScans]) – SPEC scans that compose the set.

experiment_type: Literal['EDD', 'GIWAXS', 'HDRM', 'SAXSWAXS', 'TOMO', 'XRF']

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

spec_scans: Annotated[list[SpecScans], Len(min_length=1, max_length=None)]

station: Literal['id1a3', 'id3a', 'id3b', 'id4b']

classmethod validate_experiment_type(experiment_type, info)[source]

Ensure values for the station and experiment_type fields are compatible.

Parameters:

experiment_type (Literal[ 'EDD', 'GIWAXS', 'HDRM', 'SAXSWAXS', 'TOMO', 'XRF']) – experiment_type value to validate.
info (pydantic.ValidationInfo) – Model parameter validation information.

Raises:

ValueError – Invalid experiment type.

Returns:

Validated experiment_type value.

Return type:

str

classmethod validate_specconfig_before(data)[source]

Ensure that a valid configuration was provided and finalize spec_file filepaths.

Parameters:: data (dict) – Pydantic validator data object.
Returns:: Currently validated class attributes.
Return type:: dict

class SpecScans[source]

Bases: CHAPBaseModel

Class representing a set of scans from a single SPEC file.

Variables:

spec_file (str) – Path to the SPEC file.
scan_numbers (int or list[int] or str) – Scan numbers to use.
par_file (str, optional) – Path to a non-default SMB-style par file.

get_detector_data(detectors, scan_number, scan_step_index)[source]

Return the raw data from the specified detectors at the specified scan number and scan step index.

Parameters:

detectors (list[str]) – Detector prefixes to get raw data for.
scan_number (int) – Scan number to get data for.
scan_step_index (int) – Scan step index to get data for.

Returns:

Data from the specified detectors for the specified scan number and scan step index.

Return type:

list[np.ndarray]

get_index(scan_number, scan_step_index, map_config)[source]

Return a tuple representing the index of a specific step in a specific SPEC scan within a map.

Parameters:

scan_number (int) – Scan number to get index for.
scan_step_index (int) – Scan step index to get index for.
map_config (MapConfig) – Map configuration to get index for.

Returns:

Index for the specified scan number and scan step index within the specified map configuration.

Return type:

tuple

get_scanparser(scan_number)[source]

Return a ScanParser <https://github.com/CHESSComputing/chess-scanparsers?tab=readme-ov-file>, for the specified scan number in the specified SPEC file.

Parameters:: scan_number (int) – Scan number to get a ScanParser for.
Returns:: ScanParser for the specified scan number.
Return type:: chess_scanparsers.ScanParser

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

par_file: Annotated[Path, PathType(path_type=file)] | None

scan_numbers: Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)] | Annotated[list[Annotated[int, None, Interval(gt=0, ge=None, lt=None, le=None), None]], Len(min_length=1, max_length=None)]

property scanparsers

Return the list of ScanParser`s <https://github.com/CHESSComputing/chess-scanparsers?tab=readme-ov-file>, for each of the scans specified by the SPEC file and scan numbers belonging to this instance of SpecScans.

Type:: list[chess_scanparsers.ScanParser]

spec_file: Annotated[Path, PathType(path_type=file)]

classmethod validate_par_file(par_file)[source]

Validate the specified SMB-style par file.

Parameters:: par_file (str) – Path to a non-default SMB-style par file.
Raises:: ValueError – If the SMB-style par file is invalid.
Returns:: Validated absolute path to the SMB-style par file.
Return type:: str

classmethod validate_scan_numbers(scan_numbers, info)[source]

Validate the specified list of scan numbers.

Parameters:

scan_numbers (int or list[int] or str) – Scan numbers.
info (pydantic.ValidationInfo) – Model parameter validation information.

Raises:

ValueError – If a specified scan number is not found in the SPEC file.

Returns:

Validated scan numbers.

Return type:

list[int]

classmethod validate_spec_file(spec_file)[source]

Validate the specified SPEC file.

Parameters:: spec_file (str) – Path to the SPEC file.
Raises:: ValueError – If the SPEC file is invalid.
Returns:: Validated absolute path to the SPEC file.
Return type:: str

get_available_scan_numbers(spec_file)[source]

Get the available scan numbers.

Parameters:: spec_file (str) – Path to the SPEC file.
Returns:: Available scan numbers.
Return type:: list[pyspec.file.spec.FileSpec]

get_detector_data(detector_prefixes, spec_file, scan_number, scan_step_index)[source]

Get the detector data.

Parameters:

detector_prefixes (tuple[str] or list[str]) – Detector prefixes.
spec_file (str) – Path to the SPEC file.
scan_number (int) – Scan number to get data for.
scan_step_index (int) – Scan step index.

Returns:

Detector data.

Return type:

list[numpy.ndarray]

get_detector_log_timestamps(spec_file, scan_number, detector_prefix)[source]

Return the list of detector timestamps for the given scan and detector prefix.

Parameters:

spec_file – Location of a SPEC file in which the requested scan occurs.
scan_number (int) – Number of the scan for which to return detector log timestamps.
detector_prefix – Prefix of the detector whose log file should be used.

Returns:

All detector log timestamps for the given scan.

Return type:

list[float]

get_expression_value(spec_scans, scan_number, scan_step_index, expression, scalar_data)[source]

Return the value of an evaluated expression of other sources of point-by-point scalar scan data for a single point.

Parameters:

spec_scans (SpecScans) – Instance of SpecScans in which the requested scan step occurs.
scan_number (int) – Number of the scan in which the requested scan step occurs.
scan_step_index (int) – Requested scan step index.
expression (str) – String expression to evaluate.
scalar_data (list[PointByPointScanData]) – scalar_data field of a MapConfig object (used to provide values for variables used in expression).

Returns:

Par file value for the requested scan.

Return type:

float

get_scan_start_time(spec_file, scan_number)[source]

Return the start time of the indicated spec scan as the unix epoch (in seconds).

Parameters:

spec_file (str) – SPEC file location.
scan_number – Scan number.

Returns:

Epoch at which the scan began.

Return type:

int

get_scanparser(spec_file, scan_number, par_file=None)[source]

Get the scanparser.

Parameters:

spec_file (str) – Path to the SPEC file.
scan_number (int) – Scan number to get data for.
par_file (str, optional) – Path to a SMB-style par file.

Returns:

ScanParser for the requested scan.

Return type:

list[chess_scanparsers.ScanParser]

get_smb_par_value(spec_file, scan_number, par_name)[source]

Return the value recorded for a specific scan in SMB-tyle par file.

Parameters:

spec_file – Location of a SPEC file in which the requested scan step occurs.
scan_number (int) – Number of the scan in which the requested scan step occurs.
par_name (str) – Name of the column in the par file.

Returns:

Value of the par file value for the scan requested.

Return type:

float

get_spec_counter_value(spec_file, scan_number, scan_step_index, spec_column_label)[source]

Return the value recorded for a SPEC counter at a specific scan step.

Parameters:

spec_file – Location of a SPEC file in which the requested scan step occurs.
scan_number (int) – Number of the scan in which the requested scan step occurs.
scan_step_index (int) – Requested scan step index.
spec_column_label (str) – SPEC data column label.

Returns:

Value of the counter at the scan step requested.

Return type:

float

get_spec_motor_value(spec_file, scan_number, scan_step_index, spec_mnemonic, relative=True, static=False, ndigits=None)[source]

Return the value recorded for a SPEC motor at a specific scan step.

Parameters:

spec_file – Location of a SPEC file in which the requested scan step occurs.
scan_number (int) – Number of the scan in which the requested scan step occurs.
scan_step_index (int) – Requested scan step index.
spec_mnemonic (str) – SPEC motor mnemonic.
relative (bool, optional) – Whether to return a relative value or not, defaults to True.
static (bool, optional) – Wether to return just a static motor postion even if the motor is scanned (in which case: return the first position of the motor in the scan); defaults to False.

Params ndigits:

Round SPEC motor values to the specified number of decimals if set.

Returns:

Value of the motor at the scan step requested.

Return type:

float

import_scanparser(station, experiment)[source]

Given the name of a CHESS station and experiment type, import the corresponding subclass of ScanParser as ScanParser.

Parameters:

station (Literal['id1a3', 'id3a', 'id3b', 'id4b']) – Station name (‘IDxx’, not the beamline acronym).
experiment (Literal[ 'EDD', 'GIWAXS', 'HDRM', 'SAXSWAXS', 'TOMO', 'XRF']) – Experiment type.

validate_data_source_for_map_config(data_source, info)[source]

Confirm that an instance of PointByPointScanData is valid for the station and scans provided by a map configuration dictionary.

Parameters:

data_source (PointByPointScanData) – Input object to validate.
info (pydantic.ValidationInfo) – Model parameter validation information.

Raises:

Exception – If data_source cannot be validated.

Returns:

Validated data_source instance.

Return type:

PointByPointScanData