Phys

The Phys class works with physiological data such as heart rate and blood pressure. It inherits from the _TsData class similarly to the Ephys class so the same methods will work on both classes. The Phys class reads data from ADInstruments technology. Before attempting to read this data, export the raw .adicht file to a .mat file using software such as LabChart. More information about exporting files can be found on the ADInstruments website at https://www.adinstruments.com/

Phys objects can be instantiated with a path name to a file similarly to Ephys objects. Phys objects also have the option to read one file into multiple data sets. Set mult_data to True in order to read in one file into multiple data sets. The data sets are automatically split up by ‘blocks’ in the recording.

class pyeCAP.phys.Phys(data, *args, mult_data=True, check=True, order=True, **kwargs)

Class for physiological data

__init__(data, *args, mult_data=True, check=True, order=True, **kwargs)

Constructor for the Phys class

Parameters

  • data (str, list) – Path name or list of path names to .mat files.

  • args (*) – See _TsData (parent class) constructor.

  • mult_data (bool) – Set to True to treat each block as a separate data set, false to treat each all blocks as one data set.

  • check (bool) – Set to True to allow warnings about improperly formatted files.

  • order (bool) – Set to True to order data sets by start time. Since data from the same file is read in chronological order, this will only have an effect when reading in data from multiple files.

  • kwargs (**) – See _TsData (parent class) constructor

Examples

>>> pyeCAP.Phys(pathname1)   # replace pathnames with paths to data      

>>> pyeCAP.Phys([pathname1, pathname2, pathname3])
property units

Property getter method for channel units.

Returns

List of dictionaries linking channel name to units for each data set.

Return type

list

Examples

>>> phys_data.units

Parent class

The Parent class of the Phys class is the _TsData class. The majority of methods available to Phys objects are inherited from this class.

Reading data with the Phys class

The primary method of reading data with the Phys class is through ADInstruments binary files (.adibin). This method is preferred because the Phys class does not load the binary data into memory until a computation is performed. Pre-processing of raw data is necessary to transform files into this format. Software such as LabChart https://www.adinstruments.com/support/software will export raw .adicht files into a variety of formats. To create an ADInstruments binary file, open LabChart and open the raw data file. Click on the ‘File’ dropdown in the upper left corner and select export. Select ADInstruments binary file. A menu will pop up with options of how to export the file. Ensure that the data type is a 32 of 64 bit floating point, the “time” box is not selected, and the “header” box is selected. If these options are not chosen, the Phys class will not be able to read the resulting binary file properly.

The Phys class also reads data from non-hdf5 MatLab (.mat) files that are under 4GB. To create the MatLab file, use LabChart to export the data similarly to a binary file. Select the “MATLAB” option when choosing the file type. Choose the desired channels and make sure the ‘upsample to same rate’ option is selected. This will ensure a consistent sample rate by interpolating data points. pyeCAP currently does not support data with different sampling rates between blocks or channels.

More information about how Labchart exports this data can be found here: https://www.adinstruments.com/support/knowledge-base/how-does-matlab-open-exported-data

Automatic Warnings

When reading .mat files, pyeCAP can generate warnings that will catch data that is improperly formatted or not implemented. To enable these warnings, set the ‘check’ parameter to True when instantiating a new Phys object. This parameter is only intended to generate warnings by reading data directly from files. This will not check data when data and metadata are manually inputted into a Phys object. The constructor calls the check_data function documented below. The current warnings are shown below:

  • Array formatted improperly: This warning is generated if data is not exported to the matlab file correctly and the arrays have incorrect dimensions.

  • NaN values in data: This warning is generated if there are NaN values in the data. This may cause problems when plotting data. Ensure that y limits are specified manually.

  • Inconsistent sample rates: This warning is generated when the data has inconsistent sample rates. Reading this data is not yet implemented.

  • Inconsistent units: This warning is generated when a channel has more than one unit across the experiment.

  • Offset in data blocks: Warns about offsets in the start time of each channel. See the ‘firstsampleoffset’ array at https://www.adinstruments.com/support/knowledge-base/how-does-matlab-open-exported-data for more information.

  • Channel data does not align into a rectangular array: Some or all data for a channel may be missing. This will cause eba toolkit to crash when performing computations on the data. To avoid this error, avoid exporting channels with missing data. If this is not possible, see the pad_array function in the Phys class.

For binary files, the Phys class will not generate warnings because the data is not loaded into memory when it is read in. Instead, the Phys class will generate errors for improperly formatted binary files. Errors may occur from exporting the file with integer data instead of float data, including the time array in exporting, or not including file headers.

Functions for reading in data

The following functions can be used to read in MATLAB data at a lower level.

pyeCAP.io.adinstruments_io.check_data(raw_data)

Warns user of potential errors in reading in the data.

Parameters

raw_data (dict) – Python dictionary with keys corresponding to matlab variables and numpy data arrays as values.

Returns

Return type

None

pyeCAP.io.adinstruments_io.to_array(raw_array, index_start_array, index_end_array, mult_data)

Creates a properly formatted dask array to insert into the Phys or _TsData constructor.

Parameters

  • raw_array (numpy.ndarray) – Array of all raw data points. (‘data’)

  • index_start_array (numpy.ndarray) – Array of matlab start indices for each channel and block combination. (‘datastart’)

  • index_end_array (numpy.ndarray) – Array of matlab end indices for each channel and block combination. (‘dataend’)

  • mult_data (bool) – Indicator of whether or not to treat the file as one data set or multiple.

Returns

Raw data formatted into an array.

Return type

dask.array.core.Array

pyeCAP.io.adinstruments_io.to_meta(start_indices, end_indices, tick, channels, units, units_map, start_times, mult_data)

Generates metadata for a Phys object.

Parameters

  • start_indices (numpy.ndarray) – Array of matlab start indices for each channel and block combination. (‘datastart’)

  • end_indices (numpy.ndarray) – Array of matlab end indices for each channel and block combination. (‘dataend’)

  • tick (numpy.ndarray) – Array of highest sample rates for each block. (‘tickrate’)

  • channels (numpy.ndarray) – Array of channel names. (‘titles’)

  • units (numpy.ndarray) – Array of channel units. (‘unittext’)

  • units_map (numpy.ndarray) – Array of indices linking units to channel and block. (‘unittextmap’)

  • start_times (numpy.ndarray) – Array of start times for each block (matlab datetime format). (‘blocktimes’)

  • mult_data (bool) – Indicator of whether or not to treat the file as one data set or multiple.

Returns

Metadata dictionaries for each data set.

Return type

list

Comment reading

The following function can be used to read the comments from a file and record the timestamp, channel, and name of each comment.

pyeCAP.phys.get_comments(file, comtype=None)

Reads the comments in the specified file path. Creates a dictionary with keys as channel names. Values are dictionaries with comment names as key names and arrays of timestamps as values.

Parameters

  • file (str) – Path of a .mat file.

  • comtype (None, str) – Use None to default to any comment type. Specify ‘user’, ‘event’, or ‘both’.

Returns

Python dictionary. Index with channel name and comment name.

Return type

dict

Examples

>>> pyeCAP.phys.get_comments(pathname)    # insert pathname to data