HDFMapControlBMotion

class bapsflib._hdf.maps.controls.bmotion.HDFMapControlBMotion(group: Group)

Bases: HDFMapControlTemplate

Mapping module for the control device ‘bmotion’.

Simple group structure looks like:

+-- bmotion
|   +-- <configuration name>        [Group]
|   +-- Run time list               [Dataset]
|   +-- bmotion_axis_names          [Dataset]
|   +-- bmotion_positions           [Dataset]
|   +-- bmotion_target_positions    [Dataset]

Parameters:: group (h5py.Group) – The HDF5 to apply the mapping to.

Attributes Summary

`configs`	Dictionary containing all the relevant mapping information to translate the corresponding device data in the HDF5 file and provide a consistent user interface via `File`.
`contype`	Control device type.
`dataset_names`	List of names of the HDF5 datasets within the mapped group, at the root level.
`device_name`	Name of Control device
`group`	Instance of the HDF5 group that was mapped.
`group_name`	Name of the mapped HDF5 group.
`group_path`	Path of the mapped HDF5 group in the HDF5 file.
`has_command_list`	`True` if the control device utilizes a command list
`info`	Metadata information about the mapping type and the mapped group location in the HDF5 file.
`maptype`	Mapping class type (`MapTypes`).
`one_config_per_dset`	`True` if each control configuration has its own dataset
`run_config_names`	Tuple of the bmotion run configuration names loaded and used during a data run.
`subgroup_names`	List of names of the HDF5 subgroups within the mapped group, at the root level.

Methods Summary

`construct_dataset_name`(which, *args)	Return the data set name for the specified `which` argument.
`get_config_column_value`(config_name)	For the given configuration name `config_name` get the associated configuration value that would be in the configuration column of the associated HDF5 datasets.
`get_config_name_by_drive_name`(name)	Get the configuration name for the specified drive `name`.
`get_config_name_by_motion_group_id`(_id)	Get the configuration name for the given motion group id.
`get_config_name_by_motion_group_name`(name)	Get the configuration name for the given motion group name.
`get_run_configuration`([run_config_name, ...])	Get the TOML string associated with a specified bmotion run configuration, `run_config_name`.
`process_config_name`(config_name)	Process a given configuration name `config_name` and return the conditioned configuration name.

Attributes Documentation

configs

Dictionary containing all the relevant mapping information to translate the corresponding device data in the HDF5 file and provide a consistent user interface via File.

Notes

The information stored in the configs dictionary is used by HDFReadControls to build the numpy data array from the associated HDF5 dataset(s).

The configs dict is a nested dictionary where the first level of keys represents the control device configuration names. Each configuration name (dict key) has an associated dict value that consists of a set of required keys and optional keys. Any optional key is considered as meta-info for the device and is added to the info dictionary.

The required keys are as follows:

Dictionary breakdown for `config = configs['config name']`
Key	Description
config['dset paths']	Internal HDF5 path to the dataset associated with the control device configuration. For example, config['dset paths'] = ('/foo/bar/Control/d1', )
config['shotnum']	Defines how the run shot numbers are stored in the associated HDF5 dataset, which are mapped to the `'shotnum'` field of the constructed `numpy` array. Should look like, config['shotnum'] = { 'dset paths': config['dset paths'], 'dset field': ('Shot number',), 'shape': (), 'dtype': numpy.int32, } where `'dset paths'` is the internal HDF5 path to the dataset, `'dset field'` is the field name of the dataset containing shot numbers, `'shape'` is the numpy shape of the shot number data, and `'dtype'` is the numpy `dtype` of the data. This all defines the numpy `dtype` of the `'shotnum'` field in the `HDFReadControls` constructed numpy array. If the `'dset paths'` entry is defined as `None`, then the `bapsflib` routines will default to the `'dset paths'` defined for each of the `'state values'` entries.
config['state values']	This is another dictionary defining `'state values'`. For example,: config['state values'] = { 'xyz': { 'dset paths': config['dset paths'], 'dset field': ('x', 'y', 'z'), 'shape': (3,), 'dtype': numpy.float32, 'config column': 'Configuration name', }, } will tell `HDFReadControls` to construct a numpy array with a `'xyz'` field. This field would be a 3-element array of `numpy.float32`, where the `'x'` field of the HDF5 dataset is mapped to the 1st index, `'y'` is mapped to the 2nd index, and `'z'` is mapped to the 3rd index. The `'config column'` indicates the dataset column name that holds the configuration identification value (name, id, etc.). This field is optional, and will look for the column with ‘configuration’ in its name if the field is omitted. Note: A state value field (key) can not be defined as `'signal'` since this field is reserved for digitizer data constructed by `HDFReadData`. If state value data represents probe position data, then it should be given the field name (key) `'xyz'` (like in the example above).

