if-split 0.1.0__tar.gz → 0.2.0__tar.gz

{if_split-0.1.0 → if_split-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: if-split
-Version: 0.1.0
+Version: 0.2.0
 Summary: Reproducible, date-pinned, ligand-aware train/val/test splitter for the PDB (LigandMPNN-style).
 Author: WSobo
 License: MIT
@@ -19,6 +19,10 @@ Description-Content-Type: text/markdown
 
 # IF-Split
 
+[![CI](https://github.com/WSobo/IF-Split/actions/workflows/ci.yml/badge.svg)](https://github.com/WSobo/IF-Split/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/if-split.svg)](https://pypi.org/project/if-split/)
+[![Python](https://img.shields.io/pypi/pyversions/if-split.svg)](https://pypi.org/project/if-split/)
+
 **A reproducible, date-pinned, ligand-aware train/val/test splitter for the PDB.**
 
 IF-Split borrows the *split logic* of LigandMPNN (Dauparas et al., *Nature
@@ -60,16 +64,23 @@ records and sequences. Coordinates are an optional, downstream concern.
 
 ## Install
 
-Requires Python ≥ 3.11 and [`uv`](https://docs.astral.sh/uv/). `build` needs
-only network access to RCSB — no external binaries. (The optional `mmseqs2`
-clustering backend and the optional coordinate/featurization path via `gemmi`
-are Linux-native, so run under Linux/WSL if you use them.)
+Requires Python ≥ 3.11. `build` needs only network access to RCSB — no external
+binaries.
+
+```bash
+pip install if-split          # from PyPI
+```
+
+Or for development, with [`uv`](https://docs.astral.sh/uv/):
 
 ```bash
+git clone https://github.com/WSobo/IF-Split && cd IF-Split
 uv sync          # creates .venv from uv.lock, installs deps + dev tools (ruff, pytest)
 ```
 
-`uv.lock` is committed, so environments are reproducible.
+`uv.lock` is committed, so dev environments are reproducible. (The optional
+coordinate/featurization path via `gemmi` is Linux-native, so run under
+Linux/WSL if you use `fetch`.)
 
 ## Quickstart
 
@@ -91,6 +102,9 @@ uv run if-split build --registry data/out/splits.registry.json --out data/out2
 
 # OPTIONAL: download the actual structures for a built split (see below).
 uv run if-split fetch data/out/manifest.json --split test --out data/structures
+
+# Emit a portable, shareable split spec (see "Sharing a split spec" below).
+uv run if-split spec data/out/manifest.json --name my-split --out my-split.ifsplit.yaml
 ```
 
 ### Outputs (`--out` directory)
@@ -163,7 +177,7 @@ A `build` runs eight stages; none touch coordinates.
 |---|---|---|
 | 1 — enumerate | `enumerate.py`, `rcsb.py` | RCSB Search → entry IDs; Data API (GraphQL, batched) → sequences, ligands, residue counts, cluster membership → `candidates.jsonl`. |
 | 3 — filter | `parse.py` | Drop no-protein / no-sequence / oversized entries (assembly-1 residue count vs `max_total_residues`), plus optional wwPDB validation-report quality caps (clashscore, R-free, Ramachandran/rotamer/RSRZ) — all from metadata. Every drop is logged with its reason. |
-| 4 — ligands | `ligands.py` | Tier each non-protein component `functional`/`ambiguous`/`artifact`; derive class labels (metal / small-molecule / nucleotide). Nucleotide is functional only with a verified protein↔NA assembly interface. **Annotate, never drop.** |
+| 4 — ligands | `ligands.py` | Tier each non-protein component `functional`/`ambiguous`/`artifact`; derive class labels (metal / small-molecule / nucleic-acid). `nucleic_acid` = a protein↔DNA/RNA *complex* (verified assembly interface), **not** a bound mononucleotide. **Annotate, never drop.** |
 | 5 — cluster | `cluster.py` | Group protein entities by RCSB precomputed cluster id at `identity_threshold`; canonical key = smallest member id. |
 | 6 — split | `split.py` | Deterministic hash → train/val/test; assert no cluster spans two splits; audit residual secondary-chain overlap. |
 | 7 — manifest | `manifest.py` | Emit lock + manifest + registry (all deterministic, no wall-clock fields). |
@@ -213,16 +227,30 @@ machine-readable reason, from RCSB metadata signals:
 **Holo gating (metadata-only).** Presence isn't enough. A small molecule or metal
 is `functional` only if RCSB reports it *contacting* the protein (`bound_components`)
 or it has a measured binding affinity; an unbound one is `ambiguous`. A DNA/RNA
-chain is `functional` *nucleotide* only when the biological assembly has a verified
-protein↔nucleic-acid interface (`rcsb_interface_info.polymer_composition == "Protein/NA"`)
-— a co-deposited but non-contacting oligo is reported `ambiguous`, never silently
+chain is `functional` `nucleic_acid` only when the biological assembly has a verified
+protein↔nucleic-acid interface (`num_prot_na_interface_entities > 0`) — a
+co-deposited but non-contacting oligo is reported `ambiguous`, never silently
 labelled. (Interfaces are RCSB-computed metadata, available for X-ray *and* cryo-EM,
 so no coordinates are downloaded.)
 
+> The `nucleic_acid` class is the protein–nucleic-acid **complex** category (DNA/RNA
+> polymer chains), matching LigandMPNN's "nucleotide" split. Bound *mononucleotide*
+> ligands (ATP, GTP, NAD, SAM, …) are not this class — they fall under
+> `small_molecule`.
+
 The His-tag/Ni curation catches a known blemish in the LigandMPNN metal set:
 structures whose only "metal site" is a poly-His tag chelating Ni/Co from
-affinity purification. Live examples from a real build: `101M → {HEM:
-functional, SO4: artifact}`, `102L → {BME: artifact, CL: artifact}`.
+affinity purification. A poly-His run anywhere — or a short run at a chain
+terminus (`histag_terminal_min_run`, catching 6×His tags left partial by
+unmodeled or trimmed residues) — flags the entry's Ni/Co as an `artifact`.
+
+But a real audit showed the deeper issue: **~96% of lone Ni/Co entries have no
+His-tag in the deposited sequence at all** (the tag is trimmed from the SEQRES
+record, not just unmodeled), so a sequence scan can never see it. So even with no
+detectable tag, a *lone* Ni/Co (the entry's only metal) with no measured affinity
+is demoted from `functional` to `ambiguous` — reported, not labelled. Real metals
+(Zn, Mg, Fe, …), and Ni/Co backed by an affinity or sitting alongside a genuine
+metal, are untouched. On the full PDB this re-tiers ~2.7% of the metal set.
 
 Crucially, **the structure always stays in its split** — a protein with a junk
 ion is still a good backbone; we just don't label the junk. A consumer wanting
@@ -255,11 +283,54 @@ for epoch in range(3):
     batch_ids = ds.train.sample_by_cluster(seed=epoch)
 ```
 
+## Sharing a split spec
+
+The config **is** the shareable recipe. Everything that affects the split lives in
+one small YAML file with a content hash, so you can hand someone that file and they
+reproduce your methodology exactly — like `params.yaml` in DVC. `if-split spec`
+emits a portable, self-identifying version from any build or config:
+
+```bash
+# Extract a stand-alone spec from a finished build (config is embedded in the manifest):
+uv run if-split spec data/out/manifest.json --name "my-split" --author "you" \
+    --out my-split.ifsplit.yaml
+
+# Anyone reproduces your split from just that file:
+uv run if-split build --config my-split.ifsplit.yaml --out their/out
+```
+
+The emitted file carries a `spec:` header that announces what it is and pins the
+expected hash:
+
+```yaml
+spec:
+  ifsplit_spec: ifsplit/config@1          # schema id — the file says what it is
+  name: my-split
+  author: you
+  created_with: if-split 0.1.0
+  expected_config_hash: 3b63318286fd2ac4994f34d10936be05
+snapshot_date: '2026-05-31'
+resolution_max_A: 3.5
+# ... all output-affecting settings ...
+```
+
+On load, if `expected_config_hash` no longer matches the settings (someone edited
+them after stamping), IF-Split warns. The `spec:` metadata is **excluded from the
+hash**, so name/author/description never change the split identity — two specs that
+differ only in their labels produce byte-identical outputs.
+
+| Artifact | Question it answers | Size |
+|---|---|--:|
+| `*.ifsplit.yaml` (or `config.yaml`) | *"How did you make this split?"* — the recipe | ~KB |
+| `manifest.json` | *"What's in it?"* — counts, provenance, file index | ~KB |
+| `dataset.lock` | *"Reproduce the exact bytes"* — pins entry set + candidates SHA | ~MB |
+
 ## Configuration
 
 Everything that affects the output lives in one YAML file
 ([`config/default.yaml`](config/default.yaml)); its canonical hash is embedded
-in every manifest, so two builds with the same hash used identical settings.
+in every manifest, so two builds with the same hash used identical settings. It
+doubles as a shareable **split spec** — see [Sharing a split spec](#sharing-a-split-spec).
 
 | Key | Default | Meaning |
 |---|---|---|
@@ -270,8 +341,9 @@ in every manifest, so two builds with the same hash used identical settings.
 | `excluded_het` | waters + common ions | Extra components forced to `artifact`. |
 | `use_biological_assembly` | `true` | Count residues from assembly 1, not the deposited asymmetric unit. |
 | `purification_metals` | `[NI, CO]` | Metals treated as IMAC tags; `[]` disables the heuristic. |
-| `histag_min_run` | `6` | His-run length that marks a purification tag. |
-| `exclude_purification_artifacts` | `true` | Demote His-tag metals to `artifact`. |
+| `histag_min_run` | `6` | His-run length (anywhere) that marks a purification tag. |
+| `histag_terminal_min_run` | `3` | Shorter His-run at a chain terminus that also counts as a tag (partial/unmodeled 6×His). |
+| `exclude_purification_artifacts` | `true` | Demote His-tag metals to `artifact`; lone uncorroborated Ni/Co → `ambiguous`. |
 | `identity_threshold` | `0.30` | Clustering cutoff (RCSB levels: 30/50/70/90/95/100). |
 | `clustering_backend` | `precomputed` | `precomputed` (RCSB clusters) or `mmseqs2` (run your own). |
 | `split_fractions` | 0.80 / 0.10 / 0.10 | train / val / test. |

{if_split-0.1.0 → if_split-0.2.0}/README.md

@@ -1,5 +1,9 @@
 # IF-Split
 
+[![CI](https://github.com/WSobo/IF-Split/actions/workflows/ci.yml/badge.svg)](https://github.com/WSobo/IF-Split/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/if-split.svg)](https://pypi.org/project/if-split/)
+[![Python](https://img.shields.io/pypi/pyversions/if-split.svg)](https://pypi.org/project/if-split/)
+
 **A reproducible, date-pinned, ligand-aware train/val/test splitter for the PDB.**
 
 IF-Split borrows the *split logic* of LigandMPNN (Dauparas et al., *Nature
@@ -41,16 +45,23 @@ records and sequences. Coordinates are an optional, downstream concern.
 
 ## Install
 
-Requires Python ≥ 3.11 and [`uv`](https://docs.astral.sh/uv/). `build` needs
-only network access to RCSB — no external binaries. (The optional `mmseqs2`
-clustering backend and the optional coordinate/featurization path via `gemmi`
-are Linux-native, so run under Linux/WSL if you use them.)
+Requires Python ≥ 3.11. `build` needs only network access to RCSB — no external
+binaries.
+
+```bash
+pip install if-split          # from PyPI
+```
+
+Or for development, with [`uv`](https://docs.astral.sh/uv/):
 
 ```bash
+git clone https://github.com/WSobo/IF-Split && cd IF-Split
 uv sync          # creates .venv from uv.lock, installs deps + dev tools (ruff, pytest)
 ```
 
-`uv.lock` is committed, so environments are reproducible.
+`uv.lock` is committed, so dev environments are reproducible. (The optional
+coordinate/featurization path via `gemmi` is Linux-native, so run under
+Linux/WSL if you use `fetch`.)
 
 ## Quickstart
 
@@ -72,6 +83,9 @@ uv run if-split build --registry data/out/splits.registry.json --out data/out2
 
 # OPTIONAL: download the actual structures for a built split (see below).
 uv run if-split fetch data/out/manifest.json --split test --out data/structures
+
+# Emit a portable, shareable split spec (see "Sharing a split spec" below).
+uv run if-split spec data/out/manifest.json --name my-split --out my-split.ifsplit.yaml
 ```
 
 ### Outputs (`--out` directory)
@@ -144,7 +158,7 @@ A `build` runs eight stages; none touch coordinates.
 |---|---|---|
 | 1 — enumerate | `enumerate.py`, `rcsb.py` | RCSB Search → entry IDs; Data API (GraphQL, batched) → sequences, ligands, residue counts, cluster membership → `candidates.jsonl`. |
 | 3 — filter | `parse.py` | Drop no-protein / no-sequence / oversized entries (assembly-1 residue count vs `max_total_residues`), plus optional wwPDB validation-report quality caps (clashscore, R-free, Ramachandran/rotamer/RSRZ) — all from metadata. Every drop is logged with its reason. |
-| 4 — ligands | `ligands.py` | Tier each non-protein component `functional`/`ambiguous`/`artifact`; derive class labels (metal / small-molecule / nucleotide). Nucleotide is functional only with a verified protein↔NA assembly interface. **Annotate, never drop.** |
+| 4 — ligands | `ligands.py` | Tier each non-protein component `functional`/`ambiguous`/`artifact`; derive class labels (metal / small-molecule / nucleic-acid). `nucleic_acid` = a protein↔DNA/RNA *complex* (verified assembly interface), **not** a bound mononucleotide. **Annotate, never drop.** |
 | 5 — cluster | `cluster.py` | Group protein entities by RCSB precomputed cluster id at `identity_threshold`; canonical key = smallest member id. |
 | 6 — split | `split.py` | Deterministic hash → train/val/test; assert no cluster spans two splits; audit residual secondary-chain overlap. |
 | 7 — manifest | `manifest.py` | Emit lock + manifest + registry (all deterministic, no wall-clock fields). |
@@ -194,16 +208,30 @@ machine-readable reason, from RCSB metadata signals:
 **Holo gating (metadata-only).** Presence isn't enough. A small molecule or metal
 is `functional` only if RCSB reports it *contacting* the protein (`bound_components`)
 or it has a measured binding affinity; an unbound one is `ambiguous`. A DNA/RNA
-chain is `functional` *nucleotide* only when the biological assembly has a verified
-protein↔nucleic-acid interface (`rcsb_interface_info.polymer_composition == "Protein/NA"`)
-— a co-deposited but non-contacting oligo is reported `ambiguous`, never silently
+chain is `functional` `nucleic_acid` only when the biological assembly has a verified
+protein↔nucleic-acid interface (`num_prot_na_interface_entities > 0`) — a
+co-deposited but non-contacting oligo is reported `ambiguous`, never silently
 labelled. (Interfaces are RCSB-computed metadata, available for X-ray *and* cryo-EM,
 so no coordinates are downloaded.)
 
+> The `nucleic_acid` class is the protein–nucleic-acid **complex** category (DNA/RNA
+> polymer chains), matching LigandMPNN's "nucleotide" split. Bound *mononucleotide*
+> ligands (ATP, GTP, NAD, SAM, …) are not this class — they fall under
+> `small_molecule`.
+
 The His-tag/Ni curation catches a known blemish in the LigandMPNN metal set:
 structures whose only "metal site" is a poly-His tag chelating Ni/Co from
-affinity purification. Live examples from a real build: `101M → {HEM:
-functional, SO4: artifact}`, `102L → {BME: artifact, CL: artifact}`.
+affinity purification. A poly-His run anywhere — or a short run at a chain
+terminus (`histag_terminal_min_run`, catching 6×His tags left partial by
+unmodeled or trimmed residues) — flags the entry's Ni/Co as an `artifact`.
+
+But a real audit showed the deeper issue: **~96% of lone Ni/Co entries have no
+His-tag in the deposited sequence at all** (the tag is trimmed from the SEQRES
+record, not just unmodeled), so a sequence scan can never see it. So even with no
+detectable tag, a *lone* Ni/Co (the entry's only metal) with no measured affinity
+is demoted from `functional` to `ambiguous` — reported, not labelled. Real metals
+(Zn, Mg, Fe, …), and Ni/Co backed by an affinity or sitting alongside a genuine
+metal, are untouched. On the full PDB this re-tiers ~2.7% of the metal set.
 
 Crucially, **the structure always stays in its split** — a protein with a junk
 ion is still a good backbone; we just don't label the junk. A consumer wanting
@@ -236,11 +264,54 @@ for epoch in range(3):
     batch_ids = ds.train.sample_by_cluster(seed=epoch)
 ```
 
+## Sharing a split spec
+
+The config **is** the shareable recipe. Everything that affects the split lives in
+one small YAML file with a content hash, so you can hand someone that file and they
+reproduce your methodology exactly — like `params.yaml` in DVC. `if-split spec`
+emits a portable, self-identifying version from any build or config:
+
+```bash
+# Extract a stand-alone spec from a finished build (config is embedded in the manifest):
+uv run if-split spec data/out/manifest.json --name "my-split" --author "you" \
+    --out my-split.ifsplit.yaml
+
+# Anyone reproduces your split from just that file:
+uv run if-split build --config my-split.ifsplit.yaml --out their/out
+```
+
+The emitted file carries a `spec:` header that announces what it is and pins the
+expected hash:
+
+```yaml
+spec:
+  ifsplit_spec: ifsplit/config@1          # schema id — the file says what it is
+  name: my-split
+  author: you
+  created_with: if-split 0.1.0
+  expected_config_hash: 3b63318286fd2ac4994f34d10936be05
+snapshot_date: '2026-05-31'
+resolution_max_A: 3.5
+# ... all output-affecting settings ...
+```
+
+On load, if `expected_config_hash` no longer matches the settings (someone edited
+them after stamping), IF-Split warns. The `spec:` metadata is **excluded from the
+hash**, so name/author/description never change the split identity — two specs that
+differ only in their labels produce byte-identical outputs.
+
+| Artifact | Question it answers | Size |
+|---|---|--:|
+| `*.ifsplit.yaml` (or `config.yaml`) | *"How did you make this split?"* — the recipe | ~KB |
+| `manifest.json` | *"What's in it?"* — counts, provenance, file index | ~KB |
+| `dataset.lock` | *"Reproduce the exact bytes"* — pins entry set + candidates SHA | ~MB |
+
 ## Configuration
 
 Everything that affects the output lives in one YAML file
 ([`config/default.yaml`](config/default.yaml)); its canonical hash is embedded
-in every manifest, so two builds with the same hash used identical settings.
+in every manifest, so two builds with the same hash used identical settings. It
+doubles as a shareable **split spec** — see [Sharing a split spec](#sharing-a-split-spec).
 
 | Key | Default | Meaning |
 |---|---|---|
@@ -251,8 +322,9 @@ in every manifest, so two builds with the same hash used identical settings.
 | `excluded_het` | waters + common ions | Extra components forced to `artifact`. |
 | `use_biological_assembly` | `true` | Count residues from assembly 1, not the deposited asymmetric unit. |
 | `purification_metals` | `[NI, CO]` | Metals treated as IMAC tags; `[]` disables the heuristic. |
-| `histag_min_run` | `6` | His-run length that marks a purification tag. |
-| `exclude_purification_artifacts` | `true` | Demote His-tag metals to `artifact`. |
+| `histag_min_run` | `6` | His-run length (anywhere) that marks a purification tag. |
+| `histag_terminal_min_run` | `3` | Shorter His-run at a chain terminus that also counts as a tag (partial/unmodeled 6×His). |
+| `exclude_purification_artifacts` | `true` | Demote His-tag metals to `artifact`; lone uncorroborated Ni/Co → `ambiguous`. |
 | `identity_threshold` | `0.30` | Clustering cutoff (RCSB levels: 30/50/70/90/95/100). |
 | `clustering_backend` | `precomputed` | `precomputed` (RCSB clusters) or `mmseqs2` (run your own). |
 | `split_fractions` | 0.80 / 0.10 / 0.10 | train / val / test. |

{if_split-0.1.0 → if_split-0.2.0}/config/default.yaml

@@ -14,11 +14,19 @@ use_biological_assembly: true      # biounits, as in LigandMPNN (assembly 1)
 # Curation: purification-artifact detection (Stage 4). A poly-His tag that
 # coordinates Ni/Co is an artifact of affinity purification, not a biological
 # metal site — a known blemish in the LigandMPNN metal set. An entry whose only
-# metal is one of these AND that has a His-tag of >= histag_min_run residues is
-# flagged, and (by default) its purification metal is dropped from the metal
-# class. Set purification_metals: [] to disable.
+# metal is a purification metal AND that carries a His-tag (a >= histag_min_run
+# run anywhere, OR a >= histag_terminal_min_run run at a chain terminus — to
+# catch 6xHis tags left partial by unmodeled/trimmed residues) is flagged as an
+# artifact. Set purification_metals: [] to disable.
+#
+# Even without a detectable tag, a *lone* Ni/Co with no measured affinity is
+# demoted from `functional` to `ambiguous` (reported, not labelled): ~96% of
+# lone Ni/Co in the PDB have no His-tag in the deposited sequence, so a bare
+# contact can't be trusted as a biological metal site. Real metals (Zn, Mg, Fe,
+# Mn, …) and Ni/Co alongside another real metal or with affinity are unaffected.
 purification_metals: ["NI", "CO"]
 histag_min_run: 6
+histag_terminal_min_run: 3
 exclude_purification_artifacts: true
 
 identity_threshold: 0.30           # clustering cutoff (Data API levels: 30/50/70/90/95/100)
@@ -33,7 +41,7 @@ seed: 0
 # components (never individual entries -> no leakage) into test, in deterministic
 # hash order, skipping registry-pinned components (growth stays stable). A floor
 # larger than the available supply is met as far as possible; the shortfall is
-# reported in the manifest, not forced. Example: {metal: 500, nucleotide: 200}
+# reported in the manifest, not forced. Example: {metal: 500, nucleic_acid: 200}
 test_min_per_class: {}
 
 # Quality filters (Stage 3) — wwPDB validation-report metrics, fetched as

{if_split-0.1.0 → if_split-0.2.0}/examples/IF-Split-2026.05.31/README.md

@@ -18,7 +18,7 @@ uv run if-split build --config examples/IF-Split-2026.05.31/config.yaml --out da
 | [`test.json`](test.json) | 100 KB | test-set PDB ids (all of them) |
 | [`test/metal_test.json`](test/metal_test.json) | 36 KB | test ids with a functional **metal** site |
 | [`test/small_molecule_test.json`](test/small_molecule_test.json) | 28 KB | test ids with a functional **small molecule** |
-| [`test/nucleotide_test.json`](test/nucleotide_test.json) | 8 KB | test ids that are protein↔**nucleic-acid** complexes |
+| [`test/nucleic_acid_test.json`](test/nucleic_acid_test.json) | 8 KB | test ids that are protein↔**nucleic-acid** complexes (DNA/RNA chains) |
 | [`manifest.json`](manifest.json) | 4 KB | provenance: config, counts, clustering stats, file index |
 | [`config.yaml`](config.yaml) | — | the exact config used (= `config/default.yaml`, cutoff pinned) |
 | [`STATS.txt`](STATS.txt) | — | `if-split stats` output |
@@ -50,16 +50,16 @@ output).
 
 ## Headline numbers
 
-- **223,422** candidates (X-ray + EM, ≤ 3.5 Å, released ≤ 2026-05-31)
-- **214,794 kept** — dropped 3,078 no-protein, 5,550 over-size (≥ 6000 residues)
-- **34,222** raw RCSB sequence clusters @ 30% identity → **19,587 leakage-safe
-  components** after union-find merged **38,834** multi-chain bridging entries
+- **223,419** candidates (X-ray + EM, ≤ 3.5 Å, released ≤ 2026-05-31)
+- **214,791 kept** — dropped 3,078 no-protein, 5,550 over-size (≥ 6000 residues)
+- **34,222** raw RCSB sequence clusters @ 30% identity → **19,589 leakage-safe
+  components** after union-find merged **38,832** multi-chain bridging entries
 
 | Split | Entries | Components | Component % |
 |---|--:|--:|--:|
-| train | 188,672 | 15,613 | 79.7% |
-| val   |  13,726 |  1,993 | 10.2% |
-| test  |  12,396 |  1,981 | 10.1% |
+| train | 188,662 | 15,615 | 79.7% |
+| val   |  13,720 |  1,992 | 10.2% |
+| test  |  12,409 |  1,982 | 10.1% |
 
 **The split is balanced on sequence *components*, not entry counts** — that's why
 train holds ~88% of entries (redundant families like lysozyme carry many entries
@@ -68,13 +68,17 @@ per component). Splitting on components is what prevents cross-split leakage; us
 
 ## Curation highlights (holo-gated, annotate-never-destroy)
 
-- **Test set, functional tier:** metal 4,099 · small-molecule 3,530 · nucleotide 586
-- **Test set, ambiguous (reported, not labelled):** small-molecule 3,596 · metal 73 · nucleotide 1
-  - The small-molecule ambiguous count ≈ the functional one: roughly half of
-    bound-looking small molecules aren't corroborated by contact or a measured
-    affinity, so they're flagged rather than silently labelled.
-- **404** His-tag/Ni(Co) purification artifacts flagged and demoted from the metal
-  class — the LigandMPNN metal-set blemish, caught automatically.
+- **Test set, functional tier:** metal 4,012 · small-molecule 6,713 · nucleic-acid 586
+- **Test set, ambiguous (reported, not labelled):** small-molecule 419 · metal 166 · nucleic-acid 1
+  - Functional small molecules far exceed ambiguous (6,713 vs 419): the
+    `is_subject_of_investigation` gate recovers non-covalently bound cofactors
+    (FAD/NAD/FMN/NADP) and inhibitors that the bond-based contact field misses.
+  - The metal ambiguous count includes lone, uncorroborated Ni/Co (likely IMAC
+    artifacts whose His-tag is absent from the deposited sequence) — demoted from
+    functional, not dropped.
+- **415** His-tag/Ni(Co) purification artifacts flagged and demoted from the metal
+  class — the LigandMPNN metal-set blemish, caught automatically (full His run or
+  a partial terminal tag).
 
 Every structure stays in its split regardless of ligand quality; only the labels
 and confidence tiers change.

if_split-0.2.0/examples/IF-Split-2026.05.31/STATS.txt

@@ -0,0 +1,20 @@
+IF-Split-2026.05.31  (config 3b63318286fd2ac4994f34d10936be05)
+  candidates: 223419  kept: 214791  dropped: 8628
+    - no_protein_entity: 3078
+    - too_large: 5550
+  clustering: precomputed @ 30%  components=19589 (from 34222 raw)  multichain=38832
+  splits (entries / components):
+    train:  188662 entries    15615 components
+    val  :   13720 entries     1992 components
+    test :   12409 entries     1982 components
+  test set by ligand class (functional tier):
+    metal: 4012
+    nucleic_acid: 586
+    small_molecule: 6713
+  test set ambiguous (reported, not labelled):
+    metal: 166
+    nucleic_acid: 1
+    small_molecule: 419
+  His-tag/Ni purification artifacts flagged: 415
+  split files: test.json, train.json, val.json
+  per-class test files: test/metal_test.json, test/nucleic_acid_test.json, test/small_molecule_test.json

{if_split-0.1.0 → if_split-0.2.0}/examples/IF-Split-2026.05.31/manifest.json

@@ -1,13 +1,13 @@
 {
   "candidates": {
-    "count": 223422,
-    "sha256": "62116f0183c2eb9a1c3bf69a36331748b920a1b9e182c65eae7518b0c86336ad"
+    "count": 223419,
+    "sha256": "302da149ddc0bc8ef62e92fe8f249146f9f37119fca7ea4ab5fbe26f3c6b15d7"
   },
   "clustering": {
     "backend": "precomputed",
     "identity": 30,
-    "multichain_entries": 38834,
-    "n_clusters": 19587,
+    "multichain_entries": 38832,
+    "n_clusters": 19589,
     "n_raw_clusters": 34222,
     "unclustered_entries": 316
   },
@@ -26,6 +26,7 @@
       "ELECTRON MICROSCOPY"
     ],
     "histag_min_run": 6,
+    "histag_terminal_min_run": 3,
     "identity_threshold": 0.3,
     "ligand_context_radius_A": 8.0,
     "max_clashscore": null,
@@ -49,9 +50,10 @@
       "val": 0.1
     },
     "split_salt": "snapsplit-v1",
+    "test_min_per_class": {},
     "use_biological_assembly": true
   },
-  "config_hash": "eaa0d1757f53cb929794c21e7d47fcf4",
+  "config_hash": "3b63318286fd2ac4994f34d10936be05",
   "dataset_version": "IF-Split-2026.05.31",
   "files": {
     "clusters": "clusters.json",
@@ -64,7 +66,7 @@
     },
     "test_by_class": {
       "metal": "test/metal_test.json",
-      "nucleotide": "test/nucleotide_test.json",
+      "nucleic_acid": "test/nucleic_acid_test.json",
       "small_molecule": "test/small_molecule_test.json"
     }
   },
@@ -74,56 +76,57 @@
       "too_large": 5550
     },
     "dropped": 8628,
-    "kept": 214794
+    "kept": 214791
   },
   "if_split_version": "0.1.0",
   "ligands": {
-    "n_purification_artifacts": 404
+    "n_purification_artifacts": 415
   },
   "manifest_schema": "if-split/manifest@2",
   "splits": {
     "cluster_counts": {
-      "test": 1981,
-      "train": 15613,
-      "val": 1993
+      "test": 1982,
+      "train": 15615,
+      "val": 1992
     },
     "entry_counts": {
-      "test": 12396,
-      "train": 188672,
-      "val": 13726
+      "test": 12409,
+      "train": 188662,
+      "val": 13720
     },
     "per_split_ambiguous_counts": {
       "test": {
-        "metal": 73,
-        "nucleotide": 1,
-        "small_molecule": 3596
+        "metal": 166,
+        "nucleic_acid": 1,
+        "small_molecule": 419
       },
       "train": {
-        "metal": 1233,
-        "nucleotide": 11,
-        "small_molecule": 58418
+        "metal": 2061,
+        "nucleic_acid": 11,
+        "small_molecule": 6144
       },
       "val": {
-        "metal": 54,
-        "small_molecule": 4059
+        "metal": 562,
+        "small_molecule": 514
       }
     },
     "per_split_class_counts": {
       "test": {
-        "metal": 4099,
-        "nucleotide": 586,
-        "small_molecule": 3530
+        "metal": 4012,
+        "nucleic_acid": 586,
+        "small_molecule": 6713
       },
       "train": {
-        "metal": 55952,
-        "nucleotide": 9948,
-        "small_molecule": 50497
+        "metal": 55113,
+        "nucleic_acid": 9948,
+        "small_molecule": 102762
       },
       "val": {
-        "metal": 4535,
-        "nucleotide": 539,
-        "small_molecule": 3147
+        "metal": 4019,
+        "nucleic_acid": 539,
+        "small_molecule": 6692
       }
-    }
+    },
+    "test_minimum_shortfalls": {}
   }
 }