API Documentation¶

Here we list the Application-Programming Interface (API) for pd-parser.

pd-parser¶

pd_parser:

Find photodiode events.

Take a potentially corrupted photodiode channel and find the event time samples at which it turned on.

add_events_to_raw(raw, keep_pd_channels=False, verbose=True)[source]¶

Save out a new raw file with photodiode events.

Note: this function is not recommended, rather just skip it and use save_to_bids which doesn’t modify the underlying raw data especially converting it to fif if it isn’t fif already. In save_to_bids the raw file itself doens’t contain the event information, it’s only stored in the sidecar.

Parameters:

raw: str | mne Raw object: The object or filepath of the time-series data file (e.g. meg, eeg, ieeg).
keep_pd_channelsbool: Whether to keep the channel(s) the photodiode data was on.
verbose: bool: Whether to display or supress text output on the progress of the function.

Returns:

rawmne.io.Raw: The modified raw object with events.

add_pd_off_events(raw, off_event_name='Stim Off', max_len=1.0, zscore=10, max_flip_i=40, baseline=0.25, verbose=True, overwrite=False)[source]¶

Add events for when the photodiode deflection returns to baseline.

Parameters:

raw: str | mne Raw object: The object or filepath of the time-series data file (e.g. meg, eeg, ieeg).
off_eventstr: If None, no event will be assigned to cessation of the photodiode deflection. If a string is provided, an event of that name will be assigned to the cessation of the deflection.
max_len: float: The maximum length of the photodiode events.
zscore: float: How large of a z-score difference to use to threshold photodiode events.
max_flip_i: int: The maximum number of samples the photodiode event may take to transition.
baseline: float: How much relative to max_len to use to idenify the time before the photodiode event.
verbosebool: Whether to display or supress text output on the progress of the function.
overwritebool: Whether to overwrite existing data if it exists.

Returns:

annot: mne.Annotations: The annotations with the added events.

Note

The same parameters must be used for pd_parser.parse_pd().

add_relative_events(raw, beh, relative_event_keys, relative_event_names=None, overwrite=False, verbose=True)[source]¶

Add events relative to those determined from the photodiode.

Parameters:

raw: str | mne Raw object: The object or filepath of the time-series data file (e.g. meg, eeg, ieeg).
beh: str | dict: The dictionary or filepath to a tsv file with the behavioral timing.
relative_event_keyslist: The names of the keys where time data is stored relative to the photodiode event
relative_event_nameslist: The names of the events in relative_event_keys.
verbose: bool: Whether to display or supress text output on the progress of the function.
overwrite: bool: Whether to overwrite existing data if it exists.

Returns:

annot: mne.Annotations: The annotations with the added events.

find_pd_params(raw, pd_ch_names=None, verbose=True)[source]¶

Plot the data so the user can determine the right parameters.

The user can adjust window size to determine max_len and horizontal line height to determine zscore.

Parameters:

raw: str | mne Raw object: The object or filepath of the time-series data file (e.g. meg, eeg, ieeg).
pd_ch_nameslist: Names of the channel(s) containing the photodiode data. One channel is to be given for a common reference and two for a bipolar reference. If no channels are provided, the data will be plotted and the user will provide them.
verbosebool: Whether to display or supress text output on the progress of the function.

parse_audio(raw, audio_event_name='Tone', beh=None, beh_key='tone_onset_time', audio_ch_names=None, exclude_shift=0.03, resync=0.075, max_len=0.25, zscore=None, add_events=False, recover=False, overwrite=False, verbose=True)[source]¶

Parse audio events.

Parses photodiode events from a likely very corrupted channel using behavioral data to sync events to determine which behavioral events don’t have a match and are thus corrupted and should be excluded (while ignoring events that look like photodiode events but don’t match behavior)

Parameters:

