`CHAP.common.models.map`¶

Module Contents¶

Classes¶

`Sample`	Class representing a sample metadata configuration.
`SpecScans`	Class representing a set of scans from a single SPEC file.
`PointByPointScanData`	Class representing a source of raw scalar-valued data for which a value was recorded at every point in a `MapConfig`.
`IndependentDimension`	Class representing the source of data to identify the coordinate values along one dimension of a `MapConfig`
`CorrectionsData`	Class representing the special instances of `PointByPointScanData` that are used by certain kinds of `CorrectionConfig` tools.
`PresampleIntensity`	Class representing a source of raw data for the intensity of the beam that is incident on the sample.
`PostsampleIntensity`	Class representing a source of raw data for the intensity of the beam that has passed through the sample.
`DwellTimeActual`	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).
`SpecConfig`	Class representing the raw data for one or more SPEC scans.
`MapConfig`	Class representing an experiment consisting of one or more SPEC scans.

Functions¶

`get_available_scan_numbers`
`get_scanparser`
`get_detector_data`
`get_spec_motor_value`	Return the value recorded for a SPEC motor at a specific scan step.
`get_spec_counter_value`	Return the value recorded for a SPEC counter at a specific scan step.
`get_smb_par_value`	Return the value recorded for a specific scan in SMB-tyle .par file.
`get_expression_value`	Return the value of an evaluated expression of other sources of point-by-point scalar scan data for a single point.
`validate_data_source_for_map_config`	Confirm that an instance of PointByPointScanData is valid for the station and scans provided by a map configuration dictionary.
`import_scanparser`	Given the name of a CHESS station and experiment type, import the corresponding subclass of `ScanParser` as `ScanParser`.

API¶

class CHAP.common.models.map.Sample¶

Bases: pydantic.BaseModel

Class representing a sample metadata configuration.

Variables:

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

name: constr(min_length=1)¶: None

description: Optional[str] = <Multiline-String>¶

class CHAP.common.models.map.SpecScans¶

Bases: pydantic.BaseModel

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.

spec_file: pydantic.FilePath¶: None

scan_numbers: conlist(item_type=conint(gt=0), min_length=1)¶: None

par_file: Optional[pydantic.FilePath]¶: None

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

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_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

property scanparsers¶: A list of ScanParsers for each of the scans specified by the SPEC file and scan numbers belonging to this instance of SpecScans

get_scanparser(scan_number)¶

This method returns 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

get_index(scan_number: int, scan_step_index: int, map_config)¶

This method returns 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_detector_data(detectors: list, scan_number: int, scan_step_index: int)¶

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]

CHAP.common.models.map.get_available_scan_numbers(spec_file: str)¶

CHAP.common.models.map.get_scanparser(spec_file: str, scan_number: int, par_file=None)¶

CHAP.common.models.map.get_detector_data(detector_prefixes: tuple, spec_file: str, scan_number: int, scan_step_index: int)¶

class CHAP.common.models.map.PointByPointScanData¶

Bases: pydantic.BaseModel

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.

label: constr(min_length=1)¶: None

units: constr(strip_whitespace=True, min_length=1)¶: None

data_type: Literal[spec_motor, spec_motor_absolute, scan_column, smb_par, expression]¶: None

name: constr(strip_whitespace=True, min_length=1)¶: None

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

validate_for_station(station: str)¶

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.

