# bowang-lab/bionic architecture

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

- Interactive diagram: https://gitdiagram.com/bowang-lab/bionic
- Repository: https://github.com/bowang-lab/bionic

## Overview

##### Main Components

a. User/Configuration Entry Point:
- CLI: The entry point is defined in bionic/cli.py, where commands and configuration file paths are parsed. This is the interface through which users invoke the model training/testing process.
- Configuration File Handling: The bionic/utils/config_parser.py (and similar utilities in bionic/tests/config) reads a JSON configuration file that specifies input network paths, hyperparameters (like epochs, learning rate, embedding size, etc.), and output file names.

b. Data Input and Preprocessing:
- Input Networks & Labels: Under bionic/inputs there are network edgelist files and gene label files. These are the raw data inputs.
- Preprocessor: Found in bionic/utils/preprocessor.py, this module is responsible for reading and parsing the input edgelist files (and labels when provided) to produce data structures that the model can ingest.
- Sampler: bionic/utils/sampler.py handles sampling operations, such as neighbor sampling needed for graph convolution passes.

c. Modeling – Graph Convolutional Network Architecture:
- Model Layers: bionic/model/layers.py contains definitions for the graph convolution (or graph attention) layers (e.g., GAT layers). These modules are applied to each input network.
- Model Definition: bionic/model/model.py orchestrates the overall architecture by including network-specific encoders for each input network. It supports using shared encoders if specified. The model then integrates features from multiple networks (by summing them or through other operations) to produce the integrated gene features.
- Loss Functions: bionic/model/loss.py defines the reconstruction loss (and, if applicable, the classification loss) necessary to train the network by comparing the decoded reconstruction to the original networks and labels.

d. Training and Execution Flow:
- Training Script: bionic/train.py is the main script that ties the configuration, model, loss functions, preprocessor, and optimizer together to perform training over a specified number of epochs.
- TensorBoard Integration: Through options configured in the config file (and handled in parts of the code) the training progress can be monitored with TensorBoard, and plots are generated (as can be seen in bionic/utils/plotter.py).

e. Outputs and Artifacts:
- Output Files: The directory bionic/outputs is used for storing the integrated features, models, and logs (if enabled).
- Additional artifacts are generated for network reconstruction and optionally for label prediction outputs.

f. Testing and Build Infrastructure:
- Tests: The bionic/tests directory holds unit tests ensuring the correctness of various modules (config parsing, preprocessing, model behavior, etc.).
- Build System: Files like pyproject.toml, the build directory (which includes a script to rename the built wheel), and GitHub workflows in .github indicate CI/CD integration and build steps for packaging.

- Next, a “Data Input” component should represent the raw network files and optional gene label files.
- Merge these pathways into an “Integration Module” that sums or combines the learned gene features.
- Followed by a “Decoding Module” which splits into two paths:
– One for “Network Reconstruction” (reconstructing network topology).
– Optionally, one for “Label Prediction” when gene labels are provided.
- Both paths feed into the “Loss Computation” block where reconstruction and, optionally, classification losses are computed.
- The computed loss is used by the “Training Loop / Optimizer” component (bridge the training script in bionic/train.py) that updates model weights.
- Finally, include an “Output & Logging” component that saves integrated gene features, models, and optionally sends output to TensorBoard (utilizing bionic/utils/plotter.py and tensorboard settings).

##### Architectural Patterns and Technologies

- The usage of a deep-learning framework (PyTorch) with extensions for graph-based deep learning (PyTorch Geometric).
- The separation of concerns: distinct modules for configuration, data preprocessing, model definition, training, and output generation.
- The support for both CPU and GPU execution.
- Test suites and build pipelines.

- Rectangles for components (e.g., “Configuration Parser”, “Preprocessing”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Flow
    CLI["User/Configuration Entry Point (CLI)"]:::input
    CONFIG["Configuration Parser"]:::config
    DATA["Data Input (Raw Networks & Gene Labels)"]:::input

    CLI --> CONFIG
    CONFIG --> DATA

    %% Data Preprocessing Subgraph
    subgraph "Data Preprocessing"
        PREP["Preprocessor"]:::preprocess
        SAMPLER["Sampler"]:::preprocess
    end
    DATA --> PREP
    DATA --> SAMPLER

    %% Converge Preprocessing Outputs
    PREP_SAM["Preprocessing Output"]:::preprocess
    PREP --> PREP_SAM
    SAMPLER --> PREP_SAM

    %% Graph Convolutional Network Subgraph
    subgraph "Graph Convolutional Network"
        ML["Model Layers"]:::model
        MD["Model Definition"]:::model
        INT["Integration Module"]:::model
        DEC["Decoding Module"]:::model
        NETREC["Network Reconstruction"]:::model
        LBP["Label Prediction"]:::model
        LOSS["Loss Computation"]:::model
    end

    PREP_SAM --> ML
    ML --> MD
    MD --> INT
    INT --> DEC
    DEC --> NETREC
    DEC --> LBP
    NETREC --> LOSS
    LBP --> LOSS

    %% Training and Output Flow
    TRAIN["Training Loop / Optimizer"]:::training
    LOSS --> TRAIN
    OUTPUT["Output & Logging"]:::output
    TRAIN --> OUTPUT
    TBOARD["TensorBoard & Plotting"]:::output
    TRAIN --> TBOARD

    %% Infrastructure Subgraph
    subgraph "Infrastructure"
        TEST["Testing Suite"]:::infra
        BUILD["Build & CI/CD Infrastructure"]:::infra
    end

    %% Connect Infrastructure with dashed style
    CLI --- TEST
    CLI --- BUILD

    %% Annotation for Deep Learning Framework
    NOTE["Deep Learning Framework: PyTorch & PyTorch Geometric"]:::model
    INT --- NOTE

    %% Click Events
    click CLI "https://github.com/bowang-lab/bionic/blob/master/bionic/cli.py"
    click CONFIG "https://github.com/bowang-lab/bionic/blob/master/bionic/utils/config_parser.py"
    click DATA "https://github.com/bowang-lab/bionic/tree/master/bionic/inputs"
    click PREP "https://github.com/bowang-lab/bionic/blob/master/bionic/utils/preprocessor.py"
    click SAMPLER "https://github.com/bowang-lab/bionic/blob/master/bionic/utils/sampler.py"
    click ML "https://github.com/bowang-lab/bionic/blob/master/bionic/model/layers.py"
    click MD "https://github.com/bowang-lab/bionic/blob/master/bionic/model/model.py"
    click LOSS "https://github.com/bowang-lab/bionic/blob/master/bionic/model/loss.py"
    click TRAIN "https://github.com/bowang-lab/bionic/blob/master/bionic/train.py"
    click TBOARD "https://github.com/bowang-lab/bionic/blob/master/bionic/utils/plotter.py"
    click OUTPUT "https://github.com/bowang-lab/bionic/tree/master/bionic/outputs"
    click TEST "https://github.com/bowang-lab/bionic/tree/master/bionic/tests"
    click BUILD "https://github.com/bowang-lab/bionic/blob/master/.github"

    %% Styles
    classDef input fill:#87CEFA,stroke:#000,stroke-width:1px;
    classDef config fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef preprocess fill:#98FB98,stroke:#000,stroke-width:1px;
    classDef model fill:#FFA07A,stroke:#000,stroke-width:1px;
    classDef training fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef output fill:#F0E68C,stroke:#000,stroke-width:1px;
    classDef infra fill:#CD853F,stroke:#000,stroke-width:1px;
```
