bidsaid.events.EPrimeEventExtractor

class bidsaid.events.EPrimeEventExtractor(log_or_df, trial_types, onset_column_name, procedure_column_name, trigger_column_name=None, convert_to_seconds=None, initial_column_headers=('ExperimentName', 'Subject'), n_discarded_volumes=0, tr=None)[source]

Extract onsets, durations, trial types, reaction times, and responses from E-Prime logs using an event design.

Parameters

log_or_dfstr, Path, pandas.DataFrame

The E-Prime log as a file path or the E-Prime DataFrame returned by bidsaid.parsers.load_eprime_log.

Important

If a text file is used, data are assumed to have at least one element that is an digit or float during parsing.

trial_typesIterable[str]

The names of the trial types (i.e “congruentleft”, “seen”). Regex can be used.

Note

Depending on the way your E-Prime data is structured, for block design the rest block may have to be included as a “trial_type” to compute the correct duration. These rows can then be dropped from the events DataFrame.

onset_column_namestr

The name of the column containing stimulus onset time.

procedure_column_namestr

The name of the column containing the procedure names.

trigger_column_namestr or None, default=None

The name of the column containing the scanner start time. Uses the first value that is not NaN as the scanner start time. If None, the scanner start time will need to be given when using self.extract_onsets.

convert_to_secondslist[str] or None, default=None

Convert the time resolution of the specified columns from milliseconds to seconds. See EPrime Timing.

Important

Recommend time resolution of the columns containing the onset times, offset times (duration), reaction times, and scanner onset time (trigger_column_name) be converted to seconds.

initial_column_headersIterable[str], default=(“ExperimentName”, “Subject”)

The initial column headers for data. Only used when log_or_df is a file path.

n_discarded_volumesint, default=0

Number of non-steady state scans discarded by the scanner at the start of the sequence.

Important

  • Only used when trigger_column_name is specified.

  • Only set this parameter if scanner trigger is sent before these volumes are acquired so that the start time of the first retained volume is shifted forward by (n_discarded_volumes * tr). If the scanner sends trigger after discarding the volumes, do not set this parameter. Explanation from Neurostars.

trfloat, int, or None, default=None

The repetition time provided in seconds if data was converted to seconds or in milliseconds if not converted.

Attributes

dfpandas.DataFrame

DataFrame containing the log data.

trial_typesIterable[str]

The names of the trial types.

onset_column_namestr

Name of column containing the onset time.

procedure_column_namestr

Name of column containing the trial types.

trigger_column_namestr or None

Name of column containing time when scanner sent pulse/scanner start time.

n_discarded_scansint

Number of non-steady state scans discarded by scanner.

trfloat, int, or None

The repetition time.

scanner_start_timefloat or None

Time when scanner sends the pulse. If n_discarded_volumes is not 0 and tr is specified, then this time will be shifted forward (scanner_start_time = scanner_start_time + n_discarded_volumes * tr) to reflect the time when the first steady state volume was retained. Otherwise, the time extracted from the log data is assumed to be the time when the first steady state volume was retained.

event_trial_indiceslist[int]

The indices of when each trial event of interest (specified by trial_types) begins.

Example

>>> import pandas as pd
>>> from bidsaid.events import EPrimeEventExtractor
>>> extractor = EPrimeEventExtractor(
...     log_file,
...     trial_types=("Go", "NoGo"),
...     onset_column_name="Stimulus.OnsetTime",
...     procedure_column_name="Procedure",
...     trigger_column_name="ScannerTrigger.RTTime",
...     convert_to_seconds=[
...         "Stimulus.OnsetTime",
...         "Stimulus.OffsetTime",
...         "Stimulus.RT",
...         "ScannerTrigger.RTTime"
...     ],
... )
>>> events = {}
>>> events["onset"] = extractor.extract_onsets()
>>> events["duration"] = extractor.extract_durations(offset_column_name="Stimulus.OffsetTime")
>>> events["trial_type"] = extractor.extract_trial_types()
>>> events["reaction_time"] = extractor.extract_reaction_times(reaction_time_column_name="Stimulus.RT")
>>> events["accuracy"] = extractor.extract_accuracies(
...     subject_response_column="Stimulus.RESP",
...     correct_response_column="CorrectResponse",
... )
>>> df = pd.DataFrame(events)

Methods

extract_accuracies(subject_response_column, ...)

Extract the accuracy (correct or incorrect) for each event.

extract_durations(offset_column_name)

Extract the duration for each event.

extract_onsets([scanner_start_time])

Extract the onset times for each event.

extract_reaction_times(reaction_time_column_name)

Extract the reaction time for each event.

extract_trial_types()

Extract the trial type for each event.