HDFMapDigiTemplate

class bapsflib._hdf.maps.digitizers.templates.HDFMapDigiTemplate(group: Group)

Bases: HDFMapTemplate, ABC

Template class for all digitizer mapping classes to inherit from.

Note

To fully define a subclass there are several abstract methods that need to be defined, which includes
- construct_dataset_name(),
- construct_header_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.

Additionally, it is recommended to define additional helpers methods to construct and populate the configs dictionary. These would be utilized by _build_configs.

Possible helper methods.
Method	Description
`_adc_info_first_pass()`	Build the tuple of tuples containing the adc connected board and channels numbers, as well as, the associated setup configuration for each connected board.
`_adc_info_second_pass()`	Review and update the adc tuple generated by `_adc_info_first_pass()`. Here, the expected datasets can be checked for existence and the setup dictionary can be append with any additional entries.
`_find_active_adcs()`	Examine the configuration group to determine which digitizer adc’s were used for the configuration.
`_find_adc_connections()`	Used to determine the adc’s connected board and channels. It can also act as the seed for `_adc_info_first_pass()`.
`_parse_config_name()`	Parse the configuration group name to determine the digitizer configuration name.

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

Attributes Summary

`active_configs`	List of active digitizer configurations
`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`.
`dataset_names`	List of names of the HDF5 datasets within the mapped group, at the root level.
`device_adcs`	Tuple of the analog-digital-convert (adc) names integrated into the digitizer.
`device_name`	Name of digitizer (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.
`info`	Metadata information about the mapping type and the mapped group location in the HDF5 file.
`maptype`	Mapping class type (`MapTypes`).
`subgroup_names`	List of names of the HDF5 subgroups within the mapped group, at the root level.

Methods Summary

`construct_dataset_name`(board, channel[, ...])	Constructs the name of the HDF5 dataset containing digitizer data.
`construct_header_dataset_name`(board, channel)	Construct the name of the HDF5 header dataset associated with the digitizer dataset.
`deduce_config_active_status`(config_name)	Determines if data was recorded using the configuration specified by `config_name`.
`get_adc_info`(board, channel, *[, ...])	Get adc setup info dictionary associated with board and channel.
`validate_board_and_channel`(board, channel[, ...])
`validate_config_name`(config_name[, ...])	Validate the specified `config_name` to determine if it is present and active in the digitizer acquisition.
`validate_config_name_and_adc`(config_name, adc)	Validate the specified `config_name` and `adc` name to determine if the set is present and active in the digitizer acquisition.

Attributes Documentation

active_configs: List of active digitizer configurations

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 this configs dictionary is used by HDFReadData 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 digitizer configuration names. Each configuration name (dict key) has an associated dict value that consists of a set of polymorphic and non-polymorphic keys. Any additional keys are currently ignored.

All the polymorphic and non-polymorphic keys described below are required keys.

The non-polymorphic keys are as follows:

Required Non-Polymorphic keys for `config=configs['config name']`
Key	Description
config['active']	`True` or `False` indicating if this configuration was used in recording the digitizer datasets
config['adc']	Tuple of strings naming the adc’s used for this configuration. For example, ('SIS 3301', )
config['config group path']	Internal HDF5 path to the digitizer configuration group. For example, '/foo/bar/SIS 3301/Configuration: first_run'
config['shotnum']	Dictionary defining how the digitizer shot numbers are recorded. Assuming the shot numbers are recorded in the header dataset associated with the main dataset. The dictionary should look like, config['shotnum'] = { 'dset field': ('Shot number',), 'shape': (), 'dtype': numpy.uint32, } where `'dset field'` is the field name of the header dataset containing shot numbers `'shape'` is the `numpy` shape of the shot number data `'dtype'` is the `numpy` `dtype` of the data This all defines the `numpy` `dtype` of the `'shotnum'` field in the `HDFReadData` constructed `numpy` array. If the `'shotnum'` key is given a value of `None` (instead of the above dictionary), then it is assumed that NO shot number is recorded and the generate shot number will follow the rule `shotnum = index + 1`.

There is a required polymorphic key for each adc named in the configs['configs name']['adc'] tuple. This entry is a (N, 3) tuple where N is the number of DAQ boards associated with the adc. Continuing with the example above, the first entry of the 'SIS 3301' polymorphic key would look like:

Breakdown of Polymorphic Key. (`config=configs['config name']`)
Key	Description
config['SIS 3301'][0][0]	`int` representing the connected board number
config['SIS 3301'][0][1]	`Tuple[int, ...]` representing the connected channel numbers associated with the board number
config['SIS 3301'][0][2]	`Dict[str, Any]` representing the setup configuration of the adc. The dictionary should look like: config['SIS 3301'][0][2] = { 'bit: 10, 'clock rate': astropy.units.Quantity(100.0, unit='MHz'), 'nshotnum': 10, 'nt': 10000, 'sample average (hardware)': None, 'shot average (software)': None, 'channel_labels': ('Bx', 'By', 'Bz'), 'time_dset_path': 'time', } where `'bit'` represents the bit resolution of the adc. If given a value of `None`, then it is assumed the digitizer data is saved in volts instead of bit-levels. `'clock rate'` represents the base clock rate of the adc `'nshotnum'` is the number of shot numbers recorded `'nt'` is the number of time samples recorded `'sample average (hardware)'` is the number of time samples averaged together (this and the `'clock rate'` make up the `'sample rate'`) `'shot average (software)'` is the number of shot timeseries intended to be average together `'channel_labels'` (optional) is a tuple of of strings equal in length the number of active channels. These labels are pulled from the digitizers metadata. `'time_dset_path'` (optional) is a relative path to a time array dataset. The path is relative to the root group of the digitizer, i.e. `group_path`. This is used if the digitizer records the time array instead of the clock/sample rate.

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

device_adcs: Tuple of the analog-digital-convert (adc) names integrated into the digitizer.

device_name: Name of digitizer (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.

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
}

maptype: Mapping class type (MapTypes).

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

Methods Documentation

abstractmethod construct_dataset_name(board: int, channel: int, config_name: str = None, adc: str = None, return_info: bool = False) → str | Tuple[str, Dict[str, Any]]

Constructs the name of the HDF5 dataset containing digitizer data.

Parameters:

board (int) – board number
channel (int) – channel number
config_name (str, optional) – digitizer configuration name
adc (str, optional) – analog-digital-converter name
return_info (bool, optional) – True will return a dictionary of meta-info associated with the digitizer data (DEFAULT False)

Returns:

digitizer dataset name. If return_info=True, then returns a tuple of (dataset name, dictionary of meta-info)

Return type:

Union[str, Tuple[str, Dict[str, Any]]]

Notes

The returned adc information dictionary should look like:

adc_dict = {
    'adc': str,
    'bit': int,
    'clock rate': astropy.units.Quantity,
    'configuration name': str,
    'digitizer': str,
    'nshotnum': int,
    'nt': int,
    'sample average (hardware)': int,
    'shot average (software)': int,
    'channel_labels', tuple,  # optional
    'time_dset_path': str,  # optional
}

abstractmethod construct_header_dataset_name(board: int, channel: int, config_name: str = None, adc: str = '', **kwargs) → str

Construct the name of the HDF5 header dataset associated with the digitizer dataset. The header dataset stores shot numbers and other shot number specific meta-data. It also has a one- to-one row correspondence with the digitizer dataset.

Parameters:

board (int) – board number
channel (int) – channel number
config_name (str, optional) – digitizer configuration name
adc (str, optional) – analog-digital-converter name

Returns:

header dataset name associated with the digitizer dataset

Return type:

str

deduce_config_active_status(config_name: str) → bool

Determines if data was recorded using the configuration specified by config_name. This is done by comparing the configuration name against the dataset names.

Parameters:: config_name (str) – digitizer configuration name
Returns:: True if the configuration was used in recording the group datasets; otherwise, False
Return type:: bool

Notes

Note

If the digitizer does not use the configuration name in the name of the created datasets, then the subclassing digitizer mapping class should override this method with a rule that is appropriate for the digitizer the class is being designed for.

get_adc_info(board: int, channel: int, *, config_name: str = None, adc: str = None) → Dict[str, Any]

Get adc setup info dictionary associated with board and channel.

Parameters:

board (int) – board number
channel (int) – channel number
adc (str, optional) – analog-digital-converter name
config_name (str, optional) – digitizer configuration name

Returns:

dictionary of adc setup info (bit, clock rate, averaging, etc.) associated with board and channel

Return type:

Dict[str, Any]

validate_board_and_channel(board: int, channel: int, config_name: str | None = None, adc: str | None = None, allow_inactive: bool = False)

Parameters:

board (int) – Board Number
channel (int) – Channel Number
config_name (str or None) – The config_name to be validated. If None and only one active configuration is present, then the active configuration name will be assumed.
adc (str or None) – The adc to be validated. If None and only one operable analog-digital-converter present, then the single adc will be assumed.
allow_inactive (bool, optional) – If True, then allow an inactive configuration to pass validation. An HDFMappingWaring will be given instead of raising a ValueError. (DEFAULT: False)

Returns:

board (int) – Validated board number.
channel (int) – Validated channel number.
config_name – A validated, and active, configuration name.
adc – A validated, and active, analog-digital-converter name.