scripts/generate_hgnc_cache.py

#!/usr/bin/env python3
"""
Regenerate resources/semantic/hgnc_cache.tsv from the CollecTRI network.

The cache is the universe of TF labels that can appear in CollecTRI-based TF
enrichment output. It is consumed by src/semantic/gene_symbols.py to classify
regulator labels as genuine gene symbols (vs unresolved). Complex/family labels
(AP1, NFKB) are intentionally excluded — they are handled earlier in
classify_regulator_label() via resources/semantic/regulator_overrides.yaml.

Run from the repo root:  python scripts/generate_hgnc_cache.py
Requires decoupler and a network connection (fetches CollecTRI from OmniPath).
"""

from __future__ import annotations

from pathlib import Path

import decoupler as dc

# Complex/family labels classified via regulator_overrides.yaml, not as genes.
_EXCLUDE = {"AP1", "NFKB"}

_OUT_PATH = Path(__file__).parent.parent / "resources" / "semantic" / "hgnc_cache.tsv"


def main() -> None:
    net = dc.op.collectri(organism="human")
    symbols = sorted(s for s in net["source"].unique() if s.upper() not in _EXCLUDE)

    lines = [
        "# CollecTRI source transcription factors (HGNC symbols)",
        f'# Generated from decoupler.op.collectri(organism="human"), decoupler {dc.__version__}',
        "# Source label universe for TF enrichment; complex/family labels (AP1, NFKB)",
        "# are intentionally excluded — they are classified via regulator_overrides.yaml.",
        "# Regenerate with scripts/generate_hgnc_cache.py",
        "symbol",
        *symbols,
    ]
    _OUT_PATH.write_text("\n".join(lines) + "\n", encoding="utf-8")
    print(f"Wrote {len(symbols)} symbols to {_OUT_PATH}")


if __name__ == "__main__":
    main()