bloomberg / bloomberg/causal-ts

Add beginner-friendly step-by-step tutorials for constraint-based (PC) and score-based causal discovery

Closed
#56 3 comments 0 reactions 2 assignees Claimed by @mittal-aakriti View on GitHub
documentation help wanted
Dominant language
Python
Stars
36
Forks
15
Avg merge
4h 1m
Merged PRs (30d)
36

Description

The docs have a general [Beginner's Guide](../examples/beginers_guide.html) covering causation vs. correlation and a high-level constraint-based vs. score-based comparison, plus the full [`tutorial.ipynb`](../tutorial.html) walkthrough of CDNOTS/CEDAR/GRACE — but nothing that walks through *how either algorithm family actually works*, step by step, on a small example.

## What needs doing

Add two new tutorial notebooks under `examples/` (symlinked into `docs/examples/`, matching the existing pattern used by `beginners_guide.ipynb`):

1. `pc_step_by_step.ipynb` — constraint-based discovery on a small synthetic example: build the skeleton via pairwise/conditional independence tests, show the sepsets found, then walk through collider detection and Meek-rule orientation one rule at a time, showing the graph after each step rather than jumping to the final CPDAG.
2. `score_based_step_by_step.ipynb` — same treatment for a score-based method (e.g. GES): show the forward (insert) and backward (delete) search incrementally, with the score at each step, rather than only the converged result.

Both should:
- Keep outputs pre-baked into the notebook (docs build uses `nb_execution_mode = "off"`, so notebooks aren't re-executed at build time).
- Add a thumbnail under `docs/_static/img/thumbnails/` and a gallery entry in `docs/examples/index.md`'s "Tutorials" section.
- Ideally cross-link from the Beginner's Guide's constraint-based/score-based comparison section.

Good first doc-contribution issue for anyone comfortable with `causal-learn`/CDNOTS internals and Jupyter.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.