CPM: a python library for theory-driven modeling in computational psychiatry

Presentation Slides:

What?

Computational psychiatry has grown rapidly, but modeling approaches remain fragmented and inconsistently implemented across labs. Differences in code, assumptions, and documentation can make results difficult to reproduce or compare. At the same time, these methods can be difficult to use for researchers without a computational background, creating barriers to adoption and increasing the risk of errors when working with complex data.

The Computational Psychiatry Modelling (cpm) toolbox addresses these challenges by providing a unified, theory-driven framework for computational modeling. It is a Python library that integrates a wide range of established modeling approaches within a single, flexible system.

The cpm toolbox supports multiple types of tasks (e.g., decision-making, learning, perceptual metacognition), models (including reinforcement learning, associative models, and signal detection frameworks), and methods (such as hierarchical parameter estimation using Bayesian techniques). Its modular design allows users to adapt models to different research questions while following best practices for implementation and reporting.

By bringing these components together in one accessible framework, cpm enables both novice and experienced users to build, fit, and evaluate computational models more efficiently and consistently across studies and domains.

Why?

The cpm toolbox is designed to make computational modeling more accessible and transparent. Its interface is “interaction-centric,” meaning it mirrors how researchers naturally think about tasks and models, reducing unnecessary coding while keeping assumptions explicit.

A key strength is its modular design, which allows users to engage with the toolbox at different levels. Researchers can use fully specified models, combine pre-built components (e.g., learning and decision rules), or build models from scratch, depending on their experience and needs.

The toolbox is also supported by extensive documentation and active maintenance, including tutorials, methodological explanations, and clear handling of bugs and updates. Together, these features make it easier to implement, understand, and extend computational models in a consistent and reliable way.

How?

Prerequisites:

• Minimal coding experience required.
• Basic familiarity with Python is helpful but not necessary.
• More advanced use involves expressing behavioral theories as trial-wise generative models and validating them using simulation- and likelihood-based inference.

Requirements:

• Python version 3.10 or higher
• The toolbox is open-source and freely available

Data:

• Includes example datasets (e.g., metacognition, risky decision-making, reinforcement learning)
• Can be applied to custom datasets across a wide range of tasks

Workflow:

• Use pre-built models or components (e.g., learning and decision rules), or define custom models
• Fit models to data using built-in inference methods
• Validate models through simulation and model comparison

Tutorials and documentation: https://devcompsy.github.io/cpm/

Reference publication: Dome, L., Wagner, B., Kadri, K., Hauser, T. U., & Webb, A. (2025). cpm: a python library for theory-driven modelling in computational psychiatry. https://doi.org/10.31234/osf.io/6jc3t_v1