# mahmoodlab/uni architecture

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

- Interactive diagram: https://gitdiagram.com/mahmoodlab/uni
- Repository: https://github.com/mahmoodlab/uni

## Overview

##### Main System Components
- Model Loader & Inference Engine: Represented by the uni/get_encoder module. This component is responsible for (a) downloading pretrained checkpoints (via Hugging Face Hub authentication and caching), (b) instantiating the appropriate timm model (a specific ViT variant with custom arguments), and (c) preparing image transformation pipelines.
- Downstream Evaluation & Feature Extraction: Shown in the uni/downstream directory. This includes separate modules for evaluation (linear_probe, fewshot, logistic regression, protonet, etc.) and for extracting patch features. These modules provide distinct evaluation pipelines and are examples of “pass-through” components where the extracted embeddings are used for various downstream tasks.
- Data & Asset Management: Illustrated by the assets directory. This node includes subdirectories for checkpoints (ckpts) and datasets, which are essential for both loading model weights and for benchmarking.
- Notebooks & Example Workflows: Represented by the notebooks folder. These scripts (e.g., uni_walkthrough.ipynb and crc100k_evaluation.ipynb) act as integration demos to show how to run inference, extract features, and evaluate the model on real data.
- Setup & Configuration: Encapsulated by setup.py, which ensures installation dependency management and environment configuration.

##### Relationships and Data Flow
- The client/user (or a calling service) interacts with the notebooks or custom scripts (e.g., main inference scripts) to invoke the model.
- The Model Loader (uni/get_encoder) downloads and loads pretrained model weights from external sources (Hugging Face Hub) into the local environment (assets/ckpts) while also establishing required image transforms.
- Once the model is loaded, input images (e.g., a pathology slide image) pass through a pre-processing pipeline (built using torchvision or timm’s transform utilities). The processed image is then fed into the encoder to produce feature embeddings.
- These embeddings are then passed to various downstream evaluation modules (located in uni/downstream) that run tasks such as linear probing, k-nearest neighbors classification, and prototype-based inference.

##### Architectural Patterns and Key Technologies
- Modular design: Clear separation between model instantiation (get_encoder), downstream tasks (eval_patch_features, extract_patch_features), and usage examples (notebooks), which improves reusability and testing.
- Integration with external libraries: The project leverages timm for model definition, torchvision for image processing, and the Huggingface Hub for managing checkout, ensuring that external dependencies and caching are clearly represented.
- Distributed Data Handling: The assets directory manages both model checkpoints and data (ZIP files of datasets) which could be diagrammed as external storage or a data layer.
- API-driven design: The get_encoder method serves as a single point of retrieving models and pre-processing pipelines, thus acting as an “API” for the rest of the system.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client
    Client["Client/Script"]:::client

    %% Notebooks & Example Workflows Subgraph
    subgraph "Notebooks & Example Workflows"
        N1["uni_walkthrough.ipynb"]:::notebook
        N2["crc100k_evaluation.ipynb"]:::notebook
    end

    %% Setup & Configuration
    Setup["Setup & Configuration"]:::config

    %% Model Loader & Inference Subgraph
    subgraph "Model Loader & Inference"
        ML1["get_encoder.py"]:::internal
        ML2["Models"]:::internal
    end

    %% Downstream Evaluation & Feature Extraction Subgraph
    subgraph "Downstream Evaluation & Feature Extraction"
        DE1["eval_patch_features"]:::internal
        DE2["extract_patch_features.py"]:::internal
        DE3["Additional Modules"]:::internal
    end

    %% Data & Asset Management Subgraph
    subgraph "Data & Asset Management"
        D1["Checkpoints"]:::data
        D2["Datasets"]:::data
    end

    %% Evaluation Output
    Results["Evaluation Output"]:::result

    %% Connections
    Client -->|"triggers"| N1
    N1 -->|"invokes"| ML1
    Setup -->|"configures"| ML1
    Setup -->|"configures"| DE1

    ML1 -->|"initializes"| ML2
    ML1 -->|"downloads_weights"| D1
    ML1 -->|"prepares_data"| D2

    ML1 -->|"runs_inference"| DE1
    ML1 -->|"extracts_features"| DE2
    DE1 -->|"aggregates_results"| DE3
    DE2 -->|"aggregates_results"| DE3
    DE3 -->|"produces"| Results
    Results -->|"visualized_in"| N2

    %% Click Events for Component Mapping
    click ML1 "https://github.com/mahmoodlab/uni/blob/main/uni/get_encoder/get_encoder.py"
    click ML2 "https://github.com/mahmoodlab/uni/tree/main/uni/get_encoder/models/"
    click DE1 "https://github.com/mahmoodlab/uni/tree/main/uni/downstream/eval_patch_features/"
    click DE2 "https://github.com/mahmoodlab/uni/blob/main/uni/downstream/extract_patch_features.py"
    click D1 "https://github.com/mahmoodlab/uni/tree/main/assets/ckpts/"
    click D2 "https://github.com/mahmoodlab/uni/tree/main/assets/data/"
    click N1 "https://github.com/mahmoodlab/uni/blob/main/notebooks/uni_walkthrough.ipynb"
    click N2 "https://github.com/mahmoodlab/uni/blob/main/notebooks/crc100k_evaluation.ipynb"
    click Setup "https://github.com/mahmoodlab/uni/blob/main/setup.py"

    %% Styles
    classDef client fill:#F4E6CC,stroke:#333,stroke-width:2px;
    classDef notebook fill:#CCE5FF,stroke:#333,stroke-width:2px;
    classDef internal fill:#D1E7DD,stroke:#333,stroke-width:2px;
    classDef data fill:#FFE5D9,stroke:#333,stroke-width:2px;
    classDef config fill:#F8D7DA,stroke:#333,stroke-width:2px;
    classDef result fill:#E2E3E5,stroke:#333,stroke-width:2px;
```
