Docs (#7)

* Add docs workflow

* Add docs workflow

* Add docs workflow

* Update Index

* Add build workflow

---------

Co-authored-by: Thomas Pinder <[email protected]>

Author: thomaspinder

.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: Build Documentation
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "**"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-docs:
+    concurrency: ci-${{ github.ref }}
+    name: Build docs
+    runs-on: "ubuntu-latest"
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      # Grap the latest commit from the branch
+      - name: Checkout the branch
+        uses: actions/[email protected]
+        with:
+          persist-credentials: false
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+
+      - name: Install Hatch
+        uses: pypa/hatch@install
+
+      - name: Build and deploy the documentation
+        run: hatch run docs:deploy

.github/workflows/test_docs.yml

@@ -0,0 +1,35 @@
+name: Build Documentation
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-docs:
+    concurrency: ci-${{ github.ref }}
+    name: Build docs
+    runs-on: "ubuntu-latest"
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      # Grap the latest commit from the branch
+      - name: Checkout the branch
+        uses: actions/[email protected]
+        with:
+          persist-credentials: false
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+
+      - name: Install Hatch
+        uses: pypa/hatch@install
+
+      - name: Build and deploy the documentation
+        run: hatch run docs:build

.github/workflows/tests.yml

@@ -20,6 +20,7 @@ jobs:
         uses: actions/[email protected]
         with:
           fetch-depth: 1
+
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v4
         with:

.gitignore

@@ -147,4 +147,5 @@ scratch_nbs/
 .DS_store
 package.json
 package-lock.json
-node_modules/
+node_modules/
+docs/_examples

docs/index.md

@@ -0,0 +1,56 @@
+# Welcome to Causal Validation
+
+Causal Validation is a library designed to validate and test your causal models. To
+achieve this, we provide functionality to simulate causal data, and vaildate your model
+through a placebo test. 
+
+## Data Synthesis
+
+Data Synthesis in Causal Validation is a fully composable process whereby a set of
+functions are sequentially applied to a dataset. At some point in this process we also
+induce a treatment effect. Any of these functions can be parameterised to either have
+constant parameter values across all control units, or a value that varies across
+parameters. To see this, consider the below example where we simulate a dataset whose
+trend varies across each of the 10 control units.
+
+```python
+from causal_validation import Config, simulate
+from causal_validation.effects import StaticEffect
+from causal_validation.plotters import plot
+from causal_validation.transforms import Trend, Periodic
+from causal_validation.transforms.parameter import UnitVaryingParameter
+from scipy.stats import norm
+
+cfg = Config(
+    n_control_units=10,
+    n_pre_intervention_timepoints=60,
+    n_post_intervention_timepoints=30,
+)
+
+# Simulate the base observation
+base_data = simulate(cfg)
+
+# Apply a linear trend with unit-varying intercept
+intercept = UnitVaryingParameter(sampling_dist = norm(0, 1))
+trend_component = Trend(degree=1, coefficient=0.1, intercept=intercept)
+trended_data = trend_component(base_data)
+
+# Simulate a 5% lift in the treated unit's post-intervention data
+effect = StaticEffect(0.05)
+inflated_data = effect(trended_data)
+```
+
+## Model Validation
+
+Once a dataset has been synthesised, we may wish to validate our model using a placebo
+test. In Causal Validation this is straightforward and can be accomplished in
+combination with AZCausal by the following.
+
+```python
+from azcausal.estimators.panel.sdid import SDID
+from causal_validation.validation.placebo import PlaceboTest
+
+model = AZCausalWrapper(model=SDID())
+result = PlaceboTest(model, inflated_data).execute()
+result.summary()
+```

docs/scripts/gen_examples.py

@@ -0,0 +1,95 @@
+from argparse import ArgumentParser
+from pathlib import Path
+import subprocess
+from concurrent.futures import ThreadPoolExecutor, as_completed
+import shutil
+from dataclasses import dataclass
+
+EXCLUDE = ["utils.py"]
+
+
+def process_file(file: Path, out_file: Path | None = None, execute: bool = False):
+    """Converts a python file to markdown using jupytext and nbconvert."""
+
+    out_dir = out_file.parent
+    command = f"cd {out_dir.as_posix()} && "
+
+    out_file = out_file.relative_to(out_dir).as_posix()
+
+    if execute:
+        command += f"jupytext --to ipynb {file} --output - "
+        command += (
+            f"| jupyter nbconvert --to markdown --execute --stdin --output {out_file}"
+        )
+    else:
+        command += f"jupytext --to markdown {file} --output {out_file}"
+
+    subprocess.run(command, shell=True, check=False)
+
+
+def is_modified(file: Path, out_file: Path):
+    """Check if the output file is older than the input file."""
+    return out_file.exists() and out_file.stat().st_mtime < file.stat().st_mtime
+
+
+def main(args):
+    # project root directory
+    wdir = Path(__file__).parents[2]
+
+    # output directory
+    out_dir: Path = args.outdir
+    out_dir.mkdir(exist_ok=True, parents=True)
+
+    # copy directories in "examples" to output directory
+    for dir in wdir.glob("examples/*"):
+        if dir.is_dir():
+            (out_dir / dir.name).mkdir(exist_ok=True, parents=True)
+            for file in dir.glob("*"):
+                # copy, not move!
+                shutil.copy(file, out_dir / dir.name / file.name)
+
+    # list of files to be processed
+    files = [f for f in wdir.glob("examples/*.py") if f.name not in EXCLUDE]
+    print(files)
+
+    # process only modified files
+    if args.only_modified:
+        files = [f for f in files if is_modified(f, out_dir / f"{f.stem}.md")]
+
+    # process files in parallel
+    if args.parallel:
+        with ThreadPoolExecutor(max_workers=args.max_workers) as executor:
+            futures = []
+            for file in files:
+                out_file = out_dir / f"{file.stem.replace('.pct', '')}.md"
+                futures.append(
+                    executor.submit(
+                        process_file, file, out_file=out_file, execute=args.execute
+                    )
+                )
+
+            for future in as_completed(futures):
+                try:
+                    future.result()
+                except Exception as e:
+                    print(f"Error processing file: {e}")
+    else:
+        for file in files:
+            out_file = out_dir / f"{file.stem.replace('.pct', '')}.md"
+            process_file(file, out_file=out_file, execute=args.execute)
+
+
+@dataclass
+class GeneratorArgs:
+    max_workers: int = 4
+    execute: bool = True
+    only_modified: bool = False
+    project_root: Path = Path(__file__).parents[2]
+    parallel: bool = False
+
+    def __post_init__(self):
+        self.outdir: Path = self.project_root / "docs" / "_examples"
+
+
+args = GeneratorArgs()
+main(args)

examples/azcausal.pct.py

@@ -1,3 +1,12 @@
+# %% [markdown]
+# # AZCausal Integration
+#
+# Amazon's [AZCausal](https://github.com/amazon-science/azcausal) library provides the
+# functionality to fit synthetic control and difference-in-difference models to your
+# data. Integrating the synthetic data generating process of `causal_validation` with
+# AZCausal is trivial, as we show in this notebook. To start, we'll simulate a toy
+# dataset.
+
 # %%
 from azcausal.estimators.panel.sdid import SDID
 import scipy.stats as st
@@ -14,15 +23,6 @@
 )
 from causal_validation.transforms.parameter import UnitVaryingParameter
 
