bidsaid.events.EPrimeBlockExtractor.extract_mean_reaction_times

EPrimeBlockExtractor.extract_mean_reaction_times(reaction_time_column_name, subject_response_column=None, correct_response_column=None, valid_correct_responses=None, response_type='all', response_trial_names=None, response_required_only=False)

Extract mean reaction times for each block.

Computes mean reaction time filtered for correct, incorrect, or all trials.

Parameters

reaction_time_column_namestr

The name of the column containing reaction time values. Usually the column name ending in “.RT” not the column ending in “.RTTime”.

subject_response_columnstr or None, default=None

The name of the column containing the subject’s response. Usually the column name ending in “.RESP”. Required when response_type is “correct” or “incorrect”, or when response_required_only is True.

correct_response_columnstr or None, default=None

The name of the column containing the correct response. For no-go trials, this should be empty/NaN. Required when response_type is “correct” or “incorrect”, or when response_required_only is True.

valid_correct_responsesIterable[str | int | float] or None, default=None

Specific values in the correct_response_column to include in the computation. If provided, only trials where the correct response matches one of these values will be evaluated. This is useful for fixing the denominator to specific target trials (e.g., passing [“1”] to evaluate only Hit Rate, ignoring commission errors on NoGo trials that E-Prime might have encoded as “0”). If None, all non-NaN values are evaluated.

response_typeLiteral["correct", "incorrect", "all"], default=”all”

Whether to compute mean reaction time for correct, incorrect, or all trials.

response_trial_namesIterable[str] or None, default=None

The stimulus trial names within each block to include for the mean reaction time computation.

Important

If split_cue_from_block is True, trial types are excluded from this parameter.

response_required_onlybool, default=False

Compute mean reaction times only for trials that expect a subject response. When True, the script assumes that trials not requiring a response (e.g., NoGo trials) are encoded as NaN in the correct_response_column, and excludes them from the computation. This prevents reaction times from false alarms (commission errors) from skewing the mean reaction time of legitimate trials. Set to False to include all reaction times regardless of whether a response was expected.

Important

This parameter relies strictly on the presence of a non-NaN value in the correct_response_column to determine if a trial expects a response. If the log file explicitly assigns a value (e.g., “0”) to a trial that should not be responded to, the code will treat it as a valid, response-required trial and include it in the reaction time computation. Ensure withhold/NoGo trials are represented as NaN.

Returns

list[float]

A list of mean reaction times for each block. Returns NaN for blocks with no valid reaction times.

Note

Correctness is determined by comparing subject_response_column to correct_response_column:

• A trial is correct if the responses match, OR if both are NaN

(e.g. correct withhold on a no-go trial). - A trial is incorrect if they differ (wrong response, miss, or false alarm).

Trials with NaN reaction times (due to filtering) are excluded via np.nanmean. Also, if cue is split from the block, NaN will be assigned for its reaction time.

Example

>>> # Get mean reaction time for all trials (no accuracy filtering)
>>> mean_reaction_times = extractor.extract_mean_reaction_times(
...     reaction_time_column_name="Stimulus.RT",
... )
>>> # Get mean reaction time for correct Go trials only
>>> mean_reaction_times = extractor.extract_mean_reaction_times(
...     reaction_time_column_name="Stimulus.RT",
...     subject_response_column="Stimulus.RESP",
...     correct_response_column="CorrectResponse",
...     response_type="correct",
...     response_trial_names=("Go",),
... )