# evotec-isrd/gnn-morphmap architecture

> Architecture diagram of the GitHub repository evotec-isrd/gnn-morphmap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evotec-isrd/gnn-morphmap
- Repository: https://github.com/evotec-isrd/gnn-morphmap

## Overview

##### Main Components
a. Data Input & External Dependencies:
- Data Folder: Contains essential input data files (e.g., drkg.tsv, GOannot.tsv, pathways.tsv, orf and crispr scores, similarity CSVs).
- External Data & Models: Pre-trained models and data objects (in trained_models) as well as external data sources (links to Google Drive and Zenodo) informing the experiments.
b. Configuration Management:
- Configurations Folder: Holds the configuration files (YAML files) which define the various prediction tasks (gene_bp, gene_cc, gene_mf, gene_pathway, etc.). This acts as the project’s “parameter store,” directing how the prediction pipelines should operate.
c. Prediction & Processing Pipelines:
- make_predictions.py: The entry-point for running predictions using the defined tasks.
- transform_predictions.py: Handles the post-processing of prediction outputs.
- compute_scores.py: Computes performance or similarity scores (for ORF and CRISPR data).
d. Evaluation & Visualization:
- Notebooks (Heatmap.ipynb, ModelAccuracy.ipynb, Scatterplots.ipynb, SLCOR.ipynb): Provide interactive explorations and visual representations of the predictions, model accuracies, and biological relationships.
e. Environment & Build Configuration:
- environment.yml, pyproject.toml, and run_morphmap_gnn.sh: These files manage the software environment, build configurations, and ease the deployment/setup process.

##### Relationships and Interactions
- The Data Input (data/) feeds into the prediction pipeline, with configurations (configurations/) guiding which prediction task or model type to run.
- make_predictions.py uses the configuration details to trigger predictions, generating outputs that are then transformed by transform_predictions.py.
- compute_scores.py takes these prediction outputs and computes aggregate or merged scores that are stored back into the data folder.
- The pre-trained models in trained_models are loaded (with accompanying data objects) during these processes.
- Finally, notebooks pull both the prediction results and scores to evaluate model performance and create visual plots.
- The environment management files ensure that all libraries and dependencies are consistent across these components.

##### Architectural Patterns and Design Principles
- Modular Design: Each module (Data, Configuration, Prediction, Transformation, Scoring, Visualization) is distinct and can be updated or replaced independently.
- Pipeline Pattern: Data flows sequentially from raw data ingestion, through prediction and processing, to final evaluation. This chain is driven by command-line scripts.
- Configuration-Driven Execution: The use of YAML configuration files indicates that behavior can be modified without code changes, supporting experiment flexibility.
- Reusability & Experimentation: Notebooks allow for interactive validation of the pipeline outputs and further exploratory analysis.

– How prediction tasks are parameterized by YAML configurations.
– The movement of raw data through the pipeline to produce prediction outputs, scores, and visual insights.
– The integration between static scripts and interactive notebooks which are used for downstream analysis.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & External Dependencies
    subgraph "Data & External Dependencies"
        DataInput["Data Files (data/)"]:::data
        Models["Pre-trained Models (trained_models/)"]:::data
    end

    %% Configuration Management
    subgraph "Configuration Management"
        Config["Configuration Files (configurations/)"]:::config
    end

    %% Processing Pipeline
    subgraph "Processing Pipeline"
        Predict["make_predictions.py\n(Prediction Runner)"]:::process
        Transform["transform_predictions.py\n(Transformer)"]:::process
        Score["compute_scores.py\n(Scorer)"]:::process
    end

    %% Evaluation & Visualization
    subgraph "Evaluation & Visualization"
        Notebook1["Heatmap.ipynb"]:::notebook
        Notebook2["ModelAccuracy.ipynb"]:::notebook
        Notebook3["Scatterplots.ipynb"]:::notebook
        Notebook4["SLCOR.ipynb"]:::notebook
    end

    %% Environment & Build Configuration
    subgraph "Environment & Build"
        Env["environment.yml"]:::env
        PyProj["pyproject.toml"]:::env
        Shell["run_morphmap_gnn.sh"]:::env
    end

    %% Connections from Data & External Dependencies to Processing Pipeline
    DataInput -->|"feeds"| Predict
    Models -->|"supplies models"| Predict

    %% Connection from Configuration Management to Processing Pipeline
    Config -->|"configures"| Predict

    %% Environment influences processing pipeline
    Env -->|"env set"| Predict
    PyProj -->|"build config"| Predict
    Shell -->|"deployment"| Predict

    %% Processing Pipeline flow
    Predict -->|"generates output"| Transform
    Transform -->|"processes output"| Score

    %% Evaluation collects data from Prediction and Scoring
    Predict -->|"raw predictions"| Notebook1
    Predict -->|"raw predictions"| Notebook2
    Predict -->|"raw predictions"| Notebook3
    Predict -->|"raw predictions"| Notebook4

    Score -->|"scored data"| Notebook1
    Score -->|"scored data"| Notebook2
    Score -->|"scored data"| Notebook3
    Score -->|"scored data"| Notebook4

    %% Click Events
    click DataInput "https://github.com/evotec-isrd/gnn-morphmap/tree/main/data/"
    click Models "https://github.com/evotec-isrd/gnn-morphmap/tree/main/trained_models/"
    click Config "https://github.com/evotec-isrd/gnn-morphmap/tree/main/configurations/"
    click Predict "https://github.com/evotec-isrd/gnn-morphmap/blob/main/make_predictions.py"
    click Transform "https://github.com/evotec-isrd/gnn-morphmap/blob/main/transform_predictions.py"
    click Score "https://github.com/evotec-isrd/gnn-morphmap/blob/main/compute_scores.py"
    click Notebook1 "https://github.com/evotec-isrd/gnn-morphmap/blob/main/Heatmap.ipynb"
    click Notebook2 "https://github.com/evotec-isrd/gnn-morphmap/blob/main/ModelAccuracy.ipynb"
    click Notebook3 "https://github.com/evotec-isrd/gnn-morphmap/blob/main/Scatterplots.ipynb"
    click Notebook4 "https://github.com/evotec-isrd/gnn-morphmap/blob/main/SLCOR.ipynb"
    click Env "https://github.com/evotec-isrd/gnn-morphmap/blob/main/environment.yml"
    click PyProj "https://github.com/evotec-isrd/gnn-morphmap/blob/main/pyproject.toml"
    click Shell "https://github.com/evotec-isrd/gnn-morphmap/blob/main/run_morphmap_gnn.sh"

    %% Styling Classes
    classDef data fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef config fill:#66ccff,stroke:#333,stroke-width:2px;
    classDef process fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef notebook fill:#ff99cc,stroke:#333,stroke-width:2px;
    classDef env fill:#ccccff,stroke:#333,stroke-width:2px;
```
