class bapsflib._hdf.utils.hdfreadcontrols.HDFReadControls

Bases: numpy.ndarray

Reads control device data from the HDF5 file.

This class constructs and returns a structured numpy array. The data in the array is grouped into two categories:

  1. shot numbers which are contained in the 'shotnum' field

  2. control device data which is represented by the remaining fields in the numpy array. These field names are polymorphic and are defined by the control device mapping class.

Data that is not shot number specific is stored in the info attribute.


  • It is assumed that control data is always extracted with the intent of being matched to digitizer data.

  • Only one control for each ConType can be specified at a time.

  • It is assumed that there is only ONE dataset associated with each control device configuration.

  • If multiple device configurations are saved in the same HDF5 dataset (common in the ‘Waveform’ control device), then it is assumed that the configuration writing order is consistent for all recorded shot numbers. That is, if ‘config1’, ‘config2’, and ‘config3’ are recorded in that order for shot number 1, then that order is preserved for all recorded shot numbers.

  • hdf_file – HDF5 file object

  • controls (Union[str, Iterable[str, Tuple[str, Any]]]) – a list indicating the desired control device names and their configuration name (if more than one configuration exists)

  • shotnum (Union[int, List[int], slice, numpy.ndarray]) – HDF5 file shot number(s) indicating data entries to be extracted

  • intersection_set (bool) – True (DEFAULT) will force the returned shot numbers to be the intersection of shotnum and the shot numbers contained in each control device dataset. False will return the union instead of the intersection

Behavior of shotnum and intersection_set:
  • shotnum indexing starts at 1

  • Any shotnum values <= 0 will be thrown out

  • If intersection_set=True, then only data corresponding to shot numbers that are specified in shotnum and are in all control datasets will be returned

  • If intersection_set=False, then the returned array will have entries for all shot numbers specified in shotnum but entries that correspond to control datasets that do not have the specified shot number will be given a NULL value of -99999, 0, numpy.nan, or '', depending on the numpy.dtype.


Here the control device 'Waveform' is used as a basic example:

>>> # open HDF5 file
>>> f = bapsflib.lapd.File('test.hdf5')
>>> # read control data
>>> # - this is equivalent to 
>>> #   f.read_control(['Waveform', 'config01'])
>>> data = HDFReadControls(f, ['Waveform', 'config01'])
>>> data.dtype
dtype([('shotnum', '<u4'), ('command', '<U18')])
>>> # display shot numbers
>>> data['shotnum']
array([   1,    2,    3, ..., 6158, 6159, 6160], dtype=uint32)
>>> # show 'command' values for shot numbers 1 to 2
>>> data['command'][0:2:]
array(['FREQ 50000.000000', 'FREQ 50000.000000'],

Attributes Summary


A dictionary of meta-info for the control device.

Attributes Documentation


A dictionary of meta-info for the control device.