# wqli498/patholic architecture

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

- Interactive diagram: https://gitdiagram.com/wqli498/patholic
- Repository: https://github.com/wqli498/patholic

## Overview

PathoLIC compresses whole-slide pathology images with content-aware variable-rate learned compression, then evaluates reconstructed data and extracted features in downstream pathology tasks. The documented workflow runs WSI segmentation/patching/stitching, feature or attention extraction, compression training or checkpoint evaluation, bitstream decoding, and downstream validation. The tree also includes substantial local CompressAI and nnU-Net subsystems. Evidence is strongest for the README workflow and indexed imports; unsampled implementations and their internal wiring are represented conservatively.

Main entry points: [`main.py`](https://github.com/wqli498/patholic/blob/main/main.py) (Workflow runner), [`compressai/models/vbr.py`](https://github.com/wqli498/patholic/blob/main/compressai/models/vbr.py) (Variable-rate codec), [`decompression_and_extract_features.py`](https://github.com/wqli498/patholic/blob/main/decompression_and_extract_features.py) (Decode and extract), [`compression_model_validation.py`](https://github.com/wqli498/patholic/blob/main/compression_model_validation.py) (Compression evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_wsi["WSI preparation"]
  node_main["Workflow runner<br/>[main.py]"]
  node_slide["Slide processing"]
  node_slideio["WSI operations<br/>[WholeSlideImage.py]"]
end

subgraph group_compression["Learned compression"]
  node_compress_train["Compression training"]
  node_compress_eval["Compression evaluation"]
  node_codec["Variable-rate codec<br/>[vbr.py]"]
  node_entropy["Entropy models<br/>[entropy_models.py]"]
  node_latent["Latent codecs"]
  node_compressai_base["Codec base models<br/>[base.py]"]
  node_bitstreams[("Compressed bitstreams")]
end

subgraph group_features["Features and attention"]
  node_label["Patch labeling<br/>[patch_labeling.py]"]
  node_decode_features["Decode and extract"]
  node_feature_models["Feature encoders<br/>[pipeline.py]"]
  node_titan["TITAN encoder"]
  node_chief["CHIEF attention<br/>[CHIEF.py]"]
  node_features_store[("Feature files")]
end

subgraph group_validation["Downstream validation"]
  node_finetune["Task fine-tuning<br/>[main.py]"]
  node_survival["Survival analysis"]
  node_roi["ROI retrieval"]
  node_patch_class["Patch classification"]
  node_segmentation["Nuclei segmentation"]
  node_nn_plans["Segmentation plans"]
end

subgraph group_libraries["Model libraries"]
  node_compressai_zoo["Codec model catalog<br/>[image.py]"]
  node_rate_loss["Rate-distortion loss<br/>[rate_distortion.py]"]
  node_registry["Component registry<br/>[torch.py]"]
end

node_user(("Researcher"))

node_user -->|"runs workflow"| node_main
node_main -->|"prepares slides"| node_slide
node_slide -.->|"uses slide operations"| node_slideio
node_main -->|"extracts features"| node_label
node_main -->|"trains codec"| node_compress_train
node_main -->|"evaluates codec"| node_compress_eval
node_compress_train -.->|"optimizes"| node_codec
node_compress_eval -.->|"evaluates"| node_codec
node_codec -->|"uses"| node_entropy
node_codec -->|"extends"| node_compressai_base
node_entropy -.->|"provides coding models"| node_latent
node_main -->|"invokes extraction"| node_decode_features
node_decode_features -->|"reads and decodes"| node_bitstreams
node_compress_eval -->|"writes"| node_bitstreams
node_decode_features -->|"writes features"| node_features_store
node_label -.->|"extracts embeddings"| node_feature_models
node_decode_features -.->|"supports TITAN features"| node_titan
node_main -->|"supports CHIEF attention"| node_chief
node_main -->|"supports TITAN attention"| node_titan
node_user -->|"runs task training"| node_finetune
node_user -->|"validates survival"| node_survival
node_user -->|"runs retrieval"| node_roi
node_user -->|"runs classification"| node_patch_class
node_user -->|"runs segmentation"| node_segmentation
node_nn_plans -.->|"plans inference"| node_segmentation
node_compressai_zoo -->|"uses model base"| node_compressai_base
node_codec -.->|"trained with"| node_rate_loss
node_compressai_zoo -.->|"registers models"| node_registry

click node_main "https://github.com/wqli498/patholic/blob/main/main.py"
click node_slide "https://github.com/wqli498/patholic/blob/main/create_patches_fp.py"
click node_slideio "https://github.com/wqli498/patholic/blob/main/wsi_core/WholeSlideImage.py"
click node_label "https://github.com/wqli498/patholic/blob/main/patch_labeling.py"
click node_compress_train "https://github.com/wqli498/patholic/blob/main/compression_model_training.py"
click node_compress_eval "https://github.com/wqli498/patholic/blob/main/compression_model_validation.py"
click node_codec "https://github.com/wqli498/patholic/blob/main/compressai/models/vbr.py"
click node_entropy "https://github.com/wqli498/patholic/blob/main/compressai/entropy_models/entropy_models.py"
click node_latent "https://github.com/wqli498/patholic/blob/main/compressai/latent_codecs/gaussian_conditional.py"
click node_compressai_base "https://github.com/wqli498/patholic/blob/main/compressai/models/base.py"
click node_decode_features "https://github.com/wqli498/patholic/blob/main/decompression_and_extract_features.py"
click node_feature_models "https://github.com/wqli498/patholic/blob/main/gigapath/pipeline.py"
click node_titan "https://github.com/wqli498/patholic/blob/main/mytitan/vision_transformer.py"
click node_chief "https://github.com/wqli498/patholic/blob/main/CHIEF.py"
click node_finetune "https://github.com/wqli498/patholic/blob/main/finetune/main.py"
click node_survival "https://github.com/wqli498/patholic/blob/main/titan_survival_brca.py"
click node_roi "https://github.com/wqli498/patholic/blob/main/uni_roi_retrieval_crc_vis.py"
click node_patch_class "https://github.com/wqli498/patholic/blob/main/run_patch_classification.py"
click node_segmentation "https://github.com/wqli498/patholic/blob/main/nnUNet/nnunetv2/inference/predict_from_raw_data.py"
click node_nn_plans "https://github.com/wqli498/patholic/blob/main/nnUNet/nnunetv2/experiment_planning/experiment_planners/default_experiment_planner.py"
click node_compressai_zoo "https://github.com/wqli498/patholic/blob/main/compressai/zoo/image.py"
click node_rate_loss "https://github.com/wqli498/patholic/blob/main/compressai/losses/rate_distortion.py"
click node_registry "https://github.com/wqli498/patholic/blob/main/compressai/registry/torch.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_slide,node_slideio toneBlue
class node_compress_train,node_compress_eval,node_codec,node_entropy,node_latent,node_compressai_base,node_bitstreams toneAmber
class node_label,node_decode_features,node_feature_models,node_titan,node_chief,node_features_store toneMint
class node_finetune,node_survival,node_roi,node_patch_class,node_segmentation,node_nn_plans toneRose
class node_compressai_zoo,node_rate_loss,node_registry,node_user toneIndigo
```

## Components

### WSI preparation

- [Workflow runner](https://github.com/wqli498/patholic/blob/main/main.py): `main.py`
- [Slide processing](https://github.com/wqli498/patholic/blob/main/create_patches_fp.py): `create_patches_fp.py`
- [WSI operations](https://github.com/wqli498/patholic/blob/main/wsi_core/WholeSlideImage.py): `wsi_core/WholeSlideImage.py`

### Learned compression

- [Compression training](https://github.com/wqli498/patholic/blob/main/compression_model_training.py): `compression_model_training.py`
- [Compression evaluation](https://github.com/wqli498/patholic/blob/main/compression_model_validation.py): `compression_model_validation.py`
- [Variable-rate codec](https://github.com/wqli498/patholic/blob/main/compressai/models/vbr.py): `compressai/models/vbr.py`
- [Entropy models](https://github.com/wqli498/patholic/blob/main/compressai/entropy_models/entropy_models.py): `compressai/entropy_models/entropy_models.py`
- [Latent codecs](https://github.com/wqli498/patholic/blob/main/compressai/latent_codecs/gaussian_conditional.py): `compressai/latent_codecs/gaussian_conditional.py`
- [Codec base models](https://github.com/wqli498/patholic/blob/main/compressai/models/base.py): `compressai/models/base.py`
- **Compressed bitstreams**

### Features and attention

- [Patch labeling](https://github.com/wqli498/patholic/blob/main/patch_labeling.py): `patch_labeling.py`
- [Decode and extract](https://github.com/wqli498/patholic/blob/main/decompression_and_extract_features.py): `decompression_and_extract_features.py`
- [Feature encoders](https://github.com/wqli498/patholic/blob/main/gigapath/pipeline.py): `gigapath/pipeline.py`
- [TITAN encoder](https://github.com/wqli498/patholic/blob/main/mytitan/vision_transformer.py): `mytitan/vision_transformer.py`
- [CHIEF attention](https://github.com/wqli498/patholic/blob/main/CHIEF.py): `CHIEF.py`
- **Feature files**

### Downstream validation

- [Task fine-tuning](https://github.com/wqli498/patholic/blob/main/finetune/main.py): `finetune/main.py`
- [Survival analysis](https://github.com/wqli498/patholic/blob/main/titan_survival_brca.py): `titan_survival_brca.py`
- [ROI retrieval](https://github.com/wqli498/patholic/blob/main/uni_roi_retrieval_crc_vis.py): `uni_roi_retrieval_crc_vis.py`
- [Patch classification](https://github.com/wqli498/patholic/blob/main/run_patch_classification.py): `run_patch_classification.py`
- [Nuclei segmentation](https://github.com/wqli498/patholic/blob/main/nnUNet/nnunetv2/inference/predict_from_raw_data.py): `nnUNet/nnunetv2/inference/predict_from_raw_data.py`
- [Segmentation plans](https://github.com/wqli498/patholic/blob/main/nnUNet/nnunetv2/experiment_planning/experiment_planners/default_experiment_planner.py): `nnUNet/nnunetv2/experiment_planning/experiment_planners/default_experiment_planner.py`

### Model libraries

- [Codec model catalog](https://github.com/wqli498/patholic/blob/main/compressai/zoo/image.py): `compressai/zoo/image.py`
- [Rate-distortion loss](https://github.com/wqli498/patholic/blob/main/compressai/losses/rate_distortion.py): `compressai/losses/rate_distortion.py`
- [Component registry](https://github.com/wqli498/patholic/blob/main/compressai/registry/torch.py): `compressai/registry/torch.py`

### Other components

- **Researcher**

## Connections

- Researcher → Workflow runner: runs workflow
- Workflow runner → Slide processing: prepares slides (evidence: `main.py`)
- Slide processing → WSI operations: uses slide operations
- Workflow runner → Patch labeling: extracts features (evidence: `main.py`)
- Workflow runner → Compression training: trains codec (evidence: `main.py`)
- Workflow runner → Compression evaluation: evaluates codec (evidence: `main.py`)
- Compression training → Variable-rate codec: optimizes
- Compression evaluation → Variable-rate codec: evaluates
- Variable-rate codec → Entropy models: uses (evidence: `compressai/models/vbr.py`)
- Variable-rate codec → Codec base models: extends (evidence: `compressai/models/vbr.py`)
- Entropy models → Latent codecs: provides coding models
- Workflow runner → Decode and extract: invokes extraction (evidence: `main.py`)
- Decode and extract → Compressed bitstreams: reads and decodes
- Compression evaluation → Compressed bitstreams: writes
- Decode and extract → Feature files: writes features
- Patch labeling → Feature encoders: extracts embeddings
- Decode and extract → TITAN encoder: supports TITAN features
- Workflow runner → CHIEF attention: supports CHIEF attention
- Workflow runner → TITAN encoder: supports TITAN attention
- Researcher → Task fine-tuning: runs task training
- Researcher → Survival analysis: validates survival
- Researcher → ROI retrieval: runs retrieval
- Researcher → Patch classification: runs classification
- Researcher → Nuclei segmentation: runs segmentation
- Segmentation plans → Nuclei segmentation: plans inference
- Codec model catalog → Codec base models: uses model base (evidence: `compressai/zoo/image.py`)
- Variable-rate codec → Rate-distortion loss: trained with
- Codec model catalog → Component registry: registers models
