Readers

Each class in ptsa.data.readers is constructed with a filename parameter, indicating the file to be read, and implements a read() method, which returns a data structure containing the data in the file.

Note

Keywords must be given explicitly

class ptsa.data.readers.edf.edf.EDFRawReader(**kwargs)

Reads EEG data stored in the European Data Format (EDF/BDF, EDF+/BDF+ formats).

Keyword Arguments:

  • dataroot (str) – Full path to EDF/BDF/EDF+/BDF+ file (including extension).

  • channels (List[Union[str, int]]) – List of channels to read.

read_file(filename, channels, start_offsets=array([0]), read_size=- 1)

Read an EDF/BDF/EDF+/BDF+ file.

Parameters:

  • filename (str) – Path to file to read.

  • channels (Union(List[int],List[str])) – Channel names or numbers to read from. If names, leading If False-like, use all channels.

  • start_offsets (np.ndarray) – Indices to start reading at (not the actual offset times).

  • read_size (int) – Number of samples to read at each offset.

Returns:

A tuple containing the array of EEG data and a boolean index mask indicating whether each offset was read successfully.

Return type:

Tuple[np.ndarray, np.ndarray]

class ptsa.data.readers.BaseEventReader(filename, common_root='data/events', eliminate_events_with_no_eeg=True, eliminate_nans=True, use_reref_eeg=False, normalize_eeg_path=True)

Reader class that reads event file and returns them as np.recarray.

Keyword Arguments:

  • filename (str) – path to event file

  • eliminate_events_with_no_eeg (bool) – flag to automatically remove events with no eegfile (default True)

  • eliminate_nans (bool) – flag to automatically replace nans in the event structs with -999 (default True)

  • use_reref_eeg (bool) – flag that changes eegfiles to point reref eegs. Default is False and eegs read are nonreref ones

  • normalize_eeg_path (bool) – flag that determines if ‘data1’, ‘data2’, etc… in eeg path will get converted to ‘data’. The flag is True by default meaning all ‘data1’, ‘data2’, etc… are converted to ‘data’

  • common_root (str) – partial path to root events folder e.g. if you events are placed in /data/events/RAM_FR1 the path should be ‘data/events’. If your events are placed in the ‘/data/scalp_events/catFR’ the common root should be ‘data/scalp_events’. Note that you do not include opening ‘/’ in the common_root

as_dataframe()

Read events and return as a pd.DataFrame.

Warning

This drops the stim_params field presently as it is not scalar in the current event structure scheme and causes issues when trying to convert to a pd.DataFrame.

find_data_dir_prefix()

determining dir_prefix

data on rhino database is mounted as /data copying rhino /data structure to another directory will cause all files in data have new prefix example: self._filename=’/Users/m/data/events/R1060M_events.mat’ prefix is ‘/Users/m’ we use find_dir_prefix to determine prefix based on common_root in path with and without prefix

Returns:

data directory prefix

modify_eeg_path(events)

Replaces ‘eeg.reref’ with ‘eeg.noreref’ in eegfile path :param events: np.recarray representing events. One of hte field of this array should be eegfile :return:None

normalize_paths(events)

Replaces data1, data2 etc… in the eegfile column of the events with data :param events: np.recarray representing events. One of hte field of this array should be eegfile :return: None

read_matlab()

Reads Matlab event file and returns corresponging np.recarray. Path to the eegfile is changed w.r.t original Matlab code to account for the following: 1. /data dir of the database might have been mounted under different mount point e.g. /Users/m/data 2. use_reref_eeg is set to True in which case we replaces ‘eeg.reref’ with ‘eeg.noreref’ in eegfile path

Returns:

np.recarray representing events

class ptsa.data.readers.CMLEventReader(filename, eeg_fname_search_pattern='', eeg_fname_replace_pattern='', **kwargs)

Event reader that returns original PTSA Events object with attached rawbinwrappers – objects that know how to read eeg binary data

