Practical overview
When it fits
Use Odyssey when a research workflow needs patient-timeline event forecasting or time-to-event hazard estimates and an evaluation harness for examining concept-bottleneck reliability.
Who it is for
- Researchers studying machine learning on electronic health records.
- Developers and research teams preparing clinical event data in the MEDS schema.
- Practitioners evaluating event forecasting, time-to-event estimates or concept-level model representations.
Documented uses
- Forecast which clinical events may occur next in a patient timeline and when.
- Estimate discrete-time hazards for specified clinical outcomes.
- Inspect rule-derived concepts, unnamed concepts and residual representations alongside predictions.
- Evaluate the reliability of a model's concept bottleneck.
- Prepare MIMIC-IV data through the documented MEDS extraction workflow.
Requirements & limits
The repository documents installation with Python 3.12 or later and uv. Its public MIMIC-IV demo extraction is documented as requiring no credentials. Building the mamba-ssm hybrid backbone requires CUDA and nvcc; the documented pure-PyTorch fallback supports inference without mamba-ssm, while training still needs CUDA.
- The common data interface is MEDS, so dataset preparation must produce data conforming to that event schema.
- The README distinguishes a public MIMIC-IV demo extraction from a full-release workflow using a local input directory.
- The hybrid backbone's mamba-ssm dependency requires CUDA and nvcc to build; the pure-PyTorch fallback is described for inference, not training.
- The model estimates hazards for specified clinical outcomes and forecasts timeline events; the harness evaluates concept-bottleneck trustworthiness.
- A trained checkpoint is needed for checkpoint-based inference, with checkpoint guidance referenced by the README.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Set up Odyssey and prepare the public MIMIC-IV demo
Install the repository dependencies and create the documented public demo dataset in MEDS form.
Before you start
- Python 3.12 or later
- uv
- A shell environment in which Git and the documented uv commands are available
Steps
Clone https://github.com/VectorInstitute/odyssey.git and change into the odyssey directory.
Run the command below to install the development dependencies.
uv sync --devRun the command below to prepare the public demo data.
uv run meds-extract-run spec=MIMIC-IV output_dir= dataset_key=demo
Expected outcome
The documented setup is in place and the MIMIC-IV public demo extraction is directed to the chosen output directory.
Guide limitations
- This recipe prepares demo data; it does not document training or running a model prediction.
- The public demo is distinct from the full MIMIC-IV release, which uses a local input directory and has separate data requirements.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 13 October 2026
- Original website title
- GitHub - VectorInstitute/odyssey: An interpretable foundation model of the patient clinical timeline: event forecasting, calibrated time-to-event alerts, and concept-level interpretability, benchmarked head-to-head against tuned GBMs, tabul · Official homepage title · retained in its source language