# guangyuwanglab2021/loki architecture

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

- Interactive diagram: https://gitdiagram.com/guangyuwanglab2021/loki
- Repository: https://github.com/guangyuwanglab2021/loki

## Overview

Loki is a Python toolkit for spatial-transcriptomics and H&E analysis built around five documented capabilities: tissue alignment, cell-type decomposition, tissue annotation, ST gene-expression prediction, and image–transcriptomics retrieval. A typical user prepares data and embeddings, invokes the relevant analysis module, then inspects results with plotting utilities. The README documents these capabilities and module imports; sampled source confirms the modules’ individual computations. It does not establish cross-module orchestration, so no inter-module workflow edges are inferred.

Main entry points: [`src/loki/preprocess.py`](https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/preprocess.py) (Data preprocessing), [`src/loki/utils.py`](https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/utils.py) (Model and embeddings), [`src/loki/align.py`](https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/align.py) (Tissue alignment), [`src/loki/annotate.py`](https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/annotate.py) (Bulk annotation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_preprocess["Data preprocessing<br/>[preprocess.py]"]
end

subgraph group_embeddings["Feature encoding"]
  node_utils["Model and embeddings<br/>[utils.py]"]
end

subgraph group_analysis["Analysis capabilities"]
  node_alignment["Tissue alignment<br/>[align.py]"]
  node_annotation_bulk["Bulk annotation<br/>[annotate.py]"]
  node_annotation_markers["Marker annotation<br/>[annotate.py]"]
  node_decomposition["Cell decomposition<br/>[decompose.py]"]
  node_retrieval["Image ST retrieval<br/>[retrieve.py]"]
  node_prediction["Gene expression prediction<br/>[predex.py]"]
end

subgraph group_results["Results and visualization"]
  node_plotting["Result plotting<br/>[plot.py]"]
end

node_researcher(("Loki user"))

node_researcher -->|"prepares data"| node_preprocess
node_researcher -->|"encodes features"| node_utils
node_researcher -->|"aligns tissue"| node_alignment
node_researcher -->|"annotates tissue"| node_annotation_bulk
node_researcher -->|"annotates tissue"| node_annotation_markers
node_researcher -->|"decomposes cell types"| node_decomposition
node_researcher -->|"retrieves matches"| node_retrieval
node_researcher -->|"predicts expression"| node_prediction
node_researcher -->|"visualizes results"| node_plotting

click node_preprocess "https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/preprocess.py"
click node_utils "https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/utils.py"
click node_alignment "https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/align.py"
click node_annotation_bulk "https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/annotate.py"
click node_annotation_markers "https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/annotate.py"
click node_decomposition "https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/decompose.py"
click node_retrieval "https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/retrieve.py"
click node_prediction "https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/predex.py"
click node_plotting "https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/plot.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_preprocess,node_researcher toneBlue
class node_utils toneAmber
class node_alignment,node_annotation_bulk,node_annotation_markers,node_decomposition,node_retrieval,node_prediction toneMint
class node_plotting toneRose
```

## Components

### Data preparation

- [Data preprocessing](https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/preprocess.py): `src/loki/preprocess.py`

### Feature encoding

- [Model and embeddings](https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/utils.py): `src/loki/utils.py`

### Analysis capabilities

- [Tissue alignment](https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/align.py): `src/loki/align.py`
- [Bulk annotation](https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/annotate.py): `src/loki/annotate.py`
- [Marker annotation](https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/annotate.py): `src/loki/annotate.py`
- [Cell decomposition](https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/decompose.py): `src/loki/decompose.py`
- [Image ST retrieval](https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/retrieve.py): `src/loki/retrieve.py`
- [Gene expression prediction](https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/predex.py): `src/loki/predex.py`

### Results and visualization

- [Result plotting](https://github.com/guangyuwanglab2021/loki/blob/main/src/loki/plot.py): `src/loki/plot.py`

### Other components

- **Loki user**

## Connections

- Loki user → Data preprocessing: prepares data (evidence: `README.md`)
- Loki user → Model and embeddings: encodes features (evidence: `README.md`)
- Loki user → Tissue alignment: aligns tissue (evidence: `README.md`)
- Loki user → Bulk annotation: annotates tissue (evidence: `README.md`)
- Loki user → Marker annotation: annotates tissue (evidence: `README.md`)
- Loki user → Cell decomposition: decomposes cell types (evidence: `README.md`)
- Loki user → Image ST retrieval: retrieves matches (evidence: `README.md`)
- Loki user → Gene expression prediction: predicts expression (evidence: `README.md`)
- Loki user → Result plotting: visualizes results (evidence: `README.md`)