MilkyWay#

class MilkyWay(filepath=None)[source]#

Bases: object

Compute descriptive statistics from the two-armed bandit tasks in BrainExplorer, Milky Way (reward) and Pirate Market (punishment).

The metrics of the two games are computed separately, and difference_metrics() compares them within participants.

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:
MW_data, PM_datapandas.DataFrame

The Milky Way and Pirate Market trials that pass the trial-level exclusion criteria.

results_MW, results_PMpandas.DataFrame

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

results_diffpandas.DataFrame

The differences between the games, filled by difference_metrics().

cleanedresults_MW, cleanedresults_PM, cleanedresults_diffpandas.DataFrame

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

deleted_participants_MW, deleted_participants_PM, deleted_participants_diffint

The number of participants that clean_data() excluded from each table.

codebookdict

The description of each column of the metrics.

Notes

The data must contain the following columns:

  • userID: the unique identifier of the participant.

  • trial_type: the game, "reward" for Milky Way or "punish" for Pirate Market.

  • run: the attempt number of the participant.

  • date: the date and time of the trial.

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

  • outchosen: the outcome of the chosen option.

  • obt_min_forg: the obtained minus the foregone outcome.

  • rep: whether the choice repeated the previous one (1) or not (0).

  • WSLS_v1, WSLS_v2: whether the choice was a win-stay/lose-shift choice, in two versions of the definition.

Only the first attempt of each participant in each game is kept, which is not necessarily run 1 for Pirate Market.

Response times are not analysed. They would have to be corrected for the average time between the previous choice and the presentation of the new stimuli, 4200 ms, which can make them negative.

Examples

>>> from cpm.brainexplorer.bandits import MilkyWay
>>> milky_way = MilkyWay("2025-02-20_MilkyWay_Data.csv")
>>> results_MW, results_PM = milky_way.metrics()
>>> differences = milky_way.difference_metrics()
>>> cleaned_MW, cleaned_PM, cleaned_diff = milky_way.clean_data()
metrics()[source]#

Compute the metrics of each participant in each game.

Returns:
tuple of pandas.DataFrame

The metrics of Milky Way and of Pirate Market, one row per participant, also stored in results_MW and results_PM. The columns are described in codebook.

difference_metrics()[source]#

Compute the difference between the metrics of Milky Way and Pirate Market, for each participant who played both.

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

Returns:
pandas.DataFrame

The differences, Milky Way minus Pirate Market, one row per participant, also stored in results_diff. The columns are described in codebook.

clean_data()[source]#

Exclude participants with the participant-level exclusion criteria.

Runs metrics() and difference_metrics() first if they have not been run yet.

Returns:
tuple of pandas.DataFrame

The metrics of Milky Way, of Pirate Market, and their differences, for the participants that pass the criteria, also stored in cleanedresults_MW, cleanedresults_PM and cleanedresults_diff.

Notes

A participant is excluded from the metrics of a game if

  • they made the same choice on at least 95% of the trials,

  • their accuracy is missing,

  • they played more than 72 trials of the game (due to a technical error).

The differences are kept only for participants who pass the criteria in both games.

get_codebook()[source]#

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

Returns:
dict

The description of each column, keyed by column name.