Feature/brainexplorer

[lenarddome]

Summary

Adds cpm.brainexplorer, which computes descriptive statistics and applies the exclusion criteria for four BrainExplorer games, with tests and an API reference page. It also fixes how the optimisers handle ppt_identifier, and bumps the version to 0.26.0.dev1.

Changes

cpm.brainexplorer (new). One class per game, each with metrics(), clean_data() and get_codebook():

Class	Game
perceptual_decision_making.SpaceObserver	Space Observer (perceptual decisions with confidence)
risky_decision_making.Scavenger	Scavenger (risky decisions)
information_gathering.TreasureHunt	Treasure Hunt (information gathering)
bandits.MilkyWay	Milky Way and Pirate Market (two-armed bandits)

Each class reads a CSV file or a DataFrame, and raises a KeyError that names any required column missing from the data.

Bugs fixed in the module before it lands:

• Scavenger assumed chosen was coded 0 (safe) / 1 (risky), but raw exports use 1 / 2, so the "risky" metrics measured safe choices. Choices are now recoded on load, and any other coding raises an error.
• Scavenger: an operator-precedence bug (~t_loss & rsk == 0) made rational_safe_win, rational_safe_loss, rational_risky_win and rational_risky_loss use the wrong trials.
• Scavenger.clean_data() now applies the documented exclusion for repeating the same left/right response on at least 95% of trials.
• TreasureHunt and MilkyWay never classified a session as "night".
• MilkyWay never wrote the session date and time to its results. Its clean_data() failed unless difference_metrics() had been run first.
• TreasureHunt.codebook() and MilkyWay.codebook() could not be called; they are now get_codebook(), as in the other classes.
• Running metrics() twice appended duplicate rows.

Optimisers. Fmin, FminBound, Bads, Minimize, DifferentialEvolution and EstimatorMetaD raised UnboundLocalError for a DataFrame without ppt_identifier. They now:

• raise a ValueError saying what to pass,
• raise a KeyError listing the columns if ppt_identifier is not one of them,
• take ppt_identifier from the grouping when the data are grouped by one column (data.groupby("ppt")), so the fits record the participants.

Generators. Restores main's handling of values outside a prior's support in Parameters.PDF. An old commit on this branch gave them a log prior of about 0, the value for probability 1, instead of the lowest finite value.

Datasets. Adds cpm.datasets.load_model_based_model_free, two-step task data from BrainExplorer, with a page in the API reference.

Merge with main. Conflicts were resolved in favour of main. In particular, the branch's MBMF model is replaced by main's HybridMBMF.

Testing

• 686 tests pass, 71 of them new in test/brainexplorer/. The Scavenger tests use hand-computed values for a participant designed so that the old coding bug gives different answers.
• The docs CI checks pass, and the documentation builds with -W.

🤖 Generated with Claude Code