| """ |
| 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", |
| ] |
|
|