Keyword Arguments:

  • filename (str) – path to event file

  • eliminate_events_with_no_eeg (bool) – flag to automatically remove events with no eegfile (default True)

  • eliminate_nans (bool) – flag to automatically replace nans in the event structs with -999 (default True)

  • eeg_fname_search_pattern (str) – pattern in the eeg filename to search for in order to repalce it with eeg_fname_replace_pattern

  • eeg_fname_replace_pattern (str) – replace pattern for eeg filename. It will replace all occurrences specified by “eeg_fname_replace_pattern”

  • normalize_eeg_path (bool) – flag that determines if ‘data1’, ‘data2’, etc… in eeg path will get converted to ‘data’. The flag is False by default meaning all ‘data1’, ‘data2’, etc… are converted to ‘data’

modify_eeg_path(events)

Replaces search pattern (self.eeg_fname_search_patter’) with replace pattern (self.eeg_fname_replace_pattern) in every eegfile entry in the events recarray

Parameters:

events (np.recarray) – representing events. One of the field of this array should be eegfile

class ptsa.data.readers.EEGReader(events=None, channels=array([], dtype='|S3'), start_time=0.0, end_time=0.0, buffer_time=0.0, session_dataroot='', remove_bad_events=True)

Reader that knows how to read binary eeg files. It can read chunks of the eeg signal based on events input or can read entire session if session_dataroot is non empty.

Keyword Arguments:

  • channels (np.ndarray) – numpy array of channel labels, or a structured array with a ‘channels’ field

  • start_time (float) – read start offset in seconds w.r.t to the eegeffset specified in the events recarray

  • end_time – read end offset in seconds w.r.t to the eegeffset specified in the events recarray

  • buffer_time (float) – extra buffer in seconds (subtracted from start read and added to end read)

  • events (np.recarray) – numpy recarray representing Events

  • session_dataroot (str) – path to session dataroot. When set the reader will read the entire session

  • remove_bad_events (bool) – Remove “bad” events. Defaults to True.

Notes

An EEGReader must be constructed using either :py:arg:events or :py:arg:session_dataroot.

compute_read_offsets(reader)

Reads Parameter file and exracts sampling rate that is used to convert from start_time, end_time, buffer_time (expressed in seconds) to start_offset, end_offset, buffer_offset expressed as integers indicating number of time series data points (not bytes!)

Parameters:

dataroot – core name of the eeg datafile

Returns:

tuple of 3 {int} - start_offset, end_offset, buffer_offset

read_events_data()

Reads eeg data for individual event

Returns:

TimeSeries object (channels x events x time) with data for individual events

read_session_data()

Reads entire session worth of data

Returns:

TimeSeries object (channels x events x time) with data for entire session the events dimension has length 1

class ptsa.data.readers.TalReader(filename, struct_name='bpTalStruct', struct_type='bi', unpack=True)

Reader that reads tal structs Matlab file or pairs.json file and converts it to numpy recarray

from_dict(json_dict, unpack=True)

Reads a JSON localization file into a record array. :param json_dict: A dictionary of localization information, with one entry for each contact or pair. :return:

classmethod from_records(contact_dict)

Helper method for :meth:from_dict. Takes a list of records (dictionaries with semi-consistent fields) and returns a structured array whose fields are the keys of each record. Nested records are handled by recursion.

Missing entries should be represented by either None, NaN, or an empty dictionary.

Parameters:

contact_dict – {List[Union(Dict,None,NaN)]}

Returns:

{np.array} A structured array with the same indexing structure as :arg:contact_dict

get_bipolar_pairs()
Returns:

numpy recarray where each record has two fields ‘ch0’ and ‘ch1’ storing channel labels.

get_monopolar_channels()
Returns:

numpy array of monopolar channel labels

classmethod mkdtype(flat_df)

Invariant: there are no subfields of flat_df whose elements are dictionaries :param flat_df: {pandas.DataFrame} :return: {np.dtype}

class ptsa.data.readers.LocReader(filename)

Reads a localization file (“localization.json”) and returns the data it contains as a flat DataFrame. Nested fields in the JSON file have their full paths joined by periods. The returned DataFrame is indexed by tyep type of entry (‘contacts’ or ‘pairs’) and by the name of the entry (either the name of the contact, or a tuple with the names of each half of the pair).