Multitable 5D Analysis — Relational Hypergraph Transformer (RHT)

Reference implementation for 5D multi-table analysis with RHT.

Current Status (2026-07-01)

• Core package available: rht/, pipeline/, evaluation/
• Empirical harness available: experiments/run.py (Synthea), experiments/run_mimic.py (MIMIC-IV demo)
• Local benchmark available: benchmarks/local_csv_benchmark.py
• Latest benchmark aggregation documented in docs/PHASE1_VALIDATION_RESULTS.md
• Manuscript revision workflow documented in docs/APPLY_REVISIONS.md

Architecture Overview

The repository is organized around four layers:

1. Core model layer — RHT modules and extensions in rht/ and rht_ext/
2. Pipeline layer — multi-table orchestration and feature propagation in pipeline/
3. Evaluation layer — metrics and scoring utilities in evaluation/
4. Execution layer — reproducible experiments and benchmarks in experiments/ and benchmarks/

What the project covers

The framework addresses the 5 dimensions of multi-table complexity:

Dimension	Description
D1	Volume (large relational datasets)
D2	Variable multiplicity (wide tables)
D3	High categorical cardinality (long-tail codes)
D4	Multi-table relational structure
D5	Irregular temporal measurements

Repository Layout

multitable-5D-analysis/
├── rht/                     # Core RHT model and modules
├── rht_ext/                 # Sparse attention extension
├── pipeline/                # Multi-table pipeline orchestration
├── evaluation/              # Metrics and scoring helpers
├── experiments/             # Synthea + MIMIC-IV demo experiments
├── benchmarks/              # Local benchmark scripts
├── data/mimic-iv-demo/      # Bundled demo CSVs
├── benchmark_results/       # Historical benchmark outputs
├── tests/                   # Unit tests
├── configs/                 # Configuration files
├── README.md                # Project overview
├── docs/                    # Documentation hub and guides
│   ├── README.md            # Documentation start page
│   ├── START_HERE.md        # Quick start
│   ├── INDEX.md             # Documentation index
│   ├── REPOSITORY_STRUCTURE.md
│   ├── APPLY_REVISIONS.md
│   └── SUBMISSION_CHECKLIST.md
├── manuscript/              # Manuscript source and build artifacts
│   ├── MANUSCRIPT_REVISIONS.tex
│   ├── results.tex
│   └── MANUSCRIPT_REVISIONS.pdf
├── experiments/README.md    # Run instructions
└── docs/PHASE1_VALIDATION_RESULTS.md

Main Entry Points

• experiments/run.py — Synthea experiment harness
• experiments/run_mimic.py — MIMIC-IV demo harness
• benchmarks/local_csv_benchmark.py — local benchmark on bundled CSV files
• experiments/test_sparse_equiv.py — sparse-vs-dense attention check

Install

git clone https://github.com/edlansiaux/multitable-5d-analysis.git
cd multitable-5d-analysis
pip install -e .

Run options

1) Local benchmark on bundled MIMIC-IV demo CSV

python benchmarks/local_csv_benchmark.py \
  --subsets QUARTER HALF FULL \
  --configs RHT-TinyEmbed RHT-Full \
  --epochs 1 \
  --out-dir benchmark_results

2) Synthea experiment harness

python experiments/run.py \
  --data_dir /path/to/synthea/output/csv \
  --seeds 0 1 2 3 4 \
  --epochs 50 \
  --out manuscript/results.tex

3) MIMIC-IV demo harness

python experiments/run_mimic.py \
  --data_dir data/mimic-iv-demo \
  --seeds 0 1 2 3 4 \
  --epochs 30 \
  --out manuscript/results_mimic.tex

Project Scope

This repository is meant to support reproducible validation on open or bundled data.

• Synthea: primary empirical harness for the manuscript revision workflow
• MIMIC-IV demo: local benchmark and demo run support
• manuscript/results.tex: source of truth for manuscript tables generated from runs

Documentation map

• Documentation home: docs/README.md
• Start guide: docs/START_HERE.md
• Navigation index: docs/INDEX.md
• Repository map: docs/REPOSITORY_STRUCTURE.md
• Integration summary: docs/INTEGRATION_SUMMARY.md
• Final status snapshot: docs/FINAL_STATUS.txt
• Phase 1 benchmark results: docs/PHASE1_VALIDATION_RESULTS.md
• Experiments guide: experiments/README.md
• Manuscript revision guide: docs/APPLY_REVISIONS.md
• Submission checklist: docs/SUBMISSION_CHECKLIST.md

Key Integrity Notes

• Do not report placeholders as measured values.
• Keep manuscript/results.tex generated from runs as the single source of experimental numbers.
• TGN in the baseline module remains a stub unless explicitly integrated.

License

MIT — see LICENSE.