CHAP.common.models package

Submodules

CHAP.common.models.common module

Common Pydantic model classes.

class BinarizeProcessorConfig(*, method: Literal['CHAP', 'isodata', 'minimum', 'otsu', 'yen'] | None = 'CHAP', num_bin: Annotated[int, None, Interval(gt=None, ge=0, lt=None, le=None), None] | None = 256, nxpath: str | None = None, remove_original_data: bool | None = False)

Bases: CHAPBaseModel

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

Parameters:

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 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] = {}: 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(*, animation: bool | None = False, 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)] | None = 0, 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 = None, index_range: int | Annotated[list[None | int], Len(min_length=2, max_length=3)] | None = None, fileformat: Literal['gif', 'jpeg', 'png', 'tif'] | None = None, vrange: 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=2)] | None = None)

Bases: CHAPBaseModel

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

Parameters:

animation (bool, optional) – Create an animation for an image stack (ignored for a single image), defaults to False.
axis (Union[int, str], optional) – Axis direction or name for the image slice(s), defaults to 0.
coord_range (Union[float, 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 (Union[int, 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.
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).

Variables:

fileformat – Image (stack) return file type, defaults to ‘png’ for a single image, ‘tif’ for an image stack, or ‘gif’ for an animation.

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)] | 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'] | None

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

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

classmethod validate_index_range(index_range)

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)

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[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

CHAP.common.models.integration module

Map integration related Pydantic model classes.

class Detector(*, prefix: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], poni_file: Annotated[Path, PathType(path_type=file)], mask_file: Annotated[Path, PathType(path_type=file)] | None = None)

Bases: CHAPBaseModel

Detector class to represent a single detector used in the experiment.

Parameters:

prefix (str) – Prefix of the detector in the SPEC file.
poni_file (str) – Path to the poni file.
mask_file (str, optional) – Optional path to the mask file.

property azimuthal_integrator: Return the azimuthal integrator associated with this detector.

property mask_array: Return the mask array assocated with this detector.

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

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

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

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

classmethod validate_mask_file(mask_file, values)

Validate the mask file. If a mask file is provided, it checks if it’s a valid TIFF file.

Parameters:

mask_file (str or None) – Path to the mask file.
values (dict) – A dictionary of the Detector fields.

Raises:

ValueError – If mask_file is provided and it’s not a valid TIFF file.
ValueError – If ‘poni_file’ is not provided in values.

Returns:

Absolute path to the mask file or None.

Return type:

Union[str, None]

classmethod validate_poni_file(poni_file)

Validate the poni file by checking if it’s a valid PONI file.

Parameters:: poni_file (str) – Path to the poni file.
Raises:: ValueError – If poni_file is not a valid PONI file.
Returns:: Absolute path to the poni file.
Return type:: str

class IntegrationConfig(*, tool_type: Literal['integration'] = 'integration', title: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], integration_type: Literal['azimuthal', 'radial', 'cake'], detectors: Annotated[list[Detector], Len(min_length=1, max_length=None)], radial_units: str = 'q_A^-1', radial_min: Annotated[float, None, Interval(gt=None, ge=0, lt=None, le=None), None, None], radial_max: Annotated[float, None, Interval(gt=0, ge=None, lt=None, le=None), None, None], radial_npt: Annotated[int, None, Interval(gt=0, ge=None, lt=None, le=None), None] = 1800, azimuthal_units: str = 'chi_deg', azimuthal_min: Annotated[float, None, Interval(gt=None, ge=-180, lt=None, le=None), None, None] = -180, azimuthal_max: Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=360), None, None] = 180, azimuthal_npt: Annotated[int, None, Interval(gt=0, ge=None, lt=None, le=None), None] = 3600, error_model: Literal['poisson', 'azimuthal'] | None = None, sequence_index: Annotated[int, None, Interval(gt=0, ge=None, lt=None, le=None), None] | None = None)

Bases: CHAPBaseModel

Class representing the configuration for a raw detector data integration.

Variables:

