How bowang-lab/bionic works
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”).