# rsinghlab/scot architecture

> Architecture diagram of the GitHub repository rsinghlab/scot, 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/rsinghlab/scot
- Repository: https://github.com/rsinghlab/scot

## Overview

##### Main Components
- Core Alignment Engines:
- SCOT v1.0 (located in src/scotv1.py) implements Gromov-Wasserstein optimal transport with a self-tuning hyperparameter heuristic.
- SCOT v2.0 (located in src/scotv2.py) extends functionality with unbalanced optimal transport and multi-modal alignment.
- Data Handling:
- The “data” directory holds input datasets; these include real single-cell omics datasets (e.g., in SNARE and scGEM subdirectories) and simulated data (in the simulations subdirectory).
- There are also feature descriptions and metadata files (npy, csv, txt).
- Examples & Replication:
- “examples” and “replication” directories contain Jupyter notebooks and scripts that demonstrate the tool’s usage, including hyperparameter tuning and evaluation.
- Experimentation / Evaluation Scripts:
- Files like src/evals.py and various notebooks in src or ipynb_checkpoints that may offer insight into evaluation routines or helpers.
- Supporting Documentation & Assets:
- README, LICENSE, requirements.txt, and the “assets” directory (which holds the project logo and possibly other visual assets).

##### Relationships and Data Flow
- Input Stage: Raw data from the “data” directory (both real datasets and simulations) is fed into the SCOT alignment functions.
- Processing Stage:
- The SCOT core modules (scotv1.py and scotv2.py) perform alignment by constructing kNN graphs from the input domains, applying optimal transport techniques, and optionally tuning hyperparameters.
- Output Stage:
- The aligned outputs are returned by the align() method, which can then be visualized or further processed.
- Auxiliary Components:
- Example notebooks and replication scripts act as user interfaces to drive and test the alignment processes.
- Dependency Management:
- The requirements.txt file indicates external libraries and modules that the tool relies on.

##### Architectural Patterns and Design Principles
- Modular Design: Separation between core alignment functionality (in src), data input/output (organized in data), and experimental demonstration (in examples/replication).
- Reusability and Extensibility: The design supports plugging in different alignment techniques (v1.0 versus v2.0), and optional hyperparameter and normalization parameters.
- Clear API Design: As shown in the README “Basic use” example, users instantiate a SCOT object with two matrices and then call align() to obtain outputs.

##### Relevant Technologies, Frameworks, or Libraries
- Python as the main language.
- Jupyter Notebooks for the provided examples and replicability.
- Numpy and possibly other data science libraries listed in the requirements.txt.
- Graph-based libraries may be implied for kNN graph construction, though they are indirectly referenced in the code.
- The optimal transport libraries (or custom implementations) implementing Gromov-Wasserstein computations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    subgraph "Data Sources"
        DS["'data' directory (Real & Simulated Data)"]:::data
    end

    %% Core Alignment Engines
    subgraph "Core Alignment Engines"
        C1["SCOT v1.0 Engine (src/scotv1.py)"]:::core
        C2["SCOT v2.0 Engine (src/scotv2.py)"]:::core
    end

    %% Processing & Output
    subgraph "Processing & Output"
        EU["Evaluation & Utility Scripts (src/evals.py)"]:::utility
        EI["Example Interfaces (examples/ and replication/)"]:::interface
    end

    %% Project Configuration
    subgraph "Project Configuration"
        RD["Requirements & Dependencies (requirements.txt)"]:::config
        DA["Documentation (README.md, LICENSE)"]:::doc
        AS["Assets (assets/)"]:::doc
    end

    %% Connections
    DS -->|"feeds data"| C1
    DS -->|"feeds data"| C2

    RD -->|"dependency"| C1
    RD -->|"dependency"| C2

    C1 -->|"alignment output"| EU
    C2 -->|"alignment output"| EU

    EU -->|"processed results"| EI
    C1 -->|"alignment output"| EI
    C2 -->|"alignment output"| EI

    %% Click Events
    click DS "https://github.com/rsinghlab/scot/tree/master/data/"
    click C1 "https://github.com/rsinghlab/scot/blob/master/src/scotv1.py"
    click C2 "https://github.com/rsinghlab/scot/blob/master/src/scotv2.py"
    click EU "https://github.com/rsinghlab/scot/blob/master/src/evals.py"
    click EI "https://github.com/rsinghlab/scot/tree/master/examples/"
    click RD "https://github.com/rsinghlab/scot/blob/master/requirements.txt"
    click DA "https://github.com/rsinghlab/scot/blob/master/README.md"
    click AS "https://github.com/rsinghlab/scot/tree/master/assets/"

    %% Styles
    classDef core fill:#ffe0e0,stroke:#d62728,stroke-width:2px;
    classDef data fill:#e0f7ff,stroke:#1f77b4,stroke-width:2px;
    classDef utility fill:#fff0d9,stroke:#ff7f0e,stroke-width:2px;
    classDef interface fill:#e0ffe0,stroke:#2ca02c,stroke-width:2px;
    classDef config fill:#ffffe0,stroke:#bcbd22,stroke-width:2px;
    classDef doc fill:#e6e6fa,stroke:#9467bd,stroke-width:2px;
```
