`bidsaid.events`.PresentationBlockExtractor

class bidsaid.events.PresentationBlockExtractor(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, 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)[source]

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

trial_column_namestr, default=”Code”

Name of the column containing the trial types.

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.

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” 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.

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.

rest_code_patternLiteral["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

response

3

stim2

4

response

5

Face

6

stim1

…

…

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

0

Face

1

response

2

Face

3

response

…

…

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. If the scanner trigger is identified using scanner_event_type and scanner_trigger_code, then rows preceding the first scanner are dropped and the index is reset.
trial_typeslist[str]: The names of the trial types (i.e., Face, Place).
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_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_codesobj:list[str] or None, default=None: The rest block code(s).
rest_code_patternLiteral["fixed", "variable"], default=”fixed”: Pattern of the rest blocks.
quit_codestr or None: The quit code.
split_cue_from_blockbool: Whether to split cue from block.
unsplit_trial_typesIterable[str]: 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 PresentationBlockExtractor
>>> extractor = PresentationBlockExtractor(
...     log_file,
...     trial_types=("Face", "Place"),
...     scanner_event_type="Pulse",
...     scanner_trigger_code="99",
...     convert_to_seconds=["Time"],
...     rest_block_codes="crosshair",
... )
>>> events = {}
>>> events["onset"] = extractor.extract_onsets()
>>> events["duration"] = extractor.extract_durations()
>>> events["trial_type"] = extractor.extract_trial_types()
>>> # Mean reaction time for all trials with a response
>>> events["mean_rt"] = extractor.extract_mean_reaction_times()
>>> # Mean reaction time for correct trials only
>>> response_map = {"hit": 1, "miss": 0}
>>> events["mean_rt_correct"] = extractor.extract_mean_reaction_times(
...     response_map=response_map,
...     response_type="correct",
... )
>>> # Mean accuracy
>>> events["mean_accuracy"] = extractor.extract_mean_accuracies(response_map=response_map)
>>> df = pd.DataFrame(events)

Methods

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

bidsaid.events.PresentationBlockExtractor

Parameters

Attributes

Example

`bidsaid.events`.PresentationBlockExtractor