File size: 2,284 Bytes
bfe6079 c3b49d6 bfe6079 c3b49d6 bfe6079 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 | """
Semantic and entity annotation layer for DecoupleRpy results.
Problem this solves
-------------------
Enrichment tools (CollecTRI, PROGENy, Hallmark) return labels that are not
all the same entity type. CollecTRI TF enrichment may return individual gene
symbols (HIF1A, JUN) alongside complex/family/regulon labels (AP1, NFKB).
Downstream reporting must distinguish these — AP1 is not a single gene.
Architecture
------------
schemas.py EntityAnnotation dataclass — the common return type for all
classifiers. JSON-serializable via .to_dict().
gene_symbols.py normalize_gene_symbol() — local check against a seed set of
known HGNC-like symbols. Returns resolved/unresolved.
regulators.py classify_regulator_label() — routes via regulator_overrides.yaml
first, then gene_symbols, then marks unresolved.
gene_sets.py classify_gene_set_label() — Hallmark/PROGENy pattern matching
plus gene_set_overrides.yaml.
result_annotation.py
annotate_result_entities() — adds semantic annotation columns
to a results DataFrame. The main entry point for MCP tools.
semantic_audit.py semantic_audit() — summarises an annotated DataFrame: entity
type counts, unresolved labels, warnings, mixed-type flag.
When to use this layer
----------------------
Call annotate_result_entities() on any enrichment result DataFrame before
returning it to the agent or user. Call semantic_audit() to generate a
reporting note that the agent can include in its final summary.
Static resources
----------------
resources/semantic/regulator_overrides.yaml — known complex/family labels
resources/semantic/gene_set_overrides.yaml — known gene set labels
"""
from .gene_sets import classify_gene_set_label
from .gene_symbols import normalize_gene_symbol
from .regulators import classify_regulator_label
from .result_annotation import annotate_result_entities
from .schemas import EntityAnnotation
from .semantic_audit import semantic_audit
__all__ = [
"EntityAnnotation",
"normalize_gene_symbol",
"classify_regulator_label",
"classify_gene_set_label",
"annotate_result_entities",
"semantic_audit",
]
|