pericleshat/tacco

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.