tool_type – Integration tool type; always set to “integration”.
title – Integration title.
integration_type – Integration type.
detectors – List of detectors used in the integration.
radial_units – Radial units for the integration, defaults to ‘q_A^-1’.
radial_min – Minimum radial value for the integration range.
radial_max – Maximum radial value for the integration range.
radial_npt – Number of points in the radial range for the integration, defaults to 1800.
azimuthal_units – Azimuthal units for the integration, defaults to chi_deg.
azimuthal_min – Minimum azimuthal value for the integration range, defaults to -180.
azimuthal_max – Maximum azimuthal value for the integration range, defaults to 180.
azimuthal_npt – Number of points in the azimuthal range for the integration, defaults to 3600.
error_model – Integration error model.
sequence_index – Sequence index for the correction NXprocess object in the Nexus file.

azimuthal_max: Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=360), None, None]

azimuthal_min: Annotated[float, None, Interval(gt=None, ge=-180, lt=None, le=None), None, None]

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

azimuthal_units: str

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

error_model: Literal['poisson', 'azimuthal'] | None

get_azimuthal_adjustments()

To enable a continuous range of integration in the azimuthal direction for radial and cake integration, obtain adjusted values for this IntegrationConfig’s azimuthal_min and azimuthal_max values, the angle amount by which those values were adjusted, and the proper location of the discontinuity in the azimuthal direction.

Returns:: Adjusted chi_min, adjusted chi_max, chi_offset, chi_discontinuity.
Return type:: tuple[float, float, float, float]

get_azimuthal_integrators()

