Skip to main content

Welcome to the causalchamber package!

PyPI version Downloads License: MIT Donate

The Causal Chambers: (left) the wind tunnel, and (right) the light tunnel with the front panel removed to show its interior.

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.

Donate

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)

Source distribution for causalchamber 1.0.0
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)

Table of built distributions (wheels) for causalchamber 1.0.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page