Metadata-Version: 2.1
Name: causalchamber
Version: 0.0.2
Summary: Access the datasets and models from the causal chambers.
Author-email: Juan L Gamella <juangamella@gmail.com>
Project-URL: Homepage, https://causalchamber.org
Project-URL: Repository, https://github.com/juangamella/causal-chamber
Project-URL: Issues, https://github.com/juangamella/causal-chamber/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE

# Welcome to the `causalchamber` package

![The Causal Chambers: (left) the wind tunnel, and (right) the light tunnel with the front panel removed to show its interior.](https://github.com/juangamella/causal-chamber/raw/main/the_chambers.jpg)

The `causalchamber` package gives you access to [datasets](#accessing-the-datasets), [mechanistic models](#mechanistic-models), and [ground-truth graphs](#causal-ground-truth-graphs) from the causal chamber project. See [causalchamber.org](https://causalchamber.org) for more details.

## Download

You can install the package via pip, i.e. by typing

```
pip install causalchamber
```

in an appropriate shell.


## Accessing the datasets

Datasets can be loaded directly into your Python code. For example, you to access the image data from task d3 in the ICA case study (Fig. 6 of the original [paper](<https://placehold.co/600x400?text=Placeholder:\nArxiv link!>)):

```python
from causalchamber.datasets import Dataset

# Download the dataset and store in e.g. ./
dataset = Dataset(name='lt_camera_walks_v1',
                  root='./',
                  download=True)

# Select an experiment
experiment = dataset.get_experiment(name='actuator_mix')
# Load the observations and images (at 50x50 pixels)
observations = experiment.as_pandas_dataframe()
images = experiment.as_image_array(size='50')
```

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.

You can see what datasets are available at [causalchamber.org](https://causalchamber.org) or by typing:

```Python
causalchamber.datasets.list_available()

# Output:
```

For the available experiments in each dataset, you can run:
```python
dataset.available_experiments()

# Output:
# ['actuator_mix',
#  'color_mix']
```

For the available image sizes (only in image datasets):
```python
experiment.available_sizes()

# Output:
# ['full', '500', '200']
```

## Mechanistic models

The `causalchamber` [package](<https://placehold.co/600x400?text=Placeholder:\nPyPi link!>) also contains Python implementations of the mechanistic models described in appendix [XX] of the original [paper](<https://placehold.co/600x400?text=Placeholder:\nArxiv link!>). The models follow the same nomenclature as in the paper, e.g., to import and run model A1 of the steady-state fan speed:
```Python
from causalchamber.models import model_a1
model_a1(L=np.linspace(0,1,10), L_min=0.1, omega_max=314.15)

# Output:

# array([ 31.415     ,  34.90555556,  69.81111111, 104.71666667,
#        139.62222222, 174.52777778, 209.43333333, 244.33888889,
#        279.24444444, 314.15      ])
```

The implementations can be found in the [`src/causalchamber/models`](src/causalchamber/models) directory. You can find examples of using the models in the (case_studies/mechanistic_models.ipynb)[XX] notebook in the separate [paper repository](https://github.com/juangamella/causal-chamber-paper).

## Causal ground-truth graphs

The graphs for the causal ground truths given in Fig. 3 of the original [paper](<https://placehold.co/600x400?text=Placeholder:\nArxiv link!>) can be found as adjacency matrices in  the `ground_truths/` directory of the [project repository](https://github.com/juangamella/causal-chamber). The adjacencies can also be loaded through the `causalchamber` [package](<https://placehold.co/600x400?text=Placeholder:\nPyPi link!>), e.g., 
```python
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 chamber identifiers are `wt,lt` for the wind tunnel and light tunnel, respectively. 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
```python
from causalchamber.ground_truth import latex_name
latex_name('pol_1', enclose=True)

# Output:

# '$\\theta_1$'
```
