# labomics/midas architecture

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

- Interactive diagram: https://gitdiagram.com/labomics/midas
- Repository: https://github.com/labomics/midas

## Overview

##### Main Components
- Configuration Module: Represented by the “config.py” within the source; handles project settings and parameters.
- Data Handling: The “data.py” module is responsible for data ingestion, processing, and normalization essential for single-cell modalities.
- Model Construction: The “model.py” module defines the deep generative architecture – the core of how mosaic inputs are transformed.
- Neural Network Definition: The “nn.py” module likely contains detailed neural network implementations and integration with PyTorch Lightning.
- Helper Utilities: The “utils.py” module which provides additional support functions, error handling, preprocessing aids, etc.
- External Dependencies: Include external components such as PyTorch Lightning for distributed training (e.g., DDP) and TensorBoard integration for tracking training metrics.

##### Understand Relationships and Interactions
- Data flows from raw single-cell input through the “data.py” component, getting preprocessed using utilities.
- Configurations set via “config.py” determine how the data and model behave or interconnect.
- The “model.py” component designs the overall generative framework that uses outputs from the “data.py” and into which the neural network layers from “nn.py” are integrated.
- Training is orchestrated with PyTorch Lightning; thus, the “nn.py” also ties into the training loop, with real-time visualization provided by TensorBoard.
- Additionally, the existence of detailed documentation (in the docs folder with usage demos and tutorials) implies that the architecture is modular enough to allow for extensive external configuration and integration.

##### Diagramming the Architecture
- That Data Processing and Utilities contribute to building the final input pipeline for the Model.
- Training framework (PyTorch Lightning) as an external orchestration layer connecting to the Neural Network module and Model.
- Output repositories flowing into TensorBoard (or an “External Visualization” tool) to emphasize the integration for monitoring.

##### Architectural Patterns & Design Principles
- Modular design: Each functionality (data, model, training, utilities) is segregated into its own module for ease of maintenance, testing, and extensibility.
- Loose Coupling: The configuration and utility modules interface with both data and model modules, ensuring changes in one module have limited impact on others.
- Integration with External Systems: Explicit incorporation of PyTorch Lightning for efficient training (including optional distributed modes) and TensorBoard for real-time metric tracking.

##### Elements
- Annotations: Optionally, add short notes on key technologies (PyTorch Lightning, TensorBoard) or design decisions (modularity, extensibility).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User/Client"]:::user
    Doc["Documentation"]:::doc

    %% Core Configuration
    Config["Configuration Module"]:::config

    %% Data and Utility Modules
    Utils["Helper Utilities"]:::utils
    Data["Data Handling"]:::data

    %% Model and Neural Network
    Model["Model Construction"]:::model
    NN["Neural Network"]:::neural

    %% External Services
    Lightning["Training Framework (PyTorch Lightning)"]:::external
    TB["Visualization (TensorBoard)"]:::external

    %% Flow Connections
    User --> Doc
    Doc --> Config
    Config -->|"sets parameters"| Data
    Config -->|"sets parameters"| Model
    Utils -->|"supports"| Data
    Utils -->|"supports"| Model
    Data -->|"preprocessed data"| Model
    Model -->|"builds generative model"| NN
    NN -->|"triggers training"| Lightning
    Lightning -->|"sends metrics"| TB

    %% Click Events for Component Mapping
    click Config "https://github.com/labomics/midas/blob/main/src/scmidas/config.py"
    click Data "https://github.com/labomics/midas/blob/main/src/scmidas/data.py"
    click Model "https://github.com/labomics/midas/blob/main/src/scmidas/model.py"
    click NN "https://github.com/labomics/midas/blob/main/src/scmidas/nn.py"
    click Utils "https://github.com/labomics/midas/blob/main/src/scmidas/utils.py"

    %% Styles
    classDef user fill:#FFC0CB,stroke:#333,stroke-width:2px;
    classDef doc fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef config fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef data fill:#87CEEB,stroke:#333,stroke-width:2px;
    classDef utils fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef model fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef neural fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef external fill:#9370DB,stroke:#333,stroke-width:2px;
```
