How genedx/phenopy works
Project Type and Purpose
• This is a Python-based command-line tool and library (“phenopy”) for computing semantic similarity scores between entities annotated with Human Phenotype Ontology (HPO) terms.
• It includes modules to build an annotated HPO network, compute information content (IC), run pairwise scoring (HRSS), and expose both CLI commands and a Python API.
Top-Level Architecture Components
a. CLI Layer
• Entry point: phenopy/__main__.py
• Command dispatcher (click or argparse) handles subcommands (score, etc.)
b. Core Library Modules
• build_hpo.py: generates the HPO graph, annotates it with term frequencies and optional age distributions
• network.py: constructs and manages the graph data structure (nodes=HPO terms, edges=is_a relationships)
• ic.py: computes Information Content per term based on annotation frequencies
• score.py: Scorer class implementing HRSS term-to-term and set-to-set scoring, with summarization methods (BMA, BMWA, max)
• weights.py: implements weighting logic used by BMWA
• util.py: miscellaneous utilities (e.g., parent pruning, file export)
• d2p.py, config.py: data-to-phenotype parsing and configuration loading
c. Data Storage
• Local cache in $HOME/.phenopy/data/ (obo file, annotation files, precomputed models)
• Packaged data under phenopy/data (default models, pickles)
d. External Resources
• HPO OBO file (hp.obo from HPO project)
• OMIM phenotype annotations (phenotype.hpoa)
• Optional age distribution file
Relationships and Data Flow
• User invokes phenopy score → CLI parser reads input parameters (input file, records file, threads, summarization method).
• CLI → calls build_hpo.generate_annotated_hpo_network(obo_file, phenotype_file, ages_file) → returns (hpo_network, alt2prim, disease_records).
• CLI → instantiates Scorer(hpo_network) → calls scorer.score_term_sets_basic or score_record_sets → interacts with network.py, ic.py, weights.py to compute pairwise similarity.
• Results → written to stdout or --output-file.
Architectural Patterns and Principles
• Modular separation: each major concern in its own module (builder, network, scoring, utilities).
• Lazy caching of external resources under user home directory for reproducibility.
• Single-process or multi-process parallelism (thread/ process pool in score.py).
• Test suite verifies each module in isolation (tests/test_*.py).