HDFMapControlTemplate

class bapsflib._hdf.maps.controls.templates.HDFMapControlTemplate(group: Group)

Bases: HDFMapTemplate, ABC

Template class for all control mapping classes to inherit from.

Note

If a control device is structured around a command list, then its mapping class should subclass HDFMapControlCLTemplate instead.
To fully define a subclass there are several abstract methods that need to be defined, which includes
- construct_dataset_name()
- _build_configs()
  
  abstractmethod _build_configs()
  
  Inspect the HDF5 group and build the configuration dictionary, configs.
  
  Functionality should specifically populate self._configs instead of self.configs. If a mapping fails, then a HDFMappingError should be raised.
If a subclass needs to initialize additional variables before _build_configs is called in the __init__, then those routines can be defined in the _init_before_build_configs method.

_init_before_build_configs()

Any initialization that needs to be performed before executing self._build_configs in __init__.

By default we do nothing, but subclasses can override this for their specific purposes.

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
`subgroup_names`	List of names of the HDF5 subgroups within the mapped group, at the root level.

Methods Summary

`construct_dataset_name`(*args)	Constructs the dataset name corresponding to the input arguments.
`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.
`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

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

Methods Documentation

abstractmethod construct_dataset_name(*args) → str

Constructs the dataset name corresponding to the input arguments.

Returns:: name of dataset
Return type:: str

get_config_column_value(config_name: str | int) → 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.

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.