Hierarchical Causal Models Notebooks

[adamrupe]

Follow-up to #370, related to #278

Notebooks:

1. https://github.com/y0-causal-inference/y0/blob/HCM-fig2/notebooks/HCM%20Manuscript%20Figures.ipynb
2. https://github.com/y0-causal-inference/y0/blob/HCM-fig2/notebooks/Hierarchical%20Causal%20Models.ipynb

---

This PR implements Hierarchical Causal Models (Weinstein and Blei, 2024)

This PR will be ready for review when the following algorithms have been tested and implemented.

• Algorithm 1: Graphical algorithm for collapsing a hierarchical causal graphical model (HCGM). This algorithm transforms the graph of a hierarchical causal model (HCM) into the graph of its collapsed model, following Definition 4.
• Algorithm 2: Graphical algorithm for augmenting a collapsed model. This algorithm adds an
  augmentation variable to a collapsed HCGM, following Definition 6.
• Algorithm 3: Graphical algorithm for marginalizing an augmented model. This algorithm
  marginalizes out parent(s) of an augmentation variable (Section 5.2).
• Causal query pipeline: Utilizes Algorithms 1 -3 (as needed) to check if a causal query is identifiable in the HCM. The use of Algorithms 2 and 3 depends on the causal query, i.e. whether a variable needs to be augmented in (Alg 2) and then whether another variable needs to be marginalized out (Alg 3).
• HSCM tests
• High-level example (with real-world motivation) that shows how to do a causal query on a HCM

[codecov]

Codecov Report

Attention: Patch coverage is 88.12500% with 19 lines in your changes missing coverage. Please review.

Project coverage is 81.27%. Comparing base (05a9456) to head (3af8c66).
Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
src/y0/hierarchical.py	88.12%	9 Missing and 10 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #236      +/-   ##
==========================================
+ Coverage   80.87%   81.27%   +0.39%     
==========================================
  Files          50       51       +1     
  Lines        4135     4314     +179     
  Branches      845      981     +136     
==========================================
+ Hits         3344     3506     +162     
- Misses        668      670       +2     
- Partials      123      138      +15     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[cthoyt]

hi @adamrupe - can you add a checklist into the PR description with the tasks to complete for this PR before it needs review?

[Copilot]

Copilot reviewed 18 out of 19 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• tox.ini: Language not supported

[cthoyt]

I did a major refactor to address the software issues from the last round. The next steps for @adamrupe and @djinnome are:

1. Read through the code and familiarize yourselves with the new interface
2. Comment on / address all TODO's I left in the code (there aren't many)
3. Tests
   • Either implement tests for conversion to HSCM or delete the conversion code
   • Test augment_collapsed_model
4. Check the notebook, which used to raise some exceptions, but I replaced those with the high-level identify_outcomes API. Please review to make sure that the places where there is no estimand produced because the graph has a single c-component are all correct
5. Create a high-level, real world example that demonstrates using all of the code in a story-driven workflow (i.e., do not explain the math, only explain which functions you implemented solve the problem). Use https://github.com/y0-causal-inference/y0/blob/main/notebooks/Counterfactual%20Transportability.ipynb as a golden standard for how a great notebook with applications looks

Along the way, please make sure that you check the CI/CD system for automated, objective feedback on code quality. @adamrupe if you're not familiar with how to do this, I am happy to show you

[adamrupe]

@cthoyt What's your recommendation for handling merge conflicts with jupyter notebooks? I need to do this before I can pull your updates. I'm also not familiar with the CI/CD system, so if you could talk me through it that would be great.

[cthoyt]

@adamrupe before merging, copy your local notebook to your desktop. While merging, throw away everything from your repository's copy and overwrite it with remote. Then, you can think about manually inspecting your notebook on your desktop, and the new version from the remote repo side-by-side.

The best way to avoid this kind of thing is never to leave changes unpushed when you finish working, and to always pull before you start working again

---

The short explanation of how to use the CI/CD system is: you can always scroll to the bottom of this pull request (#236) and look at the feedback given by GitHub running our unit tests, linting, and code quality checks.

This is what it looks like to me right now:

You can click on any of the rows with the red x's, and then it will bring you to the page that ran the tests for you. Right now, you will be able to see all of the output from running pytest. You have to scroll up a bit since unfortunately, pytest reports timings and warnings after test failures, but you can see https://github.com/y0-causal-inference/y0/actions/runs/13134504627/job/36646756591?pr=236#step:6:69 for the currently failing test.

Similarly, while you're still getting used to having code quality checks, you will probably see that the linting or type checking scripts also give errors, which you can view in the same way..

It's sort of the expectation in a team setting for coding that you make pushes often, and each time check out what kind of feedback CI gives. This will help you iteratively make your code better, with fully objective feedback that you don't have to wait on someone else to give you. Alternatively to CI/CD in GitHub, you can run tox which also creates a reproducible execution of all of the testing suite.

There's documentation in the README on how to use all of the nice development tools built into this repo at https://github.com/y0-causal-inference/y0?tab=readme-ov-file#%EF%B8%8F-for-developers

If you get caught up on any parts of this that aren't self-explanatory, I'm happy to plan a video chat tomorrow, or sometime next before 6PM germany time

[adamrupe]

Awesome, thanks @cthoyt! That makes sense, and Jeremy and Richard have already shown me how to use tox a bit. I've pulled your changes and I'm going through them now. I'll add a test_to_hscm.

[cthoyt]

@adamrupe @njmmerrill there are only two tests failing, do you think we can address those and merge this (this PR is not blocked by finishing notebooks)?

[djinnome]

Hey @cthoyt well, the good news is that @njmmerrill @augeorge @emilydogbatsePNNL2025 @callahanr and I found and fixed the failing tests in test_hierarchical, but now we are getting some notebook failures in counterfactual transportability (which we did not modify).

[cthoyt]

great! I split all of the non-notebook code out of this PR into a new PR, then merged it. I will leave it to all of you to continue work on the notebooks here.

If nobody intentionally changed the counterfactual transport notebook, then I would suggest deleting the notebooks/Counterfactual Transportability edited.ipynb file from this PR.