bidsaid.events.EPrimeBlockExtractor

class bidsaid.events.EPrimeBlockExtractor(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, rest_block_codes=None, rest_code_pattern='fixed', quit_code=None, split_cue_from_block=False, unsplit_trial_types=None, cue_suffix='_cue', drop_cue_rows=False)

Extract onsets, durations, and trial types from E-Prime logs using a block 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., “Face”, “Place”). Serves to identify the boundaries of a trial type of interest. Regex can be used.

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 time, offset time (duration), reaction time, and scanner start 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.

rest_block_codesstr, Iterable[str], or None, default=None

The code name(s) for the rest block(s). Used when a resting state block is between the events to compute the correct block duration. If None, the block duration will be computed based on the starting index of the trial types given by trial_types. If specified and rest_code_pattern is “variable”, will be used with trial_types to compute the correct duration. Regex can be used.

Literal["fixed", "variable"], default=”fixed”

Pattern of the rest blocks. For “fixed”, the rest code is assumed to appear between each block. For “variable”, it is assumed that the rest code(s) inconsistently appears after each block.

quit_codestr or None, default=None

The quit code. Suggest to use in cases when a quit code, as opposed to a rest code, is preceded by a trial block. Ideally, this should be a unique code.

split_cue_from_blockbool, default=False

Whether to split cue from block. If True, the row index containing the trial type name will have a separate onset and duration time. In addition, only the row indices proceeding the row index of the cue row will be used for computing the mean reaction time and accuracy for a block.

Important

Use this when your log structure has the following stucture, where trial_types are followed by their first stimulus:

Row	Code
0	Face
1	stim1
2	stim2
3	Face
4	stim1
…	…

Do not use this when every row in the block shares the same code:

0	Face
1	Face
2	Face
…	…

unsplit_trial_typesIterable[str] or None, default=None

Block cue names that should not have their cue split from the block. Only used when split_cue_from_block is True. Blocks specified here will always start at the cue row.

cue_suffixstr, default=”_cue”

Suffix for cue trial type names.

drop_cue_rowsbool, defaut=False

Whether to drop cue rows from the output.

Attributes

dfpandas.DataFrame

DataFrame containing the log data.

trial_typeslist[str]

The names of the blocks.

onset_column_namestr

Name of column containing the onset time.

procedure_column_namestr

Name of column containing the procedure names.

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.

starting_block_indiceslist[int]

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

rest_block_codeslist[str] or None

The rest block code(s).

rest_code_patternLiteral["fixed", "variable"]

Pattern of the rest blocks.

quit_codestr or None

The quit code.

split_cue_from_blockbool

Whether to split cue from block. Will compute timing information from the row index immediately following the cue row.

unsplit_trial_typesIterable[str] or None

Names of the blocks that should not have their cue split from the block. Regex can be used.

cue_suffixstr

Suffix for cue trial type names.

drop_cue_rowsbool

Whether to drop cue rows from the output.

Example

>>> import pandas as pd
>>> from bidsaid.events import EPrimeBlockExtractor
>>> extractor = EPrimeBlockExtractor(
...     log_file,
...     trial_types=("Face", "Place"),
...     onset_column_name="Stimulus.OnsetTime",
...     procedure_column_name="Procedure",
...     trigger_column_name="ScannerTrigger.RTTime",
...     convert_to_seconds=["Stimulus.OnsetTime", "ScannerTrigger.RTTime", "Stimulus.RT"],
...     rest_block_codes="Rest",
... )
>>> events = {}
>>> events["onset"] = extractor.extract_onsets()
>>> events["duration"] = extractor.extract_durations(offset_column_name="Stimulus.OffsetTime")
>>> events["trial_type"] = extractor.extract_trial_types()
>>> # Mean reaction time for correct Face trials only
>>> events["mean_rt"] = extractor.extract_mean_reaction_times(
...     reaction_time_column_name="Stimulus.RT",
...     subject_response_column="Stimulus.RESP",
...     correct_response_column="Simulus.CRESP",
...     response_type="correct",
...     response_trial_names=("Face")
... )
>>> # Mean accuracy across all trial types
>>> events["mean_accuracy"] = extractor.extract_mean_accuracies(
...     subject_response_column="Stimulus.RESP",
...     correct_response_column="Stimulus.CRESP",
... )
>>> df = pd.DataFrame(events)

Methods

extract_durations([offset_column_name])	Extract the duration for each block.
extract_mean_accuracies(...[, ...])	Extract mean accuracy for each block.
extract_mean_reaction_times(...[, ...])	Extract mean reaction times for each block.
extract_onsets([scanner_start_time])	Extract the onset times for each block.
extract_response_counts(...[, ...])	Extract the number of trials with a response for each block.
extract_trial_types()	Extract the trial type for each block.