causalphylo 0.1.0__tar.gz

causalphylo-0.1.0/.gitignore

@@ -0,0 +1,79 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Environment files (not .env.example)
+.env
+.env.local
+.env.production
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test / coverage
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# Generated outputs
+reports/
+results/
+
+# Molecular data caches
+modules/dockbot/cache/
+*.pdb
+*.pdbqt
+*.sdf
+*.mol2
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Model weights (too large for git)
+*.pt
+*.pth
+*.h5
+*.pkl
+*.ckpt
+
+# Shipped model asset — must be committed and packaged (see pyproject artifacts)
+!src/neorx/genmol/assets/*.pt
+
+# ChEMBL SQLite database (28 GB — too large for git)
+chembl_*.db
+
+# Local backups and trained-model checkpoints -- large and machine-specific,
+# never meant to be committed (a `git add -A` would otherwise pull in tens
+# of MB of these).
+.backup-scripts/
+checkpoints/
+
+# Experiment run records are deliverables, not scratch -- they are the
+# evidence behind every reported number, IF they are cited. See
+# docs/run-manifest.toml. Default to NOT tracking a run directory (so a
+# routine `git add -A` cannot sweep in an ad-hoc or smoke run); a record
+# that actually backs a claim is added deliberately with
+# `git add -f runs/<run-id>`.
+!runs/
+runs/*
+!runs/.gitkeep
+
+# MkDocs build output
+site/

causalphylo-0.1.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to CausalPhylo will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-10-17
+
+First release as a standalone package.
+
+`graph_semantics` and `backdoor` were written inside
+[NeoRx](https://github.com/Neoforge-Labs/neorx) and extracted here with their
+commit history. They were the part of NeoRx's causal code that depended on
+nothing but NetworkX, while NeoRx itself imported admissibility back out of
+them — a cycle one distribution can hold and two cannot. So the boundary was
+drawn where the dependency graph allows a real one.
+
+### Added
+
+- `causalphylo.graph_semantics` — `is_causal_admissible`, `causal_subgraph`,
+  `cyclic_components`, `acyclic_core`, and the `CAUSAL_EDGE_TYPES` /
+  `GENETIC_EVIDENCE_CLASSES` vocabularies. Which edges may carry a causal
+  claim, and a DAG carved out of a graph with feedback loops that names what
+  it removed.
+- `causalphylo.backdoor` — `find_adjustment_set`, `satisfies_backdoor`,
+  `mutilated_graph`, `confounding_sensitivity`, and the `Identification` /
+  `IdentificationReason` verdict types. Pearl's backdoor criterion, reporting
+  *why* identification failed as a closed enum rather than as prose, and
+  carrying `n_near_miss_confounders` so a trivial verdict cannot be mistaken
+  for an absence of confounding.
+- Documentation at [causalphylo.neoforgelabs.tech](https://causalphylo.neoforgelabs.tech/).
+  Every `>>>` example in it runs as part of the test suite.
+
+### Changed from the NeoRx original
+
+Behaviour is unchanged. Three things were cleaned up rather than carried:
+
+- `IdentificationReason` is a `StrEnum` instead of inheriting `str` and `Enum`
+  separately. Member values and identity comparisons are identical; every
+  consumer read `.value` or compared with `is`, which was checked before the
+  change and is covered by NeoRx's own suite.
+- A test asserting that `Identification` is immutable caught a blind
+  `Exception`, which a typo would also have satisfied. It names
+  `FrozenInstanceError` now.
+- An unused import of `confounding_sensitivity` is gone. Both of its tests
+  reach it through `find_adjustment_set`; it still has no direct unit test.

causalphylo-0.1.0/LICENSE

@@ -0,0 +1,31 @@
+CausalPhylo Source Available License
+
+Copyright (c) 2026 Kelyn Paul Njeri, NeoForge Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, and distribute the Software for NON-COMMERCIAL PURPOSES ONLY,
+subject to the following conditions:
+
+1. NON-COMMERCIAL USE PERMITTED. You may use, copy, modify, merge, and
+   distribute the Software and derivative works thereof for personal,
+   academic, educational, and research purposes at no charge.
+
+2. COMMERCIAL USE PROHIBITED WITHOUT LICENCE. You may NOT use the Software,
+   or any derivative works thereof, for commercial purposes — including but
+   not limited to: selling the Software or services built on it, incorporating
+   it into commercial products, or using it to generate revenue — without
+   obtaining a separate commercial licence from the copyright holder.
+
+   To obtain a commercial licence, contact: kelyn@neoforgelabs.tech
+
+3. ATTRIBUTION. The above copyright notice and this permission notice shall
+   be included in all copies or substantial portions of the Software.
+
+4. NO WARRANTY. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+   NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+   OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+   USE OR OTHER DEALINGS IN THE SOFTWARE.

causalphylo-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.5
+Name: causalphylo
+Version: 0.1.0
+Summary: Pearl's backdoor criterion over knowledge graphs — separates edges that may carry a causal claim from those that only assert co-occurrence
+Project-URL: Homepage, https://github.com/Neoforge-Labs/causalphylo
+Project-URL: Documentation, https://causalphylo.neoforgelabs.tech/
+Project-URL: Repository, https://github.com/Neoforge-Labs/causalphylo
+Project-URL: Issues, https://github.com/Neoforge-Labs/causalphylo/issues
+Author: Kelyn Paul Njeri
+License-Expression: LicenseRef-CausalPhylo-NonCommercial
+License-File: LICENSE
+Keywords: backdoor-criterion,causal-inference,do-calculus,identification,knowledge-graph,networkx,pearl
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: networkx>=3.3
+Description-Content-Type: text/markdown
+
+# CausalPhylo
+
+> Identification over knowledge graphs, where not every edge has earned its arrow.
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/license-Non--Commercial-orange.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-causalphylo.neoforgelabs.tech-teal.svg)](https://causalphylo.neoforgelabs.tech/)
+
+**CausalPhylo** implements Pearl's backdoor criterion over
+[NetworkX](https://networkx.org) directed graphs, together with the
+admissibility rules that decide which edges may carry a causal claim in the
+first place. It was extracted from [NeoRx](https://github.com/Neoforge-Labs/neorx),
+where it is the engine behind causal drug-target identification.
+
+It has one runtime dependency: NetworkX.
+
+**Full documentation: [causalphylo.neoforgelabs.tech](https://causalphylo.neoforgelabs.tech/)**
+
+## The problem it solves
+
+A graph assembled from public sources mixes two kinds of edge.
+
+Some assert a **mechanism with a direction** — a curated regulatory
+interaction where someone has established that A acts on B. Others assert only
+that two things **occur together**: a literature co-mention, membership of a
+shared pathway, an undirected protein interaction whose arrow exists only
+because one protein landed in the first column of an API response.
+
+Running do-calculus over the second kind assumes the very thing a causal
+method is supposed to establish. So CausalPhylo partitions the edges first,
+and identification runs only on the causal-admissible subgraph. Associational
+edges are not discarded — they stop being arrows.
+
+Gene → disease edges are admitted only on genetic evidence. A germline variant
+is randomised at conception, so a genetic association carries a
+natural-experiment warrant that a co-mention does not — the Mendelian
+randomisation argument ([Davey Smith & Ebrahim, 2003](https://doi.org/10.1093/ije/dyg070),
+*Int J Epidemiol* 32:1–22). That warrant is what earns the arrow.
+
+## Install
+
+```bash
+uv pip install causalphylo
+```
+
+## Use
+
+```python
+import networkx as nx
+from causalphylo import find_adjustment_set
+
+# The textbook confounding shape: U is a common cause of X and D.
+G = nx.DiGraph()
+G.add_edge("U", "X", edge_type="activates", evidence_class="regulatory")
+G.add_edge("U", "D", edge_type="associated_with", evidence_class="genetic_association")
+G.add_edge("X", "D", edge_type="associated_with", evidence_class="genetic_association")
+
+verdict = find_adjustment_set(G, "X", "D")
+
+verdict.identifiable      # True
+verdict.adjustment_set    # ('U',)
+verdict.reason.value      # 'identifiable_by_adjustment'
+```
+
+`find_adjustment_set` takes the **full** graph. Restriction to the admissible
+subgraph and to its acyclic core happens inside, so no caller can forget it.
+
+Edges carry two attributes that the admissibility rules read: `edge_type` and
+`evidence_class`. Nothing else about your graph is assumed — CausalPhylo has no
+domain model of its own.
+
+## It tells you *why* it failed
+
+A method that reports only pass/fail gives you a pile of prose to read. These
+reasons are a closed enum, so a run's failures aggregate into a distribution:
+
+| `reason` | Meaning |
+|---|---|
+| `identifiable_by_adjustment` | A valid backdoor adjustment set was found |
+| `identifiable_trivially` | No confounder appears in the graph (see the caveat below) |
+| `no_causal_path` | No admissible directed path from treatment to outcome |
+| `cyclic_component` | Treatment or outcome sits in a feedback loop; d-separation is undefined there |
+| `no_valid_adjustment_set` | Confounders exist, but no admissible subset blocks every backdoor path |
+| `treatment_absent` / `outcome_absent` | Node is not in the admissible subgraph |
+
+**The trivial case is not a clean bill of health.** A knowledge graph is
+open-world: a missing edge is missing knowledge, not evidence of no
+confounding. So a trivial verdict carries `n_near_miss_confounders` — how many
+nodes regulate the treatment and have *some* association with the outcome that
+fell short of admissibility. A target with many near misses is fragile. This is
+the same move as an E-value in observational epidemiology: not "there is no
+confounding", but "here is how much it would take to break this".
+
+`search_truncated` reports when the subset search hit its bound
+(`MAX_ADJUSTMENT_SET_SIZE`, `MAX_CANDIDATE_POOL`) rather than exhausting the
+space. It is never hidden.
+
+## API
+
+**`causalphylo.graph_semantics`** — which edges may carry a causal claim
+
+| | |
+|---|---|
+| `is_causal_admissible(attrs)` | Whether an edge with these attributes may carry a causal claim |
+| `causal_subgraph(G)` | The subgraph of admissible edges, attributes preserved |
+| `cyclic_components(G)` | Strongly connected components with cycles, self-loops included |
+| `acyclic_core(G)` | A DAG carved out of a cyclic graph, plus the nodes removed |
+| `CAUSAL_EDGE_TYPES`, `GENETIC_EVIDENCE_CLASSES` | The admissibility vocabularies |
+
+**`causalphylo.backdoor`** — identification on the admissible subgraph
+
+| | |
+|---|---|
+| `find_adjustment_set(G, treatment, outcome)` | Search for a minimal valid adjustment set |
+| `satisfies_backdoor(G, treatment, outcome, adjustment)` | Whether `adjustment` (a frozenset) satisfies the criterion |
+| `mutilated_graph(G, treatment)` | G with edges *into* the treatment removed — the interventional graph G<sub>X&#772;</sub> |
+| `confounding_sensitivity(dag, full_graph, treatment, outcome)` | Near-miss confounder count behind a trivial verdict |
+
+Cyclic nodes are not silently repaired. `acyclic_core` removes every node in a
+feedback loop and names them in `excluded`, because `nx.is_d_separator` requires
+a DAG of the whole graph — not merely of the neighbourhood under test.
+
+## Development
+
+```bash
+uv venv && uv pip install -e . --group dev
+.venv/bin/python -m pytest
+```
+
+## Licence
+
+CausalPhylo Source Available License — non-commercial use permitted, commercial
+use requires a separate licence. See [LICENSE](LICENSE).
+
+Copyright (c) 2026 Kelyn Paul Njeri, NeoForge Labs.

causalphylo-0.1.0/README.md

@@ -0,0 +1,135 @@
+# CausalPhylo
+
+> Identification over knowledge graphs, where not every edge has earned its arrow.
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/license-Non--Commercial-orange.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-causalphylo.neoforgelabs.tech-teal.svg)](https://causalphylo.neoforgelabs.tech/)
+
+**CausalPhylo** implements Pearl's backdoor criterion over
+[NetworkX](https://networkx.org) directed graphs, together with the
+admissibility rules that decide which edges may carry a causal claim in the
+first place. It was extracted from [NeoRx](https://github.com/Neoforge-Labs/neorx),
+where it is the engine behind causal drug-target identification.
+
+It has one runtime dependency: NetworkX.
+
+**Full documentation: [causalphylo.neoforgelabs.tech](https://causalphylo.neoforgelabs.tech/)**
+
+## The problem it solves
+
+A graph assembled from public sources mixes two kinds of edge.
+
+Some assert a **mechanism with a direction** — a curated regulatory
+interaction where someone has established that A acts on B. Others assert only
+that two things **occur together**: a literature co-mention, membership of a
+shared pathway, an undirected protein interaction whose arrow exists only
+because one protein landed in the first column of an API response.
+
+Running do-calculus over the second kind assumes the very thing a causal
+method is supposed to establish. So CausalPhylo partitions the edges first,
+and identification runs only on the causal-admissible subgraph. Associational
+edges are not discarded — they stop being arrows.
+
+Gene → disease edges are admitted only on genetic evidence. A germline variant
+is randomised at conception, so a genetic association carries a
+natural-experiment warrant that a co-mention does not — the Mendelian
+randomisation argument ([Davey Smith & Ebrahim, 2003](https://doi.org/10.1093/ije/dyg070),
+*Int J Epidemiol* 32:1–22). That warrant is what earns the arrow.
+
+## Install
+
+```bash
+uv pip install causalphylo
+```
+
+## Use
+
+```python
+import networkx as nx
+from causalphylo import find_adjustment_set
+
+# The textbook confounding shape: U is a common cause of X and D.
+G = nx.DiGraph()
+G.add_edge("U", "X", edge_type="activates", evidence_class="regulatory")
+G.add_edge("U", "D", edge_type="associated_with", evidence_class="genetic_association")
+G.add_edge("X", "D", edge_type="associated_with", evidence_class="genetic_association")
+
+verdict = find_adjustment_set(G, "X", "D")
+
+verdict.identifiable      # True
+verdict.adjustment_set    # ('U',)
+verdict.reason.value      # 'identifiable_by_adjustment'
+```
+
+`find_adjustment_set` takes the **full** graph. Restriction to the admissible
+subgraph and to its acyclic core happens inside, so no caller can forget it.
+
+Edges carry two attributes that the admissibility rules read: `edge_type` and
+`evidence_class`. Nothing else about your graph is assumed — CausalPhylo has no
+domain model of its own.
+
+## It tells you *why* it failed
+
+A method that reports only pass/fail gives you a pile of prose to read. These
+reasons are a closed enum, so a run's failures aggregate into a distribution:
+
+| `reason` | Meaning |
+|---|---|
+| `identifiable_by_adjustment` | A valid backdoor adjustment set was found |
+| `identifiable_trivially` | No confounder appears in the graph (see the caveat below) |
+| `no_causal_path` | No admissible directed path from treatment to outcome |
+| `cyclic_component` | Treatment or outcome sits in a feedback loop; d-separation is undefined there |
+| `no_valid_adjustment_set` | Confounders exist, but no admissible subset blocks every backdoor path |
+| `treatment_absent` / `outcome_absent` | Node is not in the admissible subgraph |
+
+**The trivial case is not a clean bill of health.** A knowledge graph is
+open-world: a missing edge is missing knowledge, not evidence of no
+confounding. So a trivial verdict carries `n_near_miss_confounders` — how many
+nodes regulate the treatment and have *some* association with the outcome that
+fell short of admissibility. A target with many near misses is fragile. This is
+the same move as an E-value in observational epidemiology: not "there is no
+confounding", but "here is how much it would take to break this".
+
+`search_truncated` reports when the subset search hit its bound
+(`MAX_ADJUSTMENT_SET_SIZE`, `MAX_CANDIDATE_POOL`) rather than exhausting the
+space. It is never hidden.
+
+## API
+
+**`causalphylo.graph_semantics`** — which edges may carry a causal claim
+
+| | |
+|---|---|
+| `is_causal_admissible(attrs)` | Whether an edge with these attributes may carry a causal claim |
+| `causal_subgraph(G)` | The subgraph of admissible edges, attributes preserved |
+| `cyclic_components(G)` | Strongly connected components with cycles, self-loops included |
+| `acyclic_core(G)` | A DAG carved out of a cyclic graph, plus the nodes removed |
+| `CAUSAL_EDGE_TYPES`, `GENETIC_EVIDENCE_CLASSES` | The admissibility vocabularies |
+
+**`causalphylo.backdoor`** — identification on the admissible subgraph
+
+| | |
+|---|---|
+| `find_adjustment_set(G, treatment, outcome)` | Search for a minimal valid adjustment set |
+| `satisfies_backdoor(G, treatment, outcome, adjustment)` | Whether `adjustment` (a frozenset) satisfies the criterion |
+| `mutilated_graph(G, treatment)` | G with edges *into* the treatment removed — the interventional graph G<sub>X&#772;</sub> |
+| `confounding_sensitivity(dag, full_graph, treatment, outcome)` | Near-miss confounder count behind a trivial verdict |
+
+Cyclic nodes are not silently repaired. `acyclic_core` removes every node in a
+feedback loop and names them in `excluded`, because `nx.is_d_separator` requires
+a DAG of the whole graph — not merely of the neighbourhood under test.
+
+## Development
+
+```bash
+uv venv && uv pip install -e . --group dev
+.venv/bin/python -m pytest
+```
+
+## Licence
+
+CausalPhylo Source Available License — non-commercial use permitted, commercial
+use requires a separate licence. See [LICENSE](LICENSE).
+
+Copyright (c) 2026 Kelyn Paul Njeri, NeoForge Labs.

causalphylo-0.1.0/docs/CNAME

@@ -0,0 +1 @@
+causalphylo.neoforgelabs.tech

causalphylo-0.1.0/docs/admissibility.md

@@ -0,0 +1,132 @@
+# Which edges earn an arrow
+
+An arrow in a causal diagram is a claim: intervene on the tail and the head
+responds. Most edges in a knowledge graph were never asserted with that
+strength. CausalPhylo's first job is to say which ones were.
+
+## The rule
+
+An edge is causal-admissible when either:
+
+1. its `edge_type` names a **directed mechanism** — someone has asserted that
+   the source acts on the target; or
+2. it is a gene-to-disease **association backed by genetic evidence**.
+
+```python
+>>> from causalphylo import CAUSAL_EDGE_TYPES, GENETIC_EVIDENCE_CLASSES
+>>> sorted(CAUSAL_EDGE_TYPES)
+['activates', 'causes', 'downregulates', 'inhibits', 'phosphorylates',
+ 'regulates', 'upregulates']
+>>> sorted(GENETIC_EVIDENCE_CLASSES)
+['genetic_association', 'somatic_mutation']
+
+```
+
+Everything else is associational.
+
+```python
+from causalphylo import is_causal_admissible
+
+is_causal_admissible({"edge_type": "activates",       "evidence_class": "regulatory"})
+is_causal_admissible({"edge_type": "associated_with", "evidence_class": "genetic_association"})
+is_causal_admissible({"edge_type": "associated_with", "evidence_class": "literature"})
+is_causal_admissible({"edge_type": "interacts_with",  "evidence_class": "regulatory"})
+is_causal_admissible({"edge_type": "participates_in", "evidence_class": ""})
+```
+
+| Edge | Admissible |
+|---|---|
+| `activates` / `regulatory` | **True** |
+| `associated_with` / `genetic_association` | **True** |
+| `associated_with` / `literature` | False |
+| `interacts_with` / `regulatory` (STRING) | False |
+| `participates_in` (pathway membership) | False |
+
+## Why genetic evidence is the exception
+
+A germline variant is randomised at conception. A genetic association
+therefore carries a natural-experiment warrant that a co-mention does not —
+this is the Mendelian randomisation argument
+([Davey Smith & Ebrahim, 2003](https://doi.org/10.1093/ije/dyg070),
+*Int J Epidemiol* 32:1–22). That warrant is what earns the arrow.
+
+A literature co-mention earns nothing. Two genes appear in one abstract for
+reasons that include a shared assay, a shared author, and a shared review.
+
+## Why an undirected interaction earns nothing
+
+!!! note "STRING interactions are not arrows"
+    A protein–protein interaction is symmetric. When it reaches you as a
+    directed edge, the direction is an artefact of which protein the API
+    returned first. Admitting it would let the ordering of a response
+    determine a causal conclusion.
+
+## Pruning the graph
+
+`causal_subgraph` keeps the admissible edges with their attributes intact, and
+drops nodes left with no admissible edge — a node participating in no causal
+relation can be neither treatment, outcome, nor confounder.
+
+```python
+import networkx as nx
+from causalphylo import causal_subgraph
+
+G = nx.DiGraph()
+G.add_edge("U", "X",         edge_type="activates",       evidence_class="regulatory")
+G.add_edge("X", "D",         edge_type="associated_with", evidence_class="genetic_association")
+G.add_edge("P", "D",         edge_type="associated_with", evidence_class="literature")
+G.add_edge("X", "pathway:1", edge_type="participates_in", evidence_class="")
+
+sub = causal_subgraph(G)
+```
+
+```python
+sorted(G.nodes())     # ['D', 'P', 'U', 'X', 'pathway:1']
+sorted(sub.nodes())   # ['D', 'U', 'X']
+sorted(sub.edges())   # [('U', 'X'), ('X', 'D')]
+```
+
+`P` and `pathway:1` are gone. The association that linked `P` to `D` still
+exists in your own graph and can still contribute to evidence scoring — it is
+simply not an arrow here.
+
+## Feedback loops
+
+`nx.is_d_separator` requires a DAG of the **whole** graph, not merely of the
+neighbourhood under test. Biological regulatory networks are full of feedback,
+so cyclic nodes have to come out — and `acyclic_core` names the ones it
+removed rather than silently repairing them.
+
+```python
+from causalphylo import acyclic_core
+
+G = nx.DiGraph()
+G.add_edge("a", "b")   # a and b form a 2-cycle
+G.add_edge("b", "a")
+G.add_edge("b", "c")
+G.add_edge("c", "d")
+
+core = acyclic_core(G)
+```
+
+```python
+sorted(core.excluded)                             # ['a', 'b']
+sorted(core.dag.nodes())                          # ['c', 'd']
+nx.is_directed_acyclic_graph(core.dag)            # True
+```
+
+Self-loops count as cycles. A node that regulates itself is excluded on the
+same grounds.
+
+Identification involving an excluded node reports
+`cyclic_component` rather than guessing an acyclic orientation. Choosing a
+direction to break the loop would be inventing the mechanism the method is
+supposed to test.
+
+## Adapting the vocabulary
+
+The edge types and evidence classes above are frozensets of plain strings.
+If your graph speaks a different vocabulary, map it to these names when you
+build the graph. CausalPhylo deliberately has no configuration layer: the
+admissibility rule is an argument about evidence, and burying it in a settings
+file would make it look like a preference.

causalphylo-0.1.0/docs/api.md

@@ -0,0 +1,54 @@
+# API reference
+
+Everything below is re-exported from the top level, so
+`from causalphylo import find_adjustment_set` and
+`from causalphylo.backdoor import find_adjustment_set` are equivalent.
+
+## causalphylo.graph_semantics
+
+Which edges may carry a causal claim. See
+[Which edges earn an arrow](admissibility.md).
+
+::: causalphylo.graph_semantics
+    options:
+      show_root_heading: false
+      members:
+        - is_causal_admissible
+        - causal_subgraph
+        - cyclic_components
+        - acyclic_core
+        - AcyclicCore
+
+### Vocabularies
+
+`CAUSAL_EDGE_TYPES`
+:   Frozenset of `edge_type` values that assert a directed mechanism.
+
+`GENETIC_EVIDENCE_CLASSES`
+:   Frozenset of `evidence_class` values that license a gene-to-disease arrow.
+
+## causalphylo.backdoor
+
+Identification on the admissible subgraph. See
+[Identification](identification.md).
+
+::: causalphylo.backdoor
+    options:
+      show_root_heading: false
+      members:
+        - find_adjustment_set
+        - Identification
+        - IdentificationReason
+        - satisfies_backdoor
+        - mutilated_graph
+        - confounding_sensitivity
+
+### Search bounds
+
+`MAX_ADJUSTMENT_SET_SIZE`
+:   Largest adjustment set the search will consider. Default `3`.
+
+`MAX_CANDIDATE_POOL`
+:   Largest candidate pool the search will draw from. Default `20`.
+
+Reaching either bound sets `Identification.search_truncated`.