bidsaid.events.PresentationEventExtractor

class bidsaid.events.PresentationEventExtractor(log_or_df, trial_types, scanner_event_type, scanner_trigger_code, trial_column_name='Code', convert_to_seconds=None, initial_column_headers=('Trial', 'Event Type'), n_discarded_volumes=0, tr=None)

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

Parameters

log_or_dfstr, Path, pandas.DataFrame

The Presentation log as a file path or the Presentation DataFrame returned by bidsaid.parsers.load_presentation_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

If your block design does not include a rest block or crosshair code, include the code immediately after the final block.

scanner_event_typestr

The event type in the “Event Type” column the scanner trigger is listed under (e.g., “Pulse”, “Response”, “Picture”, etc).

scanner_trigger_codestr

Code listed under “Code” for the scanner start (e.g., “54”, “99”, “trigger). Used with scanner_event_type to compute the onset times of the trials relative to the scanner start time then clip the dataframe to ensure that no trials before the start of the scanner is initiated.

Note

Uses the first index of the rows in the dataframe with values provided for scanner_event_type and scanner_trigger_code.

trial_column_namestr, default=”Code”

Name of the column containing the trial types.

convert_to_secondslist[str] or None, default=None

Convert the time resolution of the specified columns from 0.1 ms to seconds. See Presentation Timing.

Important

Recommend time resolution of the “Time” column and “Duration” column to be converted.

initial_column_headersIterable[str], default=(“Trial”, “Event Type”)

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 ten thousand seconds if not converted.

Attributes

dfpandas.DataFrame

DataFrame containing the log data. If the scanner trigger is identified using scanner_event_type and scanner_trigger_code, then rows preceeding the first scanner are dropped and the index is reset.

trial_typeslist[str]

The names of the trial types.

scanner_event_typestr

Event type of scanner trigger.

scanner_trigger_codestr

Code for the scanner trigger.

trial_column_namestr

Name of column containing the trial types.

n_discarded_scansint

Number of non-steady state scans discarded by scanner.

trfloat, int, or None

The repetition time.

scanner_start_time float 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 PresentationEventExtractor
>>> extractor = PresentationEventExtractor(
...     log_file,
...     trial_types=("congruentleft", "congruentright", "incongruentleft", "incongruentright", "nogo"),
...     scanner_event_type="Pulse",
...     scanner_trigger_code="99",
...     convert_to_seconds=["Time"],
... )
>>> events = {}
>>> events["onset"] = extractor.extract_onsets()
>>> events["duration"] = extractor.extract_durations()
>>> events["trial_type"] = extractor.extract_trial_types()
>>> events["reaction_time"] = extractor.extract_reaction_times()
>>> events["response"] = extractor.extract_responses()
>>> events["accuracy"] = extractor.extract_responses(response_map={"hit": 1, "miss": 0})
>>> df = pd.DataFrame(events)

Methods

extract_accuracies(response_map)	Extract the accuracy (correct or incorrect) for each event.
extract_durations()	Extract the duration for each event.
extract_onsets([scanner_start_time])	Extract the onset times for each event.
extract_reaction_times()	Extract the reaction time for each event.
extract_responses()	Extract the response for each event.
extract_trial_types()	Extract the trial type for each event.