Welcome to the causalchamber package!
The causalchamber package provides different functionality for the Causal Chambers:
- Remote Lab: a Python interface to run real-time experiments and collect datasets from our pool of chambers.
- Simulators: Python simulators and mechanistic models of different chamber phenomena.
- Open-source Datasets: download existing datasets from the dataset repository directly into your Python code.
- Ground truth: load the ground-truth causal graphs and other information for each chamber.
Install
You can install the package via pip, i.e., by typing
pip install causalchamber
in an appropriate shell.
Remote Lab
You can use our Remote Lab to collect your own data from the chambers and run experiments in real time.
See the documentation for examples.
Simulators
The package also contains Python implementations of different simulators of chamber phenomena, including the mechanistic models described in Appendix IV of the original paper.
See the Simulator Index for the complete documentation and examples.
Open-source Datasets
You can download existing datasets from the dataset repository directly into your Python code. For example, you can load the lt_camera_test_v1 image dataset as follows:
import causalchamber.datasets as datasets
# Download the dataset and store it, e.g., in the current directory
dataset = datasets.Dataset(name='lt_camera_test_v1', root='./', download=True)
# Select an experiment and load the observations and images
experiment = dataset.get_experiment(name='palette')
observations = experiment.as_pandas_dataframe()
images = experiment.as_image_array(size='200')
If download=True, the dataset will be downloaded and stored in the path provided by the root argument. If the dataset has already been downloaded it will not be downloaded again (this also means you must delete the dataset yourself if you want to download a fresh copy; this is on purpose :). The available experiments are documented in the dataset's page, and can be listed by calling dataset.available_experiments() in the above example.
The image sizes available for a particular experiment can be listed by calling experiment.available_sizes() in the above example.
For a list of all the available datasets you can visit the dataset repository or call
causalchamber.datasets.list_available()
The package refreshes its list of available datasets every time it's freshly imported.
Ground truth
Note: This loads the ground truth for the original Mk1 prototypes of the Nature paper. See the documentation for the ground truth of the newer Mk2 models (Light Tunnel / Wind Tunnel).
For evaluation and visualization, you can directly load the ground-truth causal graphs for the different chambers and their configurations. For example, to load the causal graphs given in Fig. 3 of the original paper:
from causalchamber.ground_truth import graph
graph(chamber="lt", configuration="standard")
# Output:
# red green blue osr_c v_c current pol_1 pol_2 osr_angle_1 \
# red 0 0 0 0 0 1 0 0 0
# green 0 0 0 0 0 1 0 0 0
# blue 0 0 0 0 0 1 0 0 0
# osr_c 0 0 0 0 0 1 0 0 0
The graph adjacencies are also available as matrices here, where an edge i->j is denoted by a non-zero entry in the ith row + jth column.
To make it easier to plot graphs and reference them back to the original paper, the latex representation of each variable can be obtained by calling the latex_name function. For example, to obtain the latex representation $\theta_1$ of the pol_1 variable, you can run
from causalchamber.ground_truth import latex_name
latex_name('pol_1', enclose=True)
# Output:
# '$\\theta_1$'
Setting enclose=False will return the name without surrounding $. The complete mapping between variable names and latex symbols is given in Appendix II of the original paper.
Versioning
We follow Semantic Versioning, i.e., non backward-compatible changes to the package are reflected by a change to the major version number,
e.g., code that uses causalchamber==0.1.2 will run with causalchamber==0.2.0, but may not run with causalchamber==1.0.0.
Help & Feedback
If you encounter a bug, need help using the package, or want to leave us some (highly welcome) feedback, please send us an email, leave a GitHub issue or start a new Discussion.
License
The code in this repository is shared under the permissive MIT license. A copy can be found in LICENSE.txt.
How to cite
If you use this package for your scientific work, please consider citing:
@article{gamella2025chamber,
author={Gamella, Juan L. and Peters, Jonas and B{\"u}hlmann, Peter},
title={Causal chambers as a real-world physical testbed for {AI} methodology},
journal={Nature Machine Intelligence},
doi={10.1038/s42256-024-00964-x},
year={2025},
}
Contributing
Please reach out if you would like to contribute code to the project.
You can also contribute financially with a donation as a Github sponsor.
Metadata
Release files for causalchamber 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| causalchamber-1.0.0.tar.gz | 97.5 kB | Without provenance | Details for causalchamber-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| causalchamber-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for causalchamber-1.0.0-py3-none-any.whl |
Total release size: 221.3 kB
Release files / causalchamber-1.0.0.tar.gz
| Download URL | causalchamber-1.0.0.tar.gz |
|---|---|
| Size | 97.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0fb8204add66438c2a4f85c880c69138ba674174caa4898f452dd54102f527ca
|
|
BLAKE2b-256 checksum How to use checksums |
80df8c3a57eed78006cbe4c29199ec7bf7e14c308e6f9c8b8e637bed23575626
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.0
|
Release files / causalchamber-1.0.0-py3-none-any.whl
| Download URL | causalchamber-1.0.0-py3-none-any.whl |
|---|---|
| Size | 123.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b03a6544e6c44bbd08ab8132aafab81aa2489f5c7decfecc895b31ca8faadd86
|
|
BLAKE2b-256 checksum How to use checksums |
eb886a84636b909b2b4d543709f004dffa88d9d6b9025d92220d9520865bf3d2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.0
|
Security for causalchamber 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.