# pericleshat/tacco architecture

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

- Interactive diagram: https://gitdiagram.com/pericleshat/tacco
- Repository: https://github.com/pericleshat/tacco

## Overview

1. **What this repo is**
   TACCO is a research training codebase for disease subtyping from EHR data. Architecturally, it is a **data-preparation + graph learning + clustering** pipeline rather than a production service.

2. **Primary data boundary**
   The main inputs live under `data/raw_data/` and are split by dataset (`cradle`, `mimic3`). Each dataset folder contains:
   - `hyperedges-*` for the clinical concept/patient-visit graph structure
   - `edge-labels-*` for supervision or evaluation labels
   - `node-embeddings-*` for precomputed feature vectors
   - `node_text.json` for concept text used by the language model path  
   This is the clearest boundary between raw dataset artifacts and model-ready tensors.

3. **Dataset preprocessing and conversion**
   `preprocessing.py` and `convert_datasets_to_pygDataset.py` form the ingest layer. Their role is to transform the raw EHR artifacts into a graph dataset format compatible with PyTorch Geometric. This is the handoff point from “files on disk” to “structured graph objects” used by training.

4. **Text encoding subsystem**
   `bert.py` is the language-model side of the pipeline. It likely converts `node_text.json` into semantic embeddings for clinical concepts using Hugging Face `transformers`. This makes TACCO a hybrid model: graph structure plus text semantics.

5. **Graph / hypergraph modeling**
   `layers.py` and `models.py` contain the core neural architecture. Based on the repo and paper, this layer stack is where patient visits and clinical concepts are embedded and co-clustered using hypergraph-aware message passing. `models.py` is the orchestration layer; `layers.py` is the reusable building-block layer.

6. **Clustering objective**
   `dec.py` suggests a deep embedded clustering component, likely used to refine latent clusters during training. In architecture terms, this is the optimization head that turns learned embeddings into subtyping clusters rather than just representations.

7. **Task-guided alignment**
   `alignment.py` is a distinct subsystem for aligning the two sides of the co-clustering problem: clinical concepts and patient visits. This is important because TACCO is not only learning node embeddings, but also enforcing consistency between the two node types.

8. **Training entry points**
   There are two main executables:
   - `train_tacco.py`: the main TACCO training pipeline
   - `train_hypehr.py`: a hypergraph-related training path, likely a baseline or supporting model  
   These are the top-level runtime boundaries where data, model, and loss functions come together.

9. **Experiment execution**
   `demo.sh` and `KDD24.sh` are the operational wrappers. `demo.sh` is a runnable example end-to-end, while `KDD24.sh` captures the paper’s reported configuration. Training outputs are written to `/logs`, so the repo is oriented around offline experimentation and reproducibility.

10. **External dependencies that shape the architecture**
   The architecture depends heavily on:
   - **PyTorch** for model training
   - **torch_geometric / torch-scatter / torch-sparse / torch-cluster** for graph and hypergraph operations
   - **transformers** for BERT-based text embeddings
   - **pandas / scikit-learn** for data handling and evaluation  
   These dependencies indicate a compute-heavy graph-learning stack with GPU-oriented sparse operations.

11. **End-to-end data flow**
   The typical flow is:
   raw dataset files → preprocessing/conversion → graph dataset objects → optional BERT text embeddings → TACCO model forward pass → alignment + clustering losses → trained embeddings/clusters → logs/results.  
   If drawing the architecture, this is the main left-to-right pipeline.

12. **Repo shape**
   There is no separate backend, API server, or deployment layer. The repository is a self-contained ML research system centered on offline training and evaluation, with `docs/` only providing pipeline visualization.