contype: Control device type.

dataset_names: List of names of the HDF5 datasets within the mapped group, at the root level.

device_name: Name of Control device

group: Instance of the HDF5 group that was mapped.

group_name: Name of the mapped HDF5 group.

group_path: Path of the mapped HDF5 group in the HDF5 file.

has_command_list: True if the control device utilizes a command list

info

Metadata information about the mapping type and the mapped group location in the HDF5 file.

Extended Summary

The dictionary will contain the following elements:

info = {
    "group name": "Device",  # name of the mapped HDF5 group
    "group path": "/foo/bar/Device", # internal HDF5 path to the group
    "maptype": self.maptype,  # mapping class type
    "contype": self.contype,  # control device type
}

maptype: Mapping class type (MapTypes).

one_config_per_dset: True if each control configuration has its own dataset

run_config_names: Tuple of the bmotion run configuration names loaded and used during a data run.

subgroup_names: List of names of the HDF5 subgroups within the mapped group, at the root level.

Methods Documentation

construct_dataset_name(which: str, *args) → str: Return the data set name for the specified which argument. The which argument should map directly to the keys of _required_dataset_names.

get_config_column_value(config_name: str) → str | None

For the given configuration name config_name get the associated configuration value that would be in the configuration column of the associated HDF5 datasets.

Typically, the column value is just config_name, but subclasses may override this to provide more sophisticated behavior. For example, if config_name is a mash-up of the column value and some other specifier, then this method can be used to do the proper regex to pull out the column value from config_name.

Parameters:: config_name (str or int) – The configuration name used in configs.

get_config_name_by_drive_name(name: str) → str | None: Get the configuration name for the specified drive name.

get_config_name_by_motion_group_id(_id: int | str) → str | None: Get the configuration name for the given motion group id.

get_config_name_by_motion_group_name(name: str) → str | None: Get the configuration name for the given motion group name.

get_run_configuration(run_config_name: str | None = None, as_toml_string: bool = False) → str | Dict[str, Any]

Get the TOML string associated with a specified bmotion run configuration, run_config_name.

Parameters:

run_config_name (str, optional) – The name of the bmotion run configuration to retrieve. If None, then the run configuration name will be inferred if only ONE configuration is present. (DEFAULT: None)
as_toml_string (bool, optional) – If True, then return the configuration as a TOML string instead of a dictionary. (DEFAULT: False)

Returns:

The TOML string or dict associated with the specified bmotion run configuration, run_config_name.

Return type:

Union[str, Dict[str, Any]]

process_config_name(config_name: str | int) → str | int

Process a given configuration name config_name and return the conditioned configuration name.

The conditioned configuration name is a key to the mapped configs dictionary.

Typically, the conditioned configuration name is just the given config_name, but subclasses may override this method to allow desired “nicknames” to be conditioned into valid configuration names.

Note

This method is integrated into condition_controls, which is used by HDFReadData and HDFReadControls to condition the respective arguments add_controls and controls. This integration is why the nickname mapping implemented here is available in the HDFReadData and HDFReadControls classes, as well as the read data methods of File.

Notes

The bmotion mapping module HDFMapControlBMotion allows for drive names to be used as configuration nicknames, as long as the drive is uniquely used amongst the deployed bmotion configurations. This allows a user to do something like add_controls=[("bmotion", "Hades")] instead of add_controls=[("bmotion", "<Hades> my_long_motion_list_name")] when reading data with read_data.