HDFReadData

class bapsflib._hdf.utils.hdfreaddata.HDFReadData(hdf_file: File, board: int, channel: int, index=slice(None, None, None), shotnum=slice(None, None, None), digitizer=None, config_name=None, adc=None, keep_bits=False, add_controls=None, intersection_set=True, **kwargs)

Bases: ndarray

Reads digitizer and control device data from the HDF5 file. Control device data is extracted using HDFReadControls and combined with the digitizer data.

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

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

  2. digitizer data which is contained in the 'signal' field

  3. 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. (see HDFReadControls for more detail)

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

Note

  • Every returned numpy array will have the 'xyz' field, which is reserved for probe position data. If a control device specifies this field, then field will be filled with the control device data;otherwise, the field will be filled with numpy.nan values.

Parameters:

  • hdf_file – HDF5 file object

  • board – analog-digital-converter board number

  • channel – analog-digital-converter channel number

  • index (Union[int, List[int], slice, numpy.ndarray]) – dataset row indices to be sliced (overridden by shotnum)

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

  • digitizer (str) – digitizer name

  • adc (str) – name of analog-digital-converter

  • config_name (str) – name of the digitizer configuration

  • keep_bits (bool) – set True to keep data in bits, False (DEFAULT) to convert data to voltage

  • add_controls – a list indicating the desired control device names and their configuration name (if more than one configuration exists)

  • 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 and digitizer dataset. False will return the union of shot numbers.

Behavior of index, shotnum and intersection_set:

Note

  • The shotnum keyword will always override the index keyword, but, due to extra overhead required for identifying shot number locations in the digitizer dataset, the index keyword will always execute quicker than the shotnum keyword.

Example:

Here data is extracted from the digitizer 'SIS crate' and position data is mated from the control device '6K Compumotor'.

>>> # open HDF5 file
>>> f = bapsflib.lapd.File('test.hdf5')
>>>
>>> # read digitizer data from board 1, channel 1,
>>> # - this is equivalent to 
>>> #   f.read_data(1, 1)
>>> data = HDFReadData(f, 1, 1)
>>> data.dtype
dtype([('shotnum', '<u4'), ('signal', '<f4', (100,)), 
      ('xyz', '<f4', (3,))])
>>>
>>> # display shot numbers
>>> data['shotnum']
array([  1,  2, ..., 98, 99], dtype=uint32)
>>>
>>> # show 'signal' values for shot number 1
>>> data['signal'][0]
array([-0.41381955, -0.4134333 , -0.4118886 , ..., -0.41127062,
       -0.4105754 , -0.41119337], dtype=float32)
>>>
>>> # show 'xyz' values for shot number 1
>>> data['xyz'][0]
array([nan, nan, nan], dtype=float32)
>>>
>>> # read digitizer data while adding '6K Compumotor' data
>>> # from receptacle (configuration) 3
>>> data = HDFReadData(f, 1, 1, 
                       add_controls=[('6K Compumotor', 3)])
>>> data.dtype
dtype([('shotnum', '<u4'), ('signal', '<f4', (100,)), 
       ('xyz', '<f4', (3,)), ('ptip_rot_theta', '<f8'), 
       ('ptip_rot_phi', '<f8')])
>>>
>>> # show 'xyz' values for shot number 1
>>> data['xyz'][0]
array([ -32. ,   15. , 1022.4], dtype=float32)

Attributes Summary

dt

Temporal step size (in sec) calculated from the 'clock rate' and 'sample average' items in info.

dv

Voltage step size (in volts) calculated from the 'bit' and 'voltage offset' items in info.

info

A dictionary of metadata for the extracted data.

plasma

Dictionary of plasma parameters.

Methods Summary

convert_signal([to_volt, to_bits, force])

converts signal from volts (bits) to bits (volts)

set_plasma(Bo, kTe, kTi, m_i, n_e, Z[, gamma])

Set plasma and add key frequency, length, and velocity parameters.

set_plasma_value(key, value)

Re-define one of the base plasma values (Bo, gamma, kT, kTe, kTi, m_i, n, n_e, or Z) in the plasma dictionary.

Attributes Documentation

dt

Temporal step size (in sec) calculated from the 'clock rate' and 'sample average' items in info. Returns None if step size can not be calculated.

dv

Voltage step size (in volts) calculated from the 'bit' and 'voltage offset' items in info. Returns None if step size can not be calculated.

info

A dictionary of metadata for the extracted data. The dict() keys are:

hdf file

str

HDF5 file name the data was retrieved from

dataset name

str

name of the dataset

dataset path

str

path to said dataset in the HDF5 file

digitizer

str

digitizer group name

configuration name

str

name of data configuration

adc

str

analog-digital converter in which the data was recorded on

bit

int

bit resolution for the adc

clock rate

(int, float)

tuple containing clock rate, e.g. (100.0, ‘MHz’)

clock rate

int

(hardware sampling) number of data sample average together

shot average

int

(software averaging) number of shot sequences averaged together

board

int

board that the probe was connected to

channel

int

channel of the board that the probe was connected to

voltage offset

float

voltage offset of the digitized signal

probe name

str

name of deployed probe…empty for user to use at his/her discretion

port

(int, str)

2-element tuple indicating which port the probe was deployed on, eg. (19, ‘W’)
plasma

Dictionary of plasma parameters. (All quantities are in cgs units except temperature is in eV)

Base Values

Bo

magnetic field

kT

temperature (generic)

kTe

electron temperature

kTi

ion temperature

gamma

adiabatic index

m_e

electron mass

m_i

ion mass

n

plasma number density

n_e

electron number density

n_i

ion number density

Z

ion charge number

Calculated Values

fce

electron cyclotron frequency

fci

ion cyclotron frequency

fpe

electron plasma frequency

fpi

ion plasma frequency

fUH

Upper-Hybrid Resonance frequency

lD

Debye Length

lpe

electron-inertial length

lpi

ion-inertial length

rce

electron gyroradius

rci

ion gyroradius

cs

ion sound speed

VA

Alfven speed

vTe

electron thermal velocity

vTi

ion thermal velocity

Methods Documentation

convert_signal(to_volt=False, to_bits=False, force=False)

converts signal from volts (bits) to bits (volts)

set_plasma(Bo, kTe, kTi, m_i, n_e, Z, gamma=None, **kwargs)

Set plasma and add key frequency, length, and velocity parameters. (all quantities in cgs except temperature is in eV)

Parameters:

  • Bo (float) – magnetic field (in Gauss)

  • kTe (float) – electron temperature (in eV)

  • kTi (float) – ion temperature (in eV)

  • m_i (float) – ion mass (in g)

  • n_e (float) – electron number density (in cm^-3)

  • Z (int) – ion charge number

  • gamma (float) – adiabatic index (arb.)

set_plasma_value(key, value)

Re-define one of the base plasma values (Bo, gamma, kT, kTe, kTi, m_i, n, n_e, or Z) in the plasma dictionary.

Parameters:

  • key (str) – one of the base plasma values

  • value – value for key