raw: str | mne Raw object: The object or filepath of the time-series data file (e.g. meg, eeg, ieeg).
audio_event_name: str: The name of the event corresponding to the audio.
beh: str | dict: The dictionary or filepath to a tsv file with the behavioral timing.
beh_key: str: The key (column name) of the beh dictionary that corresponds to the events.
audio_ch_names: list: Names of the channel(s) containing the audio data. One channel is to be given for a common reference and two for a bipolar reference. If no channels are provided, the data will be plotted and the user will provide them.
exclude_shift: float: How many seconds different than expected from the behavior events to exclude that event.
resync: float: The number of seconds to difference allowed to still use an audio event event to resynchronize with time-stamped events. See pd_parser.parse_pd() for more information.
max_len: float: The longest audio event can be.
zscore: float: How large of a z-score difference to use to threshold the correlation of the audio with the sound. If None is passed a plot will be shown to pick a reasonable zscore. 25 is a typical value that works.
add_events: bool: Whether to add the events found from the current call of parse_pd to a events found previously (e.g. first parse with pd_event_name=’Fixation’ and then parse with pd_event_name=’Response’. Note: pd_parser.add_relative_events will be relative to the first event added.
recover: bool: Whether to recover corrupted events manually.
verbose: bool: Whether to display or supress text output on the progress of the function.
overwrite: bool: Whether to overwrite existing data if it exists.

Returns:

annot: mne.Annotations: The annotations with the added events.
samples: list: The samples corresponding to the events, with ‘n/a’ if no event is found.

parse_pd(raw, pd_event_name='Fixation', beh=None, beh_key='fix_onset_time', pd_ch_names=None, exclude_shift=0.03, resync=0.075, max_len=1.0, zscore=10, max_flip_i=40, baseline=0.25, add_events=False, recover=False, overwrite=False, verbose=True)[source]¶

Parse photodiode events.

Parameters:

raw: str | mne Raw object: The object or filepath of the time-series data file (e.g. meg, eeg, ieeg).
pd_event_name: str: The name of the event corresponding to the photodiode.
beh: str | dict: The dictionary or filepath to a tsv file with the behavioral timing.
beh_key: str: The key (column name) of the beh dictionary that corresponds to the events.
pd_ch_nameslist: Names of the channel(s) containing the photodiode data. One channel is to be given for a common reference and two for a bipolar reference. If no channels are provided, the data will be plotted and the user will provide them.
exclude_shift: float: How many seconds different than expected from the behavior events to exclude that event. Use find_pd_params to determine if unsure.
resync: float: The number of seconds to difference allowed to still use a photodiode event to resynchronize with time-stamped events. Events with differences between resync and exclude_shift will still be used for alignment but will be excluded from the events. When exclude_shift is smaller than resync, this parameter allows event differences less than exclude_shift to be removed without losing an alignment which depends on resynchronizing to these events between exclude_shift and resync. This is most likely to happen when the drift between behavior events and the photodiode is large, so many events are to be excluded for being off by a small amount but still correctly correspond to a behavior event.
max_len: float: The longest photodiode event can be.
zscore: float: How large of a z-score difference to use to threshold photodiode events. Note, the must be large enough that any overshoot when returning to threshold is less than zscore compared to baseline.
max_flip_i: int: The maximum number of samples the photodiode event can take to transition. This shouldn’t usually need to be changed unless the transition takes longer.
baseline: float: How much relative to the max_len to use to idenify the time before the photodiode event. This should not be changed most likely unless there is a specific reason/issue.
add_events: bool: Whether to add the events found from the current call of parse_pd to a events found previously (e.g. first parse with pd_event_name=’Fixation’ and then parse with pd_event_name=’Response’. Note: pd_parser.add_relative_events will be relative to the first event added.
recover: bool: Whether to recover corrupted events manually.
verbose: bool: Whether to display or supress text output on the progress of the function.
overwrite: bool: Whether to overwrite existing data if it exists.

Returns:

annot: mne.Annotations: The annotations with the added events.
samples: list: The samples corresponding to the events, with ‘n/a’ if no event is found.

save_to_bids(bids_dir, raw, sub, task, ses=None, run=None, data_type=None, eogs=None, ecgs=None, emgs=None, verbose=True, overwrite=False)[source]¶

Convert data to BIDS format with events found from the photodiode.

Parameters:

bids_dir: str: The subject directory in the bids directory where the data should be saved.
raw: str | mne Raw object: The object or filepath of the time-series data file (e.g. meg, eeg, ieeg).
sub: str: The name of the subject.
task: str: The name of the task.
ses: str: The name of the session (optional).
run: str: The name of the run (optional).
data_type: str: The type of the channels containing data, i.e. ‘eeg’ or ‘seeg’.
eogs: list | None: The channels recording eye electrophysiology.
ecgs: list | None: The channels recording heart electrophysiology.
emgs: list | None: The channels recording muscle electrophysiology.
beh: None | str | dict: The dictionary or filepath to a tsv file with the behavioral timing. If None, the stored data is used.
verbose: bool: Whether to display or supress text output on the progress of the function.
overwrite: bool: Whether to overwrite existing data if it exists.

simulate_pd_data(n_events=10, n_secs_on=1.0, amp=300.0, iti=6.0, iti_jitter=1.5, rc_decay=0.0001, prop_corrupted=0.1, sfreq=1000.0, seed=11, show=False)[source]¶

Simulate photodiode data.

Simulate data that is a square wave with a linear change in deflection drift amount towards zero that then over shoots and drifts back as photodiodes tend to do. Some events are also corrupted.

Parameters:

n_events: float: The number of events to simulate.
n_secs_on: float | np.array: The number of seconds each event is on. If a float is provided, the time is the same for each event. If an array is provided, it must be the length of the number of events, and it determines the length of each event respectively.
amp: float: The amplitude of the photodiode in standard deviations above baseline.
iti: float: The interval in between events.
iti_jitter: float: The jitter displacing the events from exactly iti distance away from each other.
rc_decay: float: The factor controlling how much the photodiode decays back to baseline over time with no external simulus (0. == perfect square wave).
sfreq: float: The sampling frequency of the data.
show: bool: Whether to plot the data.

Returns:

raw: mne.io.Raw

The raw object containing the photodiode data

beh: dict

A dictionary with keys (columns names):

trialint
The index of the event.

timefloat
The time that both the corrupted and uncorrupted events occurred in seconds.

events: np.array

The uncorrupted events where the first column is the time stamp, the second column is unused (zero) and the third column is the event identifier.

corrupted_indices: np.array

The indices of the events which were corrupted in the simulation.