Scavenger#

class Scavenger(filepath=None)[source]#

Bases: object

Compute descriptive statistics from the risky decision-making task in BrainExplorer, Scavenger.

On each trial, participants choose between two options: the safe option returns its outcome with 100% probability, while the risky option returns one of two outcomes with 50% probability each. In loss trials, the expected value of the safe option is negative. In ambiguous trials, the probabilities of the outcomes of the risky option are only partly shown.

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, with an added column risky, 1 for risky and 0 for safe choices.

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.

Raises:
ValueError

If chosen contains values other than 1 (safe) and 2 (risky).

Notes

The data must contain the following columns:

  • userID: the unique identifier of the participant.

  • run: the attempt number of the participant.

  • date: the date and time of the trial.

  • RT: the response time, in ms.

  • chosen: the chosen option, 1 for safe and 2 for risky.

  • ambiguousTrial: whether the trial was ambiguous (1) or not (0).

  • abovechance: whether the choice was above chance level (1) or not (0).

  • EV_diff_chosen: the expected value of the chosen minus the unchosen option. A choice is rational if it is 0 or more.

  • safe_EV: the expected value of the safe option; trials where it is negative are loss trials, the others win trials.

  • outcome: the points received on the trial.

  • nbcorrect_gain: whether the choice in a no-brainer gain (catch) trial was correct (1) or not (0).

  • resp_rep: whether the left/right response repeated the previous one (1) or not (0).

  • resp_rep_sr: whether the safe/risky choice repeated the previous one (1) or not (0).

  • config_id: the version of the game. Only needed by clean_data().

Trials are excluded if the response time is below 150 ms or above 10000 ms, and only the first attempt of each participant (run equal to 1) is kept.

References

Habicht, J., Dubois, M., Michely, J., & Hauser, T. U. (2022). Do propranolol and amisulpride modulate confidence in risk-taking? Wellcome Open Research, 7, 23.

Examples

>>> from cpm.brainexplorer.risky_decision_making import Scavenger
>>> scavenger = Scavenger("2025-01-10_Scavenger.csv")
>>> results = scavenger.metrics()
>>> cleaned = scavenger.clean_data()
>>> scavenger.get_codebook()["risky_choices"]
'Proportion of risky choices overall'
metrics()[source]#

Compute the metrics of each participant: response times, points, and the proportions of risky and rational choices, overall and by win/loss and ambiguous/non-ambiguous trials.

Returns:
pandas.DataFrame

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

Notes

Metrics of an empty selection, such as the proportion of risky choices in ambiguous loss trials for a participant who played none, are NaN.

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.

Raises:
KeyError

If the data have no config_id column.

Notes

A participant is excluded if

  • they repeated the same left/right response on at least 95% of the trials,

  • they failed 2 or more of the no-brainer catch trials,

  • they played more than 40 trials (due to a technical error),

  • they played the version of the game with 60 trials (config_id 242).

get_codebook()[source]#

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

Returns:
dict

The description of each column, keyed by column name.