SpaceObserver#

class SpaceObserver(filepath=None)[source]#

Bases: object

Compute descriptive statistics from the perceptual decision-making task with confidence judgements in BrainExplorer, Space Observer.

On each trial, participants decide which of two types of alien is more numerous, and rate their confidence in their choice. For a more complete description of the task, see Dome, Moses-Payne, and Hauser (in prep.) or Marzuki et al. (2025).

Parameters:
filepathstr, os.PathLike or pandas.DataFrame

The data, as a DataFrame or the path to a CSV file. The column names must follow the convention in Notes.

Attributes:
data_rawpandas.DataFrame

The trials that pass the trial-level exclusion criteria.

data_processedpandas.DataFrame

The metrics of each session, one row per participant and session, filled by metrics().

cleanedresultspandas.DataFrame

The metrics of the sessions that pass the participant-level exclusion criteria, filled by clean_data().

deleted_participantsint

The number of participants that clean_data() excluded.

codebookdict

The description of each column of the metrics.

Notes

The data must contain the following columns:

  • userID: the unique identifier of the participant.

  • run: the session number of the participant.

  • Date: the date and time of the trial.

  • accuracy: whether the choice was correct (1) or incorrect (0).

  • RT_choice: the response time of the choice, in ms.

  • confidence: the confidence rating.

  • confidenceRT: the response time of the confidence rating, in ms.

  • stimulus_intensity: the evidence strength, the difference in evidence between the two types of stimuli.

Trials are excluded if the response time of the choice or of the confidence rating is below 150 ms or above 10000 ms, or if they have no confidence rating, since those are practice trials. For participant-level exclusions, see clean_data(), and Dome, Moses-Payne, and Hauser (in prep.).

References

Dome, L., Moses-Payne, M. E., & Hauser, T. U. (in prep.). Age-related shifts in metacognition reveals converging confidence for correct and error judgments across the lifespan.

Marzuki, A., Kosina, L., Dome, L., Hewitt, S., & Hauser, T. (2025). Metacognitive antecedents to states of mental ill-health: Drops in confidence precede symptoms of OCD. Research Square. https://doi.org/10.21203/rs.3.rs-7544256/v1

Examples

>>> from cpm.brainexplorer.perceptual_decision_making import SpaceObserver
>>> observer = SpaceObserver("2025-02-20_SpaceObserver_Data.csv")
>>> results = observer.metrics()
>>> cleaned = observer.clean_data()
>>> observer.get_codebook()["accuracy"]
'Mean accuracy across all trials (proportion correct)'
metrics()[source]#

Compute the metrics of each session of each participant.

Returns:
pandas.DataFrame

The metrics, one row per participant and session, also stored in data_processed. The columns are described in codebook.

Notes

Correct trials are those with an accuracy of 1, and incorrect trials those with an accuracy of 0. Metrics of an empty selection, such as the median response time of incorrect trials when every choice was correct, are NaN. The evidence strength bins split the trials of a session, in the order they were played, into four parts of (nearly) equal size.

clean_data()[source]#

Exclude participants with the participant-level exclusion criteria.

Runs metrics() first if it has not been run yet.

Returns:
pandas.DataFrame

The metrics of the sessions that pass the criteria, also stored in cleanedresults.

Notes

A session is excluded if

  • the mean accuracy is below 0.5,

  • the median response time of the choices is above 3000 ms,

  • the median response time of the confidence ratings is above 3000 ms,

  • the median evidence strength is above 25,

  • the median confidence is below 3 or above 97,

  • the 10th and 25th percentiles of confidence are equal, and so are the 75th and 90th percentiles.

Participants with more than 80 trials in total, across all their sessions, are excluded entirely (due to a technical error).

get_codebook()[source]#

Return the codebook, which describes each column of the metrics.

Returns:
dict

The description of each column, keyed by column name.