# genedx/phenopy architecture

> Architecture diagram of the GitHub repository genedx/phenopy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/genedx/phenopy
- Repository: https://github.com/genedx/phenopy

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: CLI/API
    CLI["CLI: phenopy/__main__.py"]:::cli
    Config["Config Loader: config.py"]:::core
    D2P["Data-to-Phenotype Parser: d2p.py"]:::core

    %% Middle Layer: Core Processing Modules
    subgraph "Core Library Modules"
        direction TB
        Build["HPO Network Builder: build_hpo.py"]:::core
        Network["Graph Manager: network.py"]:::core
        IC["Information Content: ic.py"]:::core
        Weights["Weighting Logic: weights.py"]:::core
        Util["Utilities: util.py"]:::core
        Score["HRSS Scorer: score.py\n(--threads)"]:::core
    end

    %% Bottom Layer: Data Stores & External
    subgraph "Data & External Resources"
        direction TB
        DataStore["Packaged Data Models: phenopy/data/"]:::store
        subgraph "External Resources"
            direction TB
            OBO["HPO OBO File: hp.obo"]:::external
            HPOA["OMIM Annotations: phenotype.hpoa"]:::external
            Age["Age Distribution: phenotype_age.tsv"]:::external
        end
    end

    %% Development & Validation Zone
    subgraph "Development & Validation"
        direction TB
        TestIC["tests/test_ic.py"]:::dev
        TestNet["tests/test_network.py"]:::dev
        TestScore["tests/test_score.py"]:::dev
        TestUtil["tests/test_util.py"]:::dev
        TestWeights["tests/test_weights.py"]:::dev
        Notebooks["notebooks/clustering.ipynb"]:::dev
    end

    %% Connections: CLI Layer to Core
    CLI -->|"load config"| Config
    CLI -->|"parse data"| D2P
    CLI -->|"init network"| Build
    CLI -->|"invoke scorer"| Score

    %% Build flow
    Build -->|"construct graph"| Network
    Network -->|"nodes/edges"| IC
    IC -->|"IC values"| Weights
    Weights -->|"weights logic"| Score

    %% Score interactions
    Score -->|"uses graph"| Network
    Score -->|"uses IC"| IC
    Score -->|"uses weights"| Weights
    Score -->|"util funcs"| Util

    %% Data interactions
    Build -->|"cache models"| DataStore
    Score -->|"read/write cache"| DataStore
    Build -->|"reads"| OBO
    Build -->|"reads"| HPOA
    Build -->|"reads"| Age

    %% Output
    Score -->|"results→stdout/file"| CLI

    %% Development connections
    TestIC --> IC
    TestNet --> Network
    TestScore --> Score
    TestUtil --> Util
    TestWeights --> Weights
    Notebooks --> Score

    %% Click Events
    click CLI "https://github.com/genedx/phenopy/blob/master/phenopy/__main__.py"
    click Config "https://github.com/genedx/phenopy/blob/master/phenopy/config.py"
    click D2P "https://github.com/genedx/phenopy/blob/master/phenopy/d2p.py"
    click Build "https://github.com/genedx/phenopy/blob/master/phenopy/build_hpo.py"
    click Network "https://github.com/genedx/phenopy/blob/master/phenopy/network.py"
    click IC "https://github.com/genedx/phenopy/blob/master/phenopy/ic.py"
    click Weights "https://github.com/genedx/phenopy/blob/master/phenopy/weights.py"
    click Util "https://github.com/genedx/phenopy/blob/master/phenopy/util.py"
    click Score "https://github.com/genedx/phenopy/blob/master/phenopy/score.py"
    click DataStore "https://github.com/genedx/phenopy/tree/master/phenopy/data/"
    click TestIC "https://github.com/genedx/phenopy/blob/master/tests/test_ic.py"
    click TestNet "https://github.com/genedx/phenopy/blob/master/tests/test_network.py"
    click TestScore "https://github.com/genedx/phenopy/blob/master/tests/test_score.py"
    click TestUtil "https://github.com/genedx/phenopy/blob/master/tests/test_util.py"
    click TestWeights "https://github.com/genedx/phenopy/blob/master/tests/test_weights.py"
    click OBO "https://github.com/genedx/phenopy/blob/master/tests/data/hp.obo"
    click HPOA "https://github.com/genedx/phenopy/blob/master/tests/data/phenotype.hpoa"
    click Age "https://github.com/genedx/phenopy/blob/master/tests/data/phenotype_age.tsv"

    %% Styles
    classDef cli fill:#e0f7e9,stroke:#2e7d32,stroke-width:2px
    classDef core fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef store fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef external fill:#eceff1,stroke:#607d8b,stroke-width:2px,stroke-dasharray: 5 5
    classDef dev fill:#f5f5f5,stroke:#9e9e9e,stroke-width:1px,stroke-dasharray: 2 2
```