validate_for_spec_scans(spec_scans: list[CHAP.common.models.map.SpecScans], scan_step_index: Union[Literal[all], int] = '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_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.
Returns:: None

get_value(spec_scans: CHAP.common.models.map.SpecScans, scan_number: int, scan_step_index: int = 0, scalar_data=[], 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', defaults to [].
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, defaults to None.

Returns:

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

Return type:

float

CHAP.common.models.map.get_spec_motor_value(spec_file: str, scan_number: int, scan_step_index: int, spec_mnemonic: str, 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, defaults to None.

Returns:

The value of the motor at the scan step requested.

Return type:

float

CHAP.common.models.map.get_spec_counter_value(spec_file: str, scan_number: int, scan_step_index: int, spec_column_label: str)¶

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

CHAP.common.models.map.get_smb_par_value(spec_file: str, scan_number: int, par_name: str)¶

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

CHAP.common.models.map.get_expression_value(spec_scans: CHAP.common.models.map.SpecScans, scan_number: int, scan_step_index: int, expression: str, scalar_data: list[CHAP.common.models.map.PointByPointScanData])¶

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

CHAP.common.models.map.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

class CHAP.common.models.map.IndependentDimension¶

Bases: CHAP.common.models.map.PointByPointScanData

Class representing the source of data to identify the coordinate values along one dimension of 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.
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.

start: Optional[conint(ge=0)]¶: 0

end: Optional[int]¶: None

step: Optional[conint(gt=0)]¶: 1

class CHAP.common.models.map.CorrectionsData¶

Bases: CHAP.common.models.map.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, 'presample_intensity', 'postsample_intensity', or 'dwell_time_actual'.
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.

label: Literal[presample_intensity, postsample_intensity, dwell_time_actual]¶: None

data_type: Literal[scan_column, smb_par]¶: None

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 CHAP.common.models.map.PresampleIntensity¶

Bases: CHAP.common.models.map.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'.
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.

label: Literal[presample_intensity]¶: ‘presample_intensity’

units: Literal[counts]¶: ‘counts’

class CHAP.common.models.map.PostsampleIntensity¶

Bases: CHAP.common.models.map.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'.
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.

label: Literal[postsample_intensity]¶: ‘postsample_intensity’

units: Literal[counts]¶: ‘counts’

class CHAP.common.models.map.DwellTimeActual¶

Bases: CHAP.common.models.map.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 'counts'.
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.

label: Literal[dwell_time_actual]¶: ‘dwell_time_actual’

units: Literal[s]¶: ‘s’

class CHAP.common.models.map.SpecConfig¶

Bases: pydantic.BaseModel

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.

station: Literal[id1a3, id3a, id3b]¶: None

experiment_type: Literal[EDD, GIWAXS, SAXSWAXS, TOMO, XRF]¶: None

spec_scans: conlist(item_type=SpecScans, min_length=1)¶: None

classmethod validate_config(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

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

class CHAP.common.models.map.MapConfig¶

Bases: pydantic.BaseModel

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

Variables:

title – The title for the map configuration.
station – The name of the station at which the map was collected.
spec_scans – A list of the SPEC scans that compose the map.
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'.
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 [].

title: constr(strip_whitespace=True, min_length=1)¶: None

station: Literal[id1a3, id3a, id3b]¶: None

experiment_type: Literal[EDD, GIWAXS, SAXSWAXS, TOMO, XRF]¶: None

sample: CHAP.common.models.map.Sample¶: None

spec_scans: conlist(item_type=SpecScans, min_length=1)¶: None

scalar_data: Optional[list[CHAP.common.models.map.PointByPointScanData]]¶: []

independent_dimensions: conlist(item_type=IndependentDimension, min_length=1)¶: None

presample_intensity: Optional[CHAP.common.models.map.PresampleIntensity]¶: None

dwell_time_actual: Optional[CHAP.common.models.map.DwellTimeActual]¶: None

postsample_intensity: Optional[CHAP.common.models.map.PostsampleIntensity]¶: None

attrs: Optional[typing_extensions.Annotated[dict, Field(validate_default=True)]]¶: None

_dims: tuple¶: ‘PrivateAttr(…)’

_validate_independent_dimensions¶: ‘(…)’

_validate_presample_intensity¶: ‘(…)’

_validate_dwell_time_actual¶: ‘(…)’

_validate_postsample_intensity¶: ‘(…)’

_validate_scalar_data¶: ‘(…)’

classmethod validate_config(data)¶

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

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_attrs(attrs, info)¶

Read 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

static get_smb_par_attr(class_fields, label, units='-', name=None)¶: Read an SMB par file attribute.

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.

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

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

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.

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]

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.

CHAP.common.models.map.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’]) – The experiment type.

`CHAP.common.models.map`¶

Module Contents¶

Classes¶

Functions¶

API¶

Table of Contents

Table of Contents

Previous topic

Next topic

CHAP.common.models.map¶

Module Contents¶

Classes¶

Functions¶

API¶

`CHAP.common.models.map`¶