bidsaid.events.EPrimeBlockExtractor.extract_mean_accuracies

EPrimeBlockExtractor.extract_mean_accuracies(subject_response_column, correct_response_column, valid_correct_responses=None, response_trial_names=None, response_required_only=False)

Extract mean accuracy for each block.

Computes accuracy by comparing the subject’s response to the correct response for each trial.

Parameters

subject_response_columnstr

The name of the column containing the subject’s response. Usually the column name ending in “.RESP”.

correct_response_columnstr

The name of the column containing the correct response. Trials where the subject should not respond should be NaN. Usually column name ending in “.CRESP”.

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_trial_namesIterable[str] or None, default=None

The stimulus trial names within each block to include for the accuracy computation.

Important

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

response_required_onlybool, default=False

Compute mean accuracy 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 overall accuracy scores from being artificially inflated by correct withholds. Set to False to include all trials 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 script will treat it as a valid, response-required trial and include it in the accuracy computation. Ensure withhold/NoGo trials are represented as NaN.

Returns

list[float]

A list of mean accuracies for each block.

Notes

Correctness is determined by comparing subject_response_column to correct_response_column using the following logic:

Subject Response	Correct Response	Interpretation	Accuracy
“1”	“1”	Correct response	1
NaN	NaN	Correct response	1
NaN	“1”	Incorrect response	0
“1”	NaN	Incorrect response	0
“2”	“3”	Incorrect response	0

Note: If response_required_only is True, only accuracy for the first, third, and fifth row are computed since those are trials that expect a response.

Also, if cue is split from the block, NaN will be assigned for its accuracy.

Example

>>> # Get mean accuracy for all trial types
>>> mean_accuracies = extractor.extract_mean_accuracies(
...     subject_response_column="Stimulus.RESP",
...     correct_response_column="CorrectResponse"
... )
>>> # Get mean accuracy for specific trial types only
>>> mean_accuracies = extractor.extract_mean_accuracies(
...     subject_response_column="Stimulus.RESP",
...     correct_response_column="CorrectResponse",
...     response_trial_names=("Go", "NoGo")
... )

Note

Mean accuracy for cue rows will be NaN.