TreasureHunt#

class TreasureHunt(filepath=None)[source]#

Bases: object

Compute descriptive statistics from the information-gathering task in BrainExplorer, Treasure Hunt.

On each trial, participants draw samples of evidence until they decide to stop and choose an option, and then rate their confidence in their choice.

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:
datapandas.DataFrame

The trials that pass the trial-level exclusion criteria.

resultspandas.DataFrame

The metrics of each participant, filled by metrics().

cleanedresultspandas.DataFrame

The metrics of the participants 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.

  • date: the date and time of the trial.

  • run: the attempt number of the participant.

  • outcome: the points received on the trial.

  • confidence: the confidence rating.

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

  • draws: the number of draws on the trial.

  • choseCurEv: whether the choice was in line with the current evidence (1) or not (0).

  • median_diffRT: the median response time between the actions of the trial, in ms.

If the data contain a column ev, the evidence after each draw as a list of integers such as "[1 2 -1]", it is converted to lists of integers.

Only the first attempt of each participant (run equal to 1) is kept.

Examples

>>> from cpm.brainexplorer.information_gathering import TreasureHunt
>>> treasure_hunt = TreasureHunt("2025-02-20_TreasureHunt_Data.csv")
>>> results = treasure_hunt.metrics()
>>> cleaned = treasure_hunt.clean_data()
>>> treasure_hunt.get_codebook()["mean_n_draws"]
'Mean number of stimulus draws before making a decision'
metrics()[source]#

Compute the metrics of each participant.

Returns:
pandas.DataFrame

The metrics, one row per participant, also stored in results. The columns are described in codebook.

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 participants that pass the criteria, also stored in cleanedresults.

Notes

A participant is excluded if

  • the mean number of draws is below 2 or above 23,

  • at least 20% of their choices were not in line with the current evidence (an accuracy of 0.8 or below),

  • the number of draws took fewer than 3 different values.

get_codebook()[source]#

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

Returns:
dict

The description of each column, keyed by column name.