Get a list of AzimuthalIntegrator`s that correspond to the detector configurations in this instance of IntegrationConfig.

The returned AzimuthalIntegrators are (if need be) artificially rotated in the azimuthal direction to achieve a continuous range of integration in the azimuthal direction.

Returns:: A list of AzimuthalIntegrators appropriate for use by this IntegrationConfig tool.
Return type:: list[pyFAI.azimuthalIntegrator.AzimuthalIntegrator]

get_azimuthally_integrated_data(spec_scans, scan_number, scan_step_index)

Return azimuthally-integrated data for the scan step specified.

Parameters:

spec_scans (SpecScans) – An instance of SpecScans containing the scan step requested.
scan_number (int) – The number of the scan containing the scan step requested.
scan_step_index (int) – The index of the scan step requested.

Returns:

A 1D array of azimuthally-integrated raw detector intensities.

Return type:

np.ndarray

get_cake_integrated_data(spec_scans, scan_number, scan_step_index)

Return cake-integrated data for the scan step specified.

Parameters:

spec_scans (SpecScans) – An instance of SpecScans containing the scan step requested.
scan_number (int) – The number of the scan containing the scan step requested.
scan_step_index (int) – The index of the scan step requested.

Returns:

A 2D array of cake-integrated raw detector intensities.

Return type:

np.ndarray

get_integrated_data(spec_scans, scan_number, scan_step_index)

Return integrated data for the scan step specified.

Parameters:

spec_scans (SpecScans) – An instance of SpecScans containing the scan step requested.
scan_number (int) – The number of the scan containing the scan step requested.
scan_step_index (int) – The index of the scan step requested.

Returns:

An array of integrated raw detector intensities.

Return type:

np.ndarray

get_multi_geometry_integrator()

Get a MultiGeometry integrator suitable for use by this instance of IntegrationConfig.

Returns:: A MultiGeometry integrator.
Return type:: pyFAI.multi_geometry.MultiGeometry

get_radially_integrated_data(spec_scans, scan_number, scan_step_index)

Return radially-integrated data for the scan step specified.

Parameters:

spec_scans (SpecScans) – An instance of SpecScans containing the scan step requested.
scan_number (int) – The number of the scan containing the scan step requested.
scan_step_index (int) – The index of the scan step requested.

Returns:

A 1D array of radially-integrated raw detector intensities.

Return type:

np.ndarray

property integrated_data_coordinates

Return a dictionary of coordinate arrays for navigating the dimension(s) of the integrated data produced by this instance of IntegrationConfig.

Returns:: A dictionary with either one or two keys: ‘azimuthal’ and/or ‘radial’, each of which points to a 1-D numpy array of coordinate values.
Return type:: dict[str, np.ndarray]

property integrated_data_dims: Return a tuple of the coordinate labels for the integrated data produced by this instance of IntegrationConfig.

property integrated_data_shape: Return a tuple representing the shape of the integrated data produced by this instance of IntegrationConfig for a single scan step.

integration_type: Literal['azimuthal', 'radial', 'cake']

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

radial_max: Annotated[float, None, Interval(gt=0, ge=None, lt=None, le=None), None, None]

radial_min: Annotated[float, None, Interval(gt=None, ge=0, lt=None, le=None), None, None]

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

radial_units: str

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

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

tool_type: Literal['integration']

classmethod validate_azimuthal_units(azimuthal_units)

Validate that azimuthal_units is one of the keys in the pyFAI.units.AZIMUTHAL_UNITS dictionary.

Parameters:: azimuthal_units (str) – The string representing the unit to be validated.
Raises:: ValueError – If azimuthal_units is not one of the keys in pyFAI.units.AZIMUTHAL_UNITS.
Returns:: The original supplied value, if is one of the keys in pyFAI.units.AZIMUTHAL_UNITS.
Return type:: str

validate_for_map_config(map_config)

Validate the existence of the detector data file for all scan points in map_config.

Parameters:: map_config (MapConfig) – The MapConfig instance to validate against.
Raises:: RuntimeError – If a detector data file could not be found for a scan point occurring in map_config.

classmethod validate_radial_units(radial_units)

Validate the radial units for the integration.

Parameters:: radial_units (str) – Unvalidated radial units for the integration.
Raises:: ValueError – If radial units are not one of the recognized radial units.
Returns:: Validated radial units.
Return type:: str

azimuthal_integrator(poni_file)

Return the azimuthal integrator from a PONI file.

Parameters:: poni_file (str) – Path to a PONI file.
Returns:: Azimuthal integrator.
Return type:: pyFAI.azimuthal_integrator.AzimuthalIntegrator

get_azimuthal_adjustments(chi_min, chi_max)

Fix chi discontinuity at 180 degrees and return the adjusted chi range, offset, and discontinuity.

If the discontinuity is crossed, obtain the offset to artificially rotate detectors to achieve a continuous azimuthal integration range.

Parameters:

chi_min (float) – The minimum value of the azimuthal range.
chi_max (float) – The maximum value of the azimuthal range.

Returns:

The following four values: the adjusted minimum value of the azimuthal range, the adjusted maximum value of the azimuthal range, the value by which the chi angle was adjusted, the position of the chi discontinuity.

Return type:

tuple[float, float, float, float]

get_azimuthal_integrators(poni_files, chi_offset=0)

Return a list of AzimuthalIntegrator objects generated from PONI files.

Parameters:

poni_files (tuple) – Tuple of strings, each string being a path to a PONI file.
chi_offset (float, optional) – The angle in degrees by which the AzimuthalIntegrator objects will be rotated, defaults to 0.

Returns:

List of AzimuthalIntegrator objects.

Return type:

list[pyFAI.azimuthalIntegrator.AzimuthalIntegrator]

get_integrated_data_coordinates(azimuthal_range=None, azimuthal_npt=None, radial_range=None, radial_npt=None)

Return a dictionary of coordinate arrays for the specified radial and/or azimuthal integration ranges.

Parameters:

azimuthal_range (tuple[float, float], optional) – Tuple specifying the range of azimuthal angles over which to generate coordinates, in the format (min, max).
azimuthal_npt (int, optional) – Number of azimuthal coordinate points to generate.
radial_range (tuple[float, float], optional) – Tuple specifying the range of radial distances over which to generate coordinates, in the format (min, max).
radial_npt (int, optional) – Number of radial coordinate points to generate.

Returns:

A dictionary with either one or two keys: ‘azimuthal’ and/or ‘radial’, each of which points to a 1-D numpy array of coordinate values.

Return type:

dict[str, np.ndarray]

get_mask_array(mask_file, poni_file)

Return a mask array associated with a detector loaded from a tiff file.

Parameters:

mask_file (str) – Path to a .tiff file.
poni_file (str) – Path to a PONI file.

Returns:

The mask array loaded from mask_file.

Return type:

numpy.ndarray

get_multi_geometry_integrator(poni_files, radial_unit, radial_range, azimuthal_range)

Return a MultiGeometry instance that can be used for azimuthal or cake integration.

Parameters:

poni_files (tuple) – Tuple of PONI files that describe the detectors to be integrated.
radial_unit (str) – Unit to use for radial integration range.
radial_range (tuple[float, float]) – Radial integration range.
azimuthal_range (tuple[float, float]) – Azimuthal integration range.

Returns:

MultiGeometry instance that can be used for azimuthal or cake integration.

Return type:

pyFAI.multi_geometry.MultiGeometry

CHAP.common.models.map module

Map related Pydantic model classes.

class CorrectionsData(*, label: Literal['presample_intensity', 'postsample_intensity', 'dwell_time_actual'], units: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], data_type: Literal['scan_column', 'smb_par'], name: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], ndigits: Annotated[int, None, Interval(gt=None, ge=0, lt=None, le=None), None] | None = None)

Bases: PointByPointScanData

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

Variables:

label – One of the reserved values required by CorrectionConfig.
data_type – Represents how these data were recorded at time of data collection.

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

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

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

classmethod reserved_labels()

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

Returns:: A list of reserved labels.
Return type:: list[str]

class Detector(*, id: Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], attrs: Annotated[dict, FieldInfo(annotation=NoneType, required=True, validate_default=True)] | None = {})

Bases: CHAPBaseModel

Class representing a single detector.

Variables:

id – The detector id (e.g. name or channel index).
attrs – Additional detector configuration attributes.

attrs: Annotated[dict, FieldInfo(annotation=NoneType, required=True, validate_default=True)] | None

get_id()

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

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

classmethod validate_attrs(attrs)

Validate any additional detector configuration attributes.

Parameters:: attrs (dict) – Any additional attributes to Detector.
Raises:: ValueError – Invalid attribute.
Returns:: The validated field for attrs.
Return type:: dict

classmethod validate_id(id_)

Validate the detector id.

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

class DetectorConfig(*, detectors: Annotated[list[Detector], Len(min_length=1, max_length=None)])

Bases: CHAPBaseModel

Class representing a detector configuration.

Variables:: detectors – Detector list.

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

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

class DwellTimeActual(*, label: Literal['dwell_time_actual'] = 'dwell_time_actual', units: Literal['s'] = 's', data_type: Literal['scan_column', 'smb_par'], name: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], ndigits: Annotated[int, None, Interval(gt=None, ge=0, lt=None, le=None), None] | None = None)

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 – Must be ‘dwell_time_actual’.
units – Must be ‘s’.

label: Literal['dwell_time_actual']

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

units: Literal['s']

class IndependentDimension(*, label: Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], units: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], data_type: Literal['spec_motor', 'spec_motor_absolute', 'scan_column', 'smb_par', 'expression', 'detector_log_timestamps'], name: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], ndigits: Annotated[int, None, Interval(gt=None, ge=0, lt=None, le=None), None] | None = None, start: Annotated[int, None, Interval(gt=None, ge=0, lt=None, le=None), None] | None = 0, end: int | None = None, step: Annotated[int, None, Interval(gt=0, ge=None, lt=None, le=None), None] | None = 1)

Bases: PointByPointScanData

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

Variables:

start – Sarting index for slicing all datasets of a MapConfig along this axis, defaults to 0.
end – 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 – Step for slicing all datasets of a MapConfig along this axis, defaults to 1.

end: int | None

model_config: ClassVar[ConfigDict] = {}: 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(*, did: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=None)] | None = None, title: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], station: Literal['id1a3', 'id3a', 'id3b', 'id4b'], experiment_type: Literal['EDD', 'GIWAXS', 'SAXSWAXS', 'TOMO', 'XRF', 'HDRM'], sample: Sample, spec_scans: Annotated[list[SpecScans], Len(min_length=1, max_length=None)], scalar_data: Annotated[list[PointByPointScanData], Len(min_length=0, max_length=None)] | None = [], independent_dimensions: Annotated[list[IndependentDimension], Len(min_length=1, max_length=None)], presample_intensity: PresampleIntensity | None = None, dwell_time_actual: DwellTimeActual | None = None, postsample_intensity: PostsampleIntensity | None = None, attrs: Annotated[dict, FieldInfo(annotation=NoneType, required=True, validate_default=True)] | None = {})

Bases: CHAPBaseModel

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

Param:

did: FOXDEN data identifier.

Variables:

title – The title for the map configuration.
station – The name of the station at which the map was collected.
experiment_type – Experiment type.
sample – The sample metadata configuration.
spec_scans – A list of the SPEC scans that compose the map.
scalar_data – A list of the 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 – A list of the sources of data representing the raw values of each independent dimension of the map.
presample_intensity – A source of point-by-point presample beam intensity data. Required when applying a CorrectionConfig tool.
dwell_time_actual – A source of point-by-point actual dwell times for SPEC scans. Required when applying a CorrectionConfig tool.
postsample_intensity – A source of point-by-point postsample beam intensity data. Required when applying a CorrectionConfig tool with correction_type=’flux_absorption’ or correction_type=’flux_absorption_background’.
attrs – Additional Map 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.

attrs: Annotated[dict, FieldInfo(annotation=NoneType, required=True, validate_default=True)] | None

property coords: Return a dictionary of the values of each independent dimension across the map.

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

property dims: Return a tuple of the independent dimension labels for the map.

dwell_time_actual: DwellTimeActual | None

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

get_coords(map_index)

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

Parameters:: map_index (tuple) – The map index to return coordinates for.
Returns:: A list of coordinate values.
Return type:: dict

get_detector_data(detector_name, map_index)

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) – The map index to return detector data for.

Returns:

One frame of raw detector data.

Return type:

np.ndarray

get_scan_step_index(map_index)

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

Parameters:: map_index (tuple) – The index of a map point to identify as a specific SPEC scan step index.
Returns:: A 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)

Read an SMB par file attribute.

Parameters:

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

get_value(data, map_index)

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

Parameters:

data (PointByPointScanData) – The device configuration to return a value of raw data for.
map_index (tuple) – The map index to return raw data for.

Returns:

Raw data value.

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

model_config: ClassVar[ConfigDict] = {}: 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 initialise 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.

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

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)]

classmethod validate_attrs(attrs, info)

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

Parameters:

attrs (dict) – Any additional attributes to the MapConfig class.
info (pydantic_core._pydantic_core.ValidationInfo) – Pydantic validator info object.

Raises:

ValueError – Invalid attribute.

Returns:

The validated field for attrs.

Return type:

dict

classmethod validate_experiment_type(experiment_type, info)

Ensure values for the station and experiment_type fields are compatible.

Parameters:

experiment_type (dict) – The value of experiment_type to validate.
info (pydantic_core._pydantic_core.ValidationInfo) – Pydantic validator info object.

Raises:

ValueError – Invalid experiment type.

Returns:

The validated field for experiment_type.

Return type:

str

classmethod validate_mapconfig_before(data, info)

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

Parameters:: data (MapConfig, pydantic_core._pydantic_core.ValidationInfo) – Pydantic validator data object.
Returns:: The currently validated list of class properties.
Return type:: dict

class PointByPointScanData(*, label: Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], units: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], data_type: Literal['spec_motor', 'spec_motor_absolute', 'scan_column', 'smb_par', 'expression', 'detector_log_timestamps'], name: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], ndigits: Annotated[int, None, Interval(gt=None, ge=0, lt=None, le=None), None] | None = None)

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 – A user-defined label for referring to this data in the NeXus file and in other tools.
units – The units in which the data were recorded.
data_type – Represents how these data were recorded at time of data collection.
name – Represents the name with which these raw data were recorded at time of data collection.

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

get_value(spec_scans, scan_number, scan_step_index=0, scalar_data=None, relative=True, ndigits=None)

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) – The number of the scan in which the requested scan step occurs.
scan_step_index (int, optional) – The index of the requested scan step, defaults to 0.
scalar_data (list[PointByPointScanData], optional) – list of 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).

Params ndigits:

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

Returns:

The 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)]

model_config: ClassVar[ConfigDict] = {}: 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)]

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)]

validate_for_scalar_data(scalar_data)

Used for PointByPointScanData objects with a data_type of ‘expression’. Validate that the scalar_data field of a 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')

Validate this instance of PointByPointScanData for a list of SpecScans.

Parameters:

spec_scans (list[SpecScans]) – A list of SpecScans whose raw data will be checked for the presence of the data represented by this instance of PointByPointScanData.
scan_step_index (Union[Literal['all'],int], optional) – A 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)

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

Parameters:: station (str) – The name of the station (in ‘idxx’ format).
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)

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) – The value of label to validate.
Raises:: ValueError – If label is one of the reserved values.
Returns:: The originally supplied value label.
Return type:: str

class PostsampleIntensity(*, label: Literal['postsample_intensity'] = 'postsample_intensity', units: Literal['counts'] = 'counts', data_type: Literal['scan_column', 'smb_par'], name: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], ndigits: Annotated[int, None, Interval(gt=None, ge=0, lt=None, le=None), None] | None = None)

Bases: CorrectionsData

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

Variables:

label – Must be ‘postsample_intensity’.
units – Must be ‘counts’.

label: Literal['postsample_intensity']

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

units: Literal['counts']

class PresampleIntensity(*, label: Literal['presample_intensity'] = 'presample_intensity', units: Literal['counts'] = 'counts', data_type: Literal['scan_column', 'smb_par'], name: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], ndigits: Annotated[int, None, Interval(gt=None, ge=0, lt=None, le=None), None] | None = None)

Bases: CorrectionsData

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

Variables:

label – Must be ‘presample_intensity”.
units – Must be ‘counts’.

label: Literal['presample_intensity']

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

units: Literal['counts']

class Sample(*, name: Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], description: str | None = '')

Bases: CHAPBaseModel

Class representing a sample metadata configuration.

Variables:

name – The name of the sample.
description – A description of the sample.

description: str | None

model_config: ClassVar[ConfigDict] = {}: 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)]

class SpecConfig(*, station: Literal['id1a3', 'id3a', 'id3b', 'id4b'], experiment_type: Literal['EDD', 'GIWAXS', 'SAXSWAXS', 'TOMO', 'XRF', 'HDRM'], spec_scans: Annotated[list[SpecScans], Len(min_length=1, max_length=None)])

Bases: CHAPBaseModel

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

Variables:

station – The name of the station at which the data was collected.
spec_scans – A list of the SPEC scans that compose the set.
experiment_type – Experiment type.

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

model_config: ClassVar[ConfigDict] = {}: 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)

Ensure values for the station and experiment_type fields are compatible.

Parameters:

experiment_type (str) – The value of experiment_type to validate.
info (pydantic_core._pydantic_core.ValidationInfo) – Pydantic validator info object.

Raises:

ValueError – Invalid experiment type.

Returns:

The validated field for experiment_type.

Return type:

str

classmethod validate_specconfig_before(data)

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

Parameters:: data (SpecConfig, pydantic_core._pydantic_core.ValidationInfo) – Pydantic validator data object.
Returns:: The currently validated list of class properties.
Return type:: dict

class SpecScans(*, spec_file: Annotated[Path, PathType(path_type=file)], scan_numbers: Annotated[list[Annotated[int, None, Interval(gt=0, ge=None, lt=None, le=None), None]], Len(min_length=1, max_length=None)], par_file: Annotated[Path, PathType(path_type=file)] | None = None)

Bases: CHAPBaseModel

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

Variables:

spec_file – Path to the SPEC file.
scan_numbers – List of scan numbers to use.
par_file – Path to a non-default SMB par file.

get_detector_data(detectors, scan_number, scan_step_index)

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

Parameters:

detectors (list[str]) – List of 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)

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)

Return a ScanParser 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:: ScanParser

model_config: ClassVar[ConfigDict] = {}: 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[list[Annotated[int, None, Interval(gt=0, ge=None, lt=None, le=None), None]], Len(min_length=1, max_length=None)]

property scanparsers: Returns the list of ScanParser`s for each of the scans specified by the SPEC file and scan numbers belonging to this instance of `SpecScans.

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

classmethod validate_par_file(par_file)

Validate the specified SMB par file.

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

classmethod validate_scan_numbers(scan_numbers, info)

Validate the specified list of scan numbers.

Parameters:

scan_numbers (Union(int, list[int], str)) – List of scan numbers.
info (pydantic_core._pydantic_core.ValidationInfo) – Pydantic validator info object.

Raises:

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

Returns:

List of scan numbers.

Return type:

list[int]

classmethod validate_spec_file(spec_file)

Validate the specified SPEC file.

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

get_available_scan_numbers(spec_file)

Get the available scan numbers.

Parameters:: spec_file (str) – Path to the SPEC file.

get_detector_data(detector_prefixes, spec_file, scan_number, scan_step_index)

Get the detector data.

Parameters:

detector_prefixes (Union[tuple[str], list[str]]) – The detector prefixes.
scan_number (int) – Scan number to get data for.
scan_step_index (int) – The scan step index.

Variables:

spec_file – Path to the SPEC file.

get_detector_log_timestamps(spec_file, scan_number, detector_prefix)

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

Parameters:

spec_file – Location of a SPEC file in which the requested scan occurs.
scan_number (int) – The number of the scan for which to return detector log timestamps.
detector_prefix – The prefix of the detecotr 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)

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) – An instance of SpecScans in which the requested scan step occurs.
scan_number (int) – The number of the scan in which the requested scan step occurs.
scan_step_index (int) – The index of the requested scan step.
expression (str) – The string expression to evaluate.
scalar_data (list[PointByPointScanData]) – the scalar_data field of a MapConfig object (used to provide values for variables used in expression).

Returns:

The value of the .par file value for the scan requested.

Return type:

float

get_scanparser(spec_file, scan_number, par_file=None)

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 par file.

get_smb_par_value(spec_file, scan_number, par_name)

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) – The number of the scan in which the requested scan step occurs.
par_name (str) – The name of the column in the .par file.

Returns:

The 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)

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) – The number of the scan in which the requested scan step occurs.
scan_step_index (int) – The index of the requested scan step.
spec_column_label (str) – The label of a SPEC data column.

Returns:

The 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, ndigits=None)

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) – The number of the scan in which the requested scan step occurs.
scan_step_index (int) – The index of the requested scan step.
spec_mnemonic (str) – The menmonic of a SPEC motor.
relative (bool, optional) – Whether to return a relative value or not, defaults to True.

Params ndigits:

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

Returns:

The value of the motor at the scan step requested.

Return type:

float

import_scanparser(station, experiment)

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

Parameters:

station (str) – The station name (‘IDxx’, not the beamline acronym).
experiment (Literal[ 'EDD', 'GIWAXS', 'SAXSWAXS', 'TOMO', 'XRF', 'HDRM']) – The experiment type.

validate_data_source_for_map_config(data_source, info)

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

Parameters:

data_source (PointByPointScanData) – The input object to validate.
info (pydantic_core._pydantic_core.ValidationInfo) – Pydantic validator info object.

Raises:

Exception – If data_source cannot be validated.

Returns:

The validated data_source instance.

Return type:

PointByPointScanData

Module contents

This subpackage contains PipelineItems that are common to various processing workflows.