# sggb0nd/step architecture

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

- Interactive diagram: https://gitdiagram.com/sggb0nd/step
- Repository: https://github.com/sggb0nd/step

## Overview

##### Project Type and Purpose
- STEP is a specialized deep learning/AI toolkit designed for Spatial Transcriptomics analysis. It provides a unified framework to process and analyze spatially resolved transcriptomics (SRT) and scRNA-seq data. Its architecture includes three main modules: the Backbone model (Transformer plus gene module mapping), the Batch-effect model (utilizing inverse transformations and batch-embedding), and the Spatial model (using a GCN-based spatial filter).

##### Analyzing the File Structure
- The top-level “step” directory encapsulates the core functionality and is subdivided into multiple logical areas:
- “functionality”: Contains base functions, component modules (in comps), and various function models (e.g. cross_funcmodel, sc_funcmodel, st_funcmodel). This suggests a modular design where different analysis strategies are encapsulated.
- “models”: Contains various modeling components (e.g., transcriptformer, clust, deconv) that implement the mathematical and algorithmic models.
- “modules”: Contains specific specialized modules like the decoder, GNN, and transformer implementations.
- “manager”: Provides integration functions such as saving models (e.g., in save.py) and possibly coordinating the workflow.
- “utils”: Contains supportive functionality (dataset processing, metrics, plotting, generation of synthetic data) which is fundamental for data ingestion, pre-processing, and visualization.
- In addition, the repository includes documentation files (docs folder) and continuous integration scripts (GitHub workflows), emphasizing automated deployment and good documentation practices.

a. Data Input and Pre-processing:
- Dataset ingestion layer, which utilizes the BaseDataset and MaskedDataset classes (as mentioned in the README and implemented in the utils modules).
- Data transformation utilities (e.g., dataset.py, metrics, plotting) should be included as support components.

b. Core Models:
- Backbone Model: Highlight the Transformer-based backbone with gene module sequence mapping. This forms the central model for embedding extraction.

c. Integration and Management:
- Role of the integration layer (step/integration.py) which likely ties together the outputs of the various models.
- “manager” component (from step/manager) that handles tasks like saving and orchestration of workflows.

d. External Dependencies and Frameworks:
- That the system operates atop Python 3.10+, PyTorch (>=1.13) and DGL (>=1.1.3), with CUDA support for GPU acceleration. These dependencies form the runtime environment.

##### Relationships and Data Flow
- From the pre-processing layer, data splits into the three main modeling pathways:
- The Backbone (Transformer) branch
- The Batch-effect branch
- The Spatial (GCN) branch

##### Architectural Patterns and Principles
- Separation of concerns: Highlight that utilities (data handling, metrics, plotting) are decoupled from core processing modules, which in turn are integrated via the manager/integration layer.
- Extensibility: Components such as “functionality/comps” imply that additional models or analytical approaches can be added with minimal changes to existing interface definitions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        ED("External Dependencies: Python 3.10+, PyTorch>=1.13, DGL>=1.1.3, CUDA"):::external
    end

    %% Data Ingestion and Pre-processing Layer
    subgraph "Data Ingestion and Pre-processing"
        DS("Dataset"):::data
        MET("Metrics"):::data
        PLT("Plotting"):::data
        PPD("Pre-processed Data"):::data
    end
    ED --> PPD
    DS --> PPD
    MET --> PPD
    PLT --> PPD

    %% Model Components Layer
    subgraph "Model Components"
        %% Backbone Model subgraph
        subgraph "Backbone Model (Transformer + Gene Mapping)"
            TT("Transcriptformer"):::model
            TR("Transformer"):::model
        end
        BEM("Backbone Output"):::modelDummy
        BEC("Batch-effect Correction Module"):::model
        SGN("Spatial Filtering Module (GCN)"):::model
        %% Functional Modules subgraph
        subgraph "Functional Modules (scRNA-seq & ST)"
            CF("Cross Funcmodel"):::model
            SF("sc Funcmodel"):::model
            STF("st Funcmodel"):::model
        end
    end

    %% Integration and Management Layer
    subgraph "Integration and Management"
        IL("Integration Layer"):::integration
        WM("Workflow Manager"):::integration
    end

    %% Final Output
    AO("Analysis Output"):::output

    %% Connections within Model Components
    PPD --> TT
    PPD --> TR
    TT --> BEM
    TR --> BEM
    BEM --> BEC
    BEM --> SGN
    CF --> IL
    SF --> IL
    STF --> IL
    BEC --> IL
    SGN --> IL
    IL --> WM
    WM --> AO

    %% Click Events
    click DS "https://github.com/sggb0nd/step/blob/main/step/utils/dataset.py"
    click MET "https://github.com/sggb0nd/step/blob/main/step/utils/metrics.py"
    click PLT "https://github.com/sggb0nd/step/blob/main/step/utils/plotting.py"
    click TT "https://github.com/sggb0nd/step/blob/main/step/models/transcriptformer.py"
    click TR "https://github.com/sggb0nd/step/blob/main/step/modules/transformer.py"
    click SGN "https://github.com/sggb0nd/step/blob/main/step/modules/gnn.py"
    click IL "https://github.com/sggb0nd/step/blob/main/step/integration.py"
    click WM "https://github.com/sggb0nd/step/blob/main/step/manager/save.py"
    click CF "https://github.com/sggb0nd/step/blob/main/step/functionality/cross_funcmodel.py"
    click SF "https://github.com/sggb0nd/step/blob/main/step/functionality/sc_funcmodel.py"
    click STF "https://github.com/sggb0nd/step/blob/main/step/functionality/st_funcmodel.py"

    %% Styles
    classDef external fill:#f9d,stroke:#333,stroke-width:2px,color:#000;
    classDef data fill:#ccf,stroke:#333,stroke-width:2px,color:#000;
    classDef model fill:#cfc,stroke:#333,stroke-width:2px,color:#000;
    classDef integration fill:#fcf,stroke:#333,stroke-width:2px,color:#000;
    classDef output fill:#cff,stroke:#333,stroke-width:2px,color:#000;
    classDef modelDummy fill:#eee,stroke:#333,stroke-dasharray: 5,5,color:#000;
```