-# %% [markdown]
-# ## AZCausal Integration
-#
-# Amazon's [AZCausal](https://github.com/amazon-science/azcausal) library provides the
-# functionality to fit synthetic control and difference-in-difference models to your
-# data. Integrating the synthetic data generating process of `causal_validation` with
-# AZCausal is trivial, as we show in this notebook. To start, we'll simulate a toy
-# dataset.
-
 # %%
 cfg = Config(
     n_control_units=10,
@@ -45,7 +45,7 @@
 plot(inflated_data)
 
 # %% [markdown]
-# ### Fitting a model
+# ## Fitting a model
 #
 # We now have some very toy data on which we may apply a model. For this demonstration
 # we shall use the Synthetic Difference-in-Differences model implemented in AZCausal;

examples/basic.pct.py

@@ -1,3 +1,12 @@
+# %% [markdown]
+# # Data Synthesis
+#
+# In this notebook we'll demonstrate how `causal-validation` can be used to simulate
+# synthetic datasets. We'll start with very simple data to which a static treatment
+# effect may be applied. From there, we'll build up to complex datasets. Along the way,
+# we'll show how reproducibility can be ensured, plots can be generated, and unit-level
+# parameters may be specified.
+
 # %%
 from itertools import product
 

examples/placebo_test.pct.py

@@ -9,7 +9,7 @@
 #       format_version: '1.3'
 #       jupytext_version: 1.16.4
 #   kernelspec:
-#     display_name: causal-validation
+#     display_name: dev
 #     language: python
 #     name: python3
 # ---
@@ -107,7 +107,3 @@
 # %%
 did_model = AZCausalWrapper(model=DID())
 PlaceboTest([model, did_model], data).execute().summary()
-
-# %%
-
-# %%

mkdocs.yml

@@ -0,0 +1,38 @@
+site_name: Causal Validation
+repo_url: https://github.com/amazon-science/causal-validation
+site_url: https://amazon-science.github.io/causal-validation/
+repo_name: causal-validation
+
+nav:
+  - Home: index.md
+  - Examples:
+    - Data Synthesis: _examples/basic.md
+    - Placebo Testing: _examples/placebo_test.md
+    - AZCausal Integration: _examples/azcausal.md
+
+theme:
+  name: material
+  language: en
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.sections
+    - search.suggest
+    - content.code.copy
+
+markdown_extensions:
+  - abbr
+  - admonition
+
+plugins:
+  - search
+  - gen-files:
+      scripts:
+        - docs/scripts/gen_examples.py
+
+extra:
+  version:
+    provider: mike
+
+watch:
+  - src