Main entry points: [`src/train_tacco.py`](https://github.com/pericleshat/tacco/blob/main/src/train_tacco.py) (Train TACCO), [`src/convert_datasets_to_pygDataset.py`](https://github.com/pericleshat/tacco/blob/main/src/convert_datasets_to_pygDataset.py) (To PyG), [`src/models.py`](https://github.com/pericleshat/tacco/blob/main/src/models.py) (TACCO model), [`src/preprocessing.py`](https://github.com/pericleshat/tacco/blob/main/src/preprocessing.py) (Preprocess)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Raw data"]
  node_cradle_raw[("Cradle data<br/>dataset")]
  node_mimic3_raw[("MIMIC-3 data<br/>dataset")]
  node_hyperedges["Hyperedges<br/>graph data"]
  node_edge_labels["Labels<br/>supervision"]
  node_node_embeddings["Embeddings<br/>feature data"]
  node_node_text["Node text<br/>text corpus"]
end

subgraph group_ingest["Ingest"]
  node_preprocessing["Preprocess<br/>ingest script<br/>[preprocessing.py]"]
  node_convert_pyg["To PyG<br/>dataset converter"]
end

subgraph group_model["Modeling"]
  node_bert["BERT encode<br/>text encoder<br/>[bert.py]"]
  node_layers["Layers<br/>[layers.py]"]
  node_models["TACCO model<br/>model orchestration<br/>[models.py]"]
  node_dec(("DEC head<br/>clustering head<br/>[dec.py]"))
  node_alignment["Alignment<br/>loss module<br/>[alignment.py]"]
end

subgraph group_runtime["Training"]
  node_train_tacco["Train TACCO<br/>trainer<br/>[train_tacco.py]"]
  node_train_hypehr["Train HYPEHR<br/>baseline trainer<br/>[train_hypehr.py]"]
  node_demo_sh["Demo run<br/>script<br/>[demo.sh]"]
  node_kdd24_sh["Paper run<br/>script<br/>[KDD24.sh]"]
end

node_readme["README<br/>documentation<br/>[README.md]"]

node_cradle_raw -->|"input"| node_preprocessing
node_mimic3_raw -->|"input"| node_preprocessing
node_preprocessing -->|"prepare"| node_convert_pyg
node_convert_pyg -->|"graph"| node_hyperedges
node_convert_pyg -->|"labels"| node_edge_labels
node_convert_pyg -->|"features"| node_node_embeddings
node_node_text -->|"encode"| node_bert
node_bert -->|"embeddings"| node_models
node_hyperedges -->|"message passing"| node_layers
node_node_embeddings -->|"features"| node_layers
node_layers -->|"representations"| node_models
node_models -->|"align"| node_alignment
node_models -->|"cluster"| node_dec
node_alignment -->|"loss"| node_train_tacco
node_dec -->|"loss"| node_train_tacco
node_train_tacco -->|"run"| node_demo_sh
node_train_tacco -->|"run"| node_kdd24_sh
node_train_hypehr -.->|"alt run"| node_kdd24_sh
node_train_tacco -.->|"documented in"| node_readme

click node_cradle_raw "https://github.com/pericleshat/tacco/tree/main/data/raw_data/cradle"
click node_mimic3_raw "https://github.com/pericleshat/tacco/tree/main/data/raw_data/mimic3"
click node_preprocessing "https://github.com/pericleshat/tacco/blob/main/src/preprocessing.py"
click node_convert_pyg "https://github.com/pericleshat/tacco/blob/main/src/convert_datasets_to_pygDataset.py"
click node_bert "https://github.com/pericleshat/tacco/blob/main/src/bert.py"
click node_layers "https://github.com/pericleshat/tacco/blob/main/src/layers.py"
click node_models "https://github.com/pericleshat/tacco/blob/main/src/models.py"
click node_dec "https://github.com/pericleshat/tacco/blob/main/src/dec.py"
click node_alignment "https://github.com/pericleshat/tacco/blob/main/src/alignment.py"
click node_train_tacco "https://github.com/pericleshat/tacco/blob/main/src/train_tacco.py"
click node_train_hypehr "https://github.com/pericleshat/tacco/blob/main/src/train_hypehr.py"
click node_demo_sh "https://github.com/pericleshat/tacco/blob/main/src/demo.sh"
click node_kdd24_sh "https://github.com/pericleshat/tacco/blob/main/src/KDD24.sh"
click node_readme "https://github.com/pericleshat/tacco/blob/main/README.md"

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_cradle_raw,node_mimic3_raw,node_hyperedges,node_edge_labels,node_node_embeddings,node_node_text toneBlue
class node_preprocessing,node_convert_pyg toneAmber
class node_bert,node_layers,node_models,node_dec,node_alignment toneMint
class node_train_tacco,node_train_hypehr,node_demo_sh,node_kdd24_sh toneRose
class node_readme toneNeutral
```

## Components

### Raw data

Dataset artifacts and concept graphs

- [Cradle data](https://github.com/pericleshat/tacco/tree/main/data/raw_data/cradle): dataset · Raw EHR graph artifacts for the Cradle dataset · `data/raw_data/cradle`
- [MIMIC-3 data](https://github.com/pericleshat/tacco/tree/main/data/raw_data/mimic3): dataset · Raw EHR graph artifacts for the MIMIC-3 dataset · `data/raw_data/mimic3`
- **Hyperedges**: graph data · Patient-visit and concept hypergraph structure
- **Labels**: supervision · Edge or task labels used for training and evaluation
- **Embeddings**: feature data · Precomputed node feature vectors
- **Node text**: text corpus · Clinical concept text used for semantic encoding

### Ingest

Preprocessing and dataset conversion

- [Preprocess](https://github.com/pericleshat/tacco/blob/main/src/preprocessing.py): ingest script · Transforms raw EHR artifacts into model-ready inputs · `src/preprocessing.py`
- [To PyG](https://github.com/pericleshat/tacco/blob/main/src/convert_datasets_to_pygDataset.py): dataset converter · Converts datasets into PyTorch Geometric format · `src/convert_datasets_to_pygDataset.py`

### Modeling

Graph learning, clustering, and alignment

- [BERT encode](https://github.com/pericleshat/tacco/blob/main/src/bert.py): text encoder · Encodes node text into semantic embeddings · `src/bert.py`
- [Layers](https://github.com/pericleshat/tacco/blob/main/src/layers.py): gnn layers · Reusable graph and hypergraph building blocks · `src/layers.py`
- [TACCO model](https://github.com/pericleshat/tacco/blob/main/src/models.py): model orchestration · Main neural architecture and co-clustering workflow · `src/models.py`
- [DEC head](https://github.com/pericleshat/tacco/blob/main/src/dec.py): clustering head · Deep embedded clustering objective and refinement · `src/dec.py`
- [Alignment](https://github.com/pericleshat/tacco/blob/main/src/alignment.py): loss module · Aligns concept and visit representations · `src/alignment.py`

### Training

Entry points and experiment wrappers

- [Train TACCO](https://github.com/pericleshat/tacco/blob/main/src/train_tacco.py): trainer · Main end-to-end training entry point · `src/train_tacco.py`
- [Train HYPEHR](https://github.com/pericleshat/tacco/blob/main/src/train_hypehr.py): baseline trainer · Alternative hypergraph training path · `src/train_hypehr.py`
- [Demo run](https://github.com/pericleshat/tacco/blob/main/src/demo.sh): script · Runnable example pipeline wrapper · `src/demo.sh`
- [Paper run](https://github.com/pericleshat/tacco/blob/main/src/KDD24.sh): script · Paper configuration and experiment wrapper · `src/KDD24.sh`

### Other components

- [README](https://github.com/pericleshat/tacco/blob/main/README.md): documentation · High-level project overview and usage notes · `README.md`

## Connections

- Cradle data → Preprocess: input · Cradle artifacts are ingested for preprocessing
- MIMIC-3 data → Preprocess: input · MIMIC-3 artifacts are ingested for preprocessing
- Preprocess → To PyG: prepare · Preprocessing hands off structured inputs for conversion
- To PyG → Hyperedges: graph · Produces graph structure for training
- To PyG → Labels: labels · Carries supervision into the dataset format
- To PyG → Embeddings: features · Prepares or attaches node features
- Node text → BERT encode: encode · Text is transformed into semantic embeddings
- BERT encode → TACCO model: embeddings · Language-derived features enter the model
- Hyperedges → Layers: message passing · Graph structure drives representation learning
- Embeddings → Layers: features · Initial node features feed the graph layers
- Layers → TACCO model: representations · Layer outputs are assembled by the main model
- TACCO model → Alignment: align · Model representations are regularized across node types
- TACCO model → DEC head: cluster · Latent embeddings are refined into clusters
- Alignment → Train TACCO: loss · Alignment objective participates in TACCO training
- DEC head → Train TACCO: loss · Clustering objective participates in TACCO training
- Train TACCO → Demo run: run · Demo wrapper executes the main training flow
- Train TACCO → Paper run: run · Paper script launches the reported configuration
- Train HYPEHR → Paper run: alt run · Alternative training path can be invoked by experiment scripts
- Train TACCO → README: documented in · Repository usage is described in the README