# spaicom/semasia-datasets architecture

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

- Interactive diagram: https://gitdiagram.com/spaicom/semasia-datasets
- Repository: https://github.com/spaicom/semasia-datasets

## Overview

SEMASIA is a benchmark and analysis toolkit for large-scale pretrained vision-model embeddings. Its principal workflow encodes benchmark images with timm models, stores latent representations, and runs geometric, graph/topological, prototype, and alignment analyses; model metadata also supports regression studies. The graph keeps these domain stages distinct and includes the reusable latent-space and graph-analysis layers. README-described capabilities are included, but many script-to-module connections cannot be verified from the sampled source, so those links are omitted.

Main entry points: [`scripts/encode_dataset_all_timm.py`](https://github.com/spaicom/semasia-datasets/blob/main/scripts/encode_dataset_all_timm.py) (Dataset encoding), [`src/objects/latent.py`](https://github.com/spaicom/semasia-datasets/blob/main/src/objects/latent.py) (Latent-space operations), [`src/objects/graph.py`](https://github.com/spaicom/semasia-datasets/blob/main/src/objects/graph.py) (Graph analysis), [`scripts/alignment.py`](https://github.com/spaicom/semasia-datasets/blob/main/scripts/alignment.py) (Alignment evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_encoding["Embedding generation"]
  node_encode["Dataset encoding"]
  node_timm_encoder["Timm encoder<br/>[timm.py]"]
  node_latent_dataset[("Latent dataset")]
end

subgraph group_analysis["Latent analysis"]
  node_metric_compute["Metric extraction<br/>[compute_metrics.py]"]
  node_latent_space["Latent-space operations<br/>[latent.py]"]
  node_prototype_metrics["Prototype metrics<br/>[prototypes.py]"]
  node_graph_object["Graph analysis<br/>[graph.py]"]
  node_graph_metrics["Graph metrics<br/>[graph.py]"]
  node_knn_graph["KNN construction<br/>[graph_inference.py]"]
  node_laplacian["Spectral methods<br/>[laplace.py]"]
  node_tda_features["TDA features<br/>[features.py]"]
  node_tda_extract["TDA extraction<br/>[tda_extraction.py]"]
  node_tsp_extract["Graph signatures<br/>[tsp_extraction.py]"]
  node_latent_plots["Latent visualizations<br/>[latent.py]"]
  node_tda_plots["TDA visualizations<br/>[tda.py]"]
end

subgraph group_alignment["Space alignment"]
  node_alignment_run["Alignment evaluation<br/>[alignment.py]"]
  node_alignment_methods["Alignment methods<br/>[alignment.py]"]
  node_alignment_metrics["Alignment metrics<br/>[alignment.py]"]
  node_prototype_compare["Prototype comparison"]
end

subgraph group_insights["Statistical insights"]
  node_stat_analysis["Metadata regression<br/>[stat_analysis.py]"]
  node_model_metadata["Model metadata<br/>[timm_metadata.py]"]
  node_parallel_plot["Metadata visualization"]
end

node_researcher(("Researcher"))
node_vision_data[("Benchmark images")]
node_timm_models["Pretrained models"]

node_researcher -->|"starts encoding"| node_encode
node_vision_data -->|"supplies images"| node_encode
node_timm_models -->|"provides encoders"| node_encode
node_encode -->|"uses model encoder"| node_timm_encoder
node_encode -->|"writes embeddings"| node_latent_dataset
node_researcher -->|"requests metrics"| node_metric_compute
node_latent_dataset -->|"supplies latents"| node_metric_compute
node_researcher -->|"requests TDA"| node_tda_extract
node_latent_dataset -->|"supplies latents"| node_tda_extract
node_researcher -->|"requests signatures"| node_tsp_extract
node_latent_dataset -->|"supplies latents"| node_tsp_extract
node_researcher -->|"starts evaluation"| node_alignment_run
node_latent_dataset -->|"supplies paired spaces"| node_alignment_run
node_researcher -->|"requests comparison"| node_prototype_compare
node_latent_dataset -->|"supplies model spaces"| node_prototype_compare
node_researcher -->|"starts regression"| node_stat_analysis
node_model_metadata -.->|"provides metadata"| node_stat_analysis
node_metric_compute -.->|"analyzes spaces"| node_latent_space
node_latent_space -.->|"supports prototypes"| node_prototype_metrics
node_latent_space -.->|"provides embeddings"| node_graph_object
node_graph_object -->|"builds neighborhood graph"| node_knn_graph
node_graph_object -->|"computes spectrum"| node_laplacian
node_graph_object -->|"computes metrics"| node_graph_metrics
node_knn_graph -->|"passes adjacency"| node_laplacian
node_tda_extract -.->|"extracts features"| node_tda_features
node_alignment_run -.->|"evaluates methods"| node_alignment_methods
node_alignment_run -.->|"scores results"| node_alignment_metrics
node_latent_space -->|"visualizes spaces"| node_latent_plots
node_researcher -->|"views TDA results"| node_tda_plots
node_stat_analysis -.->|"visualizes statistics"| node_parallel_plot

click node_encode "https://github.com/spaicom/semasia-datasets/blob/main/scripts/encode_dataset_all_timm.py"
click node_timm_encoder "https://github.com/spaicom/semasia-datasets/blob/main/src/models/timm.py"
click node_metric_compute "https://github.com/spaicom/semasia-datasets/blob/main/scripts/compute_metrics.py"
click node_latent_space "https://github.com/spaicom/semasia-datasets/blob/main/src/objects/latent.py"
click node_prototype_metrics "https://github.com/spaicom/semasia-datasets/blob/main/src/metrics/prototypes.py"
click node_graph_object "https://github.com/spaicom/semasia-datasets/blob/main/src/objects/graph.py"
click node_graph_metrics "https://github.com/spaicom/semasia-datasets/blob/main/src/metrics/graph.py"
click node_knn_graph "https://github.com/spaicom/semasia-datasets/blob/main/src/tsp/graph_inference.py"
click node_laplacian "https://github.com/spaicom/semasia-datasets/blob/main/src/tsp/laplace.py"
click node_tda_features "https://github.com/spaicom/semasia-datasets/blob/main/src/tda/features.py"
click node_tda_extract "https://github.com/spaicom/semasia-datasets/blob/main/scripts/tda_extraction.py"
click node_tsp_extract "https://github.com/spaicom/semasia-datasets/blob/main/scripts/tsp_extraction.py"
click node_alignment_run "https://github.com/spaicom/semasia-datasets/blob/main/scripts/alignment.py"
click node_alignment_methods "https://github.com/spaicom/semasia-datasets/blob/main/src/objects/alignment.py"
click node_alignment_metrics "https://github.com/spaicom/semasia-datasets/blob/main/src/metrics/alignment.py"
click node_prototype_compare "https://github.com/spaicom/semasia-datasets/blob/main/scripts/prototype_comparison.py"
click node_stat_analysis "https://github.com/spaicom/semasia-datasets/blob/main/scripts/stat_analysis.py"
click node_model_metadata "https://github.com/spaicom/semasia-datasets/blob/main/src/utils/timm_metadata.py"
click node_latent_plots "https://github.com/spaicom/semasia-datasets/blob/main/src/plotting/latent.py"
click node_tda_plots "https://github.com/spaicom/semasia-datasets/blob/main/src/plotting/tda.py"
click node_parallel_plot "https://github.com/spaicom/semasia-datasets/blob/main/src/visualizations/parallel_coordinates.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_encode,node_timm_encoder,node_latent_dataset toneBlue
class node_metric_compute,node_latent_space,node_prototype_metrics,node_graph_object,node_graph_metrics,node_knn_graph,node_laplacian,node_tda_features,node_tda_extract,node_tsp_extract,node_latent_plots,node_tda_plots,node_vision_data toneAmber
class node_alignment_run,node_alignment_methods,node_alignment_metrics,node_prototype_compare toneMint
class node_stat_analysis,node_model_metadata,node_parallel_plot toneRose
class node_researcher,node_timm_models toneIndigo
```

## Components

### Embedding generation

- [Dataset encoding](https://github.com/spaicom/semasia-datasets/blob/main/scripts/encode_dataset_all_timm.py): `scripts/encode_dataset_all_timm.py`
- [Timm encoder](https://github.com/spaicom/semasia-datasets/blob/main/src/models/timm.py): `src/models/timm.py`
- **Latent dataset**

### Latent analysis

- [Metric extraction](https://github.com/spaicom/semasia-datasets/blob/main/scripts/compute_metrics.py): `scripts/compute_metrics.py`
- [Latent-space operations](https://github.com/spaicom/semasia-datasets/blob/main/src/objects/latent.py): `src/objects/latent.py`
- [Prototype metrics](https://github.com/spaicom/semasia-datasets/blob/main/src/metrics/prototypes.py): `src/metrics/prototypes.py`
- [Graph analysis](https://github.com/spaicom/semasia-datasets/blob/main/src/objects/graph.py): `src/objects/graph.py`
- [Graph metrics](https://github.com/spaicom/semasia-datasets/blob/main/src/metrics/graph.py): `src/metrics/graph.py`
- [KNN construction](https://github.com/spaicom/semasia-datasets/blob/main/src/tsp/graph_inference.py): `src/tsp/graph_inference.py`
- [Spectral methods](https://github.com/spaicom/semasia-datasets/blob/main/src/tsp/laplace.py): `src/tsp/laplace.py`
- [TDA features](https://github.com/spaicom/semasia-datasets/blob/main/src/tda/features.py): `src/tda/features.py`
- [TDA extraction](https://github.com/spaicom/semasia-datasets/blob/main/scripts/tda_extraction.py): `scripts/tda_extraction.py`
- [Graph signatures](https://github.com/spaicom/semasia-datasets/blob/main/scripts/tsp_extraction.py): `scripts/tsp_extraction.py`
- [Latent visualizations](https://github.com/spaicom/semasia-datasets/blob/main/src/plotting/latent.py): `src/plotting/latent.py`
- [TDA visualizations](https://github.com/spaicom/semasia-datasets/blob/main/src/plotting/tda.py): `src/plotting/tda.py`

### Space alignment

- [Alignment evaluation](https://github.com/spaicom/semasia-datasets/blob/main/scripts/alignment.py): `scripts/alignment.py`
- [Alignment methods](https://github.com/spaicom/semasia-datasets/blob/main/src/objects/alignment.py): `src/objects/alignment.py`
- [Alignment metrics](https://github.com/spaicom/semasia-datasets/blob/main/src/metrics/alignment.py): `src/metrics/alignment.py`
- [Prototype comparison](https://github.com/spaicom/semasia-datasets/blob/main/scripts/prototype_comparison.py): `scripts/prototype_comparison.py`

### Statistical insights

- [Metadata regression](https://github.com/spaicom/semasia-datasets/blob/main/scripts/stat_analysis.py): `scripts/stat_analysis.py`
- [Model metadata](https://github.com/spaicom/semasia-datasets/blob/main/src/utils/timm_metadata.py): `src/utils/timm_metadata.py`
- [Metadata visualization](https://github.com/spaicom/semasia-datasets/blob/main/src/visualizations/parallel_coordinates.py): `src/visualizations/parallel_coordinates.py`

### Other components

- **Researcher**
- **Benchmark images**
- **Pretrained models**

## Connections

- Researcher → Dataset encoding: starts encoding
- Benchmark images → Dataset encoding: supplies images
- Pretrained models → Dataset encoding: provides encoders
- Dataset encoding → Timm encoder: uses model encoder
- Dataset encoding → Latent dataset: writes embeddings
- Researcher → Metric extraction: requests metrics
- Latent dataset → Metric extraction: supplies latents
- Researcher → TDA extraction: requests TDA
- Latent dataset → TDA extraction: supplies latents
- Researcher → Graph signatures: requests signatures
- Latent dataset → Graph signatures: supplies latents
- Researcher → Alignment evaluation: starts evaluation
- Latent dataset → Alignment evaluation: supplies paired spaces
- Researcher → Prototype comparison: requests comparison
- Latent dataset → Prototype comparison: supplies model spaces
- Researcher → Metadata regression: starts regression
- Model metadata → Metadata regression: provides metadata
- Metric extraction → Latent-space operations: analyzes spaces
- Latent-space operations → Prototype metrics: supports prototypes
- Latent-space operations → Graph analysis: provides embeddings (evidence: `src/objects/latent.py`)
- Graph analysis → KNN construction: builds neighborhood graph (evidence: `src/objects/graph.py`)
- Graph analysis → Spectral methods: computes spectrum (evidence: `src/objects/graph.py`)
- Graph analysis → Graph metrics: computes metrics (evidence: `src/objects/graph.py`)
- KNN construction → Spectral methods: passes adjacency (evidence: `src/tsp/graph_inference.py`)
- TDA extraction → TDA features: extracts features
- Alignment evaluation → Alignment methods: evaluates methods
- Alignment evaluation → Alignment metrics: scores results
- Latent-space operations → Latent visualizations: visualizes spaces (evidence: `src/plotting/latent.py`)
- Researcher → TDA visualizations: views TDA results
- Metadata regression → Metadata visualization: visualizes statistics
