TwinWeaver is a longitudinal framework for LLM-based Patient Digital Twins. It serializes longitudinal patient histories into text, enabling unified event prediction as well as forecasting with large language models (LLMs). This framework transforms structured patient historyβincluding demographics, labs, treatments, and geneticsβinto a single, human-readable text prompt, enabling LLMs to jointly forecast continuous biomarkers and predict discrete clinical events.
- Python 3.8 or higher
- Core dependencies:
pandas,numpy,transformers,scikit-learn
To install the package:
pip install twinweaverThe following sections will explain the tutorials/examples and afterwards the quick start guide.
The examples/ directory provides comprehensive tutorials to help you get up and running.
These notebooks cover the primary workflows for most users:
- 1. Basics Overview:
examples/01_data_preparation_for_training.ipynb- Demonstrates how to convert raw patient data (events, constants, genetics) into the instruction-tuning text format used by TwinWeaver. This is the core step for preparing data for fine-tuning.
- 2. Inference:
examples/02_inference_prompt_preparation.ipynb- Shows how to run inference using the TwinWeaver framework, including setting up the data manager and generating prompts.
- 3. End-to-End Workflow:
examples/03_end_to_end_llm_finetuning.ipynb- A complete guide covering the entire pipeline from data ingestion to LLM fine-tuning.
- NOTE: please install the packages required via the exact following line
pip install twinweaver[fine-tuning-example](torch CUDA version might need to be adapted to your system)
For users needing custom behavior or specific integrations:
- Pretraining Data Conversion:
examples/advanced/pretraining/prepare_pretraining_data.py- A script illustrating how to convert data for the pretraining phase, using template-based generation. Useful if you want to pretrain on your own large-scale unlabeled clinical data.
- Custom Splitting:
examples/advanced/custom_splitting/inference_individual_splitters.py: Example script for inference using individual splitters.examples/advanced/custom_splitting/training_individual_splitters.ipynb: Notebook demonstrating training data generation with individual splitters.
- MEDS Data Import:
examples/integrations/meds_data_import.ipynb- A tutorial on importing data in the Medical Event Data Standard (MEDS) format and converting it into TwinWeaver's internal format. Includes a synthetic data example.
TwinWeaver addresses the challenge of modeling sparse, multi-modal clinical time series by leveraging the generative capabilities of LLMs.
- Text Serialization: Transforms multi-modal inputs (diagnoses, laboratory measurements, genetic mutation panels) into a structured textual representation of longitudinal patient trajectories.
- Unified Task Support:
- Time-Series Forecasting: Forecasting frequently measured values such as blood biomarkers or vital signs.
- Landmark Event Prediction: Predicting patient event status (e.g., survival, disease progression) at future time points using a landmarking framework.
- Flexible Horizon: Supports sampling split times and prediction horizons to avoid overfitting to specific canonical time points.
Full documentation is available https://mendenlab.github.io/TwinWeaver/.
Here's a minimal example to get you started with TwinWeaver:
import pandas as pd
from twinweaver import (
DataManager,
Config,
DataSplitterForecasting,
DataSplitterEvents,
ConverterInstruction,
DataSplitter,
)
# Load your patient data <----- assuming your data is in df_events, df_constant and df_constant_description
dm = DataManager(config=config)
dm.load_indication_data(df_events=df_events, df_constant=df_constant, df_constant_description=df_constant_description)
dm.process_indication_data()
dm.setup_unique_mapping_of_events()
dm.setup_dataset_splits()
dm.infer_var_types()
# This data splitter handles event prediction tasks
data_splitter_events = DataSplitterEvents(dm, config=config)
data_splitter_events.setup_variables()
# This data splitter handles forecasting tasks
data_splitter_forecasting = DataSplitterForecasting(
data_manager=dm,
config=config,
)
# We will also use the easier interface that combines both data splitters
data_splitter = DataSplitter(data_splitter_events, data_splitter_forecasting)
# Set up the converter instruction
converter = ConverterInstruction(
nr_tokens_budget_total=8192,
config=config,
dm=dm,
variable_stats=data_splitter_forecasting.variable_stats, # Optional, needed for forecasting QA tasks
)
patient_data = dm.get_patient_data("patient_id_0") # <--- Set your patient id here
forecasting_splits, events_splits, reference_dates = data_splitter.get_splits_from_patient_with_target(patient_data)
training_data = converter.forward_conversion(
forecasting_splits=forecasting_splits[split_idx],
event_splits=events_splits[split_idx],
override_mode_to_select_forecasting="both",
)
# training_data now contains (Input, Target) pairs ready for LLM fine-tuningFor complete tutorials, see the Tutorials & Examples section above.
TwinWeaver expects three primary dataframes (or CSV files) as input. Example files can be found in examples/example_data/.
Contains time-varying clinical data where each row represents a single event.
| patientid | date | event_descriptive_name | event_category | event_name | event_value | meta_data | source |
|---|---|---|---|---|---|---|---|
| Unique identifier for the patient | Date of the event | Human-readable name used in the text output | (Optional) Category (e.g., lab, drug) |
(Optional) Specific event identifier | Value associated with the event | (Optional) Additional metadata | (Optional) Source of the data - e.g. events or genetic |
Contains static patient information (demographics, baseline characteristics). One row per patient.
| patientid | e.g. birthyear | e.g. gender | ... |
|---|---|---|---|
| Unique identifier for the patient | e.g. Patient's year of birth | e.g. Patient's gender | Any other static patient attributes |
Maps columns in the constant table to human-readable descriptions for the text prompt.
| variable | comment |
|---|---|
| Name of the column in the constant table | Description of the variable for the text prompt |
TwinWeaver supports two primary data formats, each serving a distinct stage in the model training pipeline:
-
Pretraining Data:
- Purpose: Continued Pretraining (CPT) to adapt a general-purpose LLM to the clinical domain.
- Format: A narrative-style serialization of the entire patient history. It does not contain specific questions or answers but rather presents the patient's chronological journey as a continuous text.
- Goal: Enables the model to learn medical terminology, clinical relationships, and temporal dynamics in an unsupervised manner (next-token prediction).
- Converter:
twinweaver.pretrain.converter_manual_template.ConverterPretrain
-
Instruction Data:
- Purpose: Supervised Fine-Tuning (SFT) to teach the model to perform specific clinical tasks.
- Format: Structured into "Input" (Prompt) and "Target" (Completion) pairs.
- Input: Patient history up to a specific time point + a list of specific questions (e.g., "Forecast the next 3 weeks of hemoglobin values").
- Target: The ground truth answers to those questions.
- Goal: Optimizes the model for specific downstream applications like forecasting and risk stratification.
- Converter:
twinweaver.instruction.converter_manual_instruction.ConverterInstruction
The paper can be found on Arxiv.
The core authors are: Nikita Makarov, Maria Bordukova, Lena Voith von Voithenberg, Estrella Villanueva Pivel, Sabrina Mielke, Jonathan Wickes, Hanchen Wang, Derek Ma, Keunwoo Choi, Kyunghyun Cho, Stephen Ra, Raul Rodriguez-Esteban, Fabian Schmich, Michael Menden
If you use the package, please cite
TODOThe logo was generated with Nano Banana Pro.
For questions or issues, please raise a Github issue or contact nikita.makarov@roche.com or michael.menden@unimelb.edu.au.
Note: The specific implementation, training, and evaluation code for the GDT model mentioned in the TwinWeaver paper is located in MendenLab/GDT.
GDT is a pan-cancer model instantiated using TwinWeaver, trained on over 93,000 patients across 20 cancer types.
GDT significantly reduces forecasting error, achieving a median Mean Absolute Scaled Error (MASE) of 0.87 compared to 0.97 for strong time-series baselines. Furthermore, it improves risk stratification, achieving an average C-index of 0.703 across survival, progression, and therapy switching tasks. GDT also demonstrates capabilities in zero-shot generalization to out-of-distribution clinical trials and supports an interpretable clinical reasoning extension.
To run the test suite:
pip install pytest pytest-cov
pytest tests/TwinWeaver is licensed under the Apache License 2.0. See LICENSE for details.
We welcome contributions to TwinWeaver! Please follow these steps to contribute.
-
Clone the repository and install dependencies:
git clone https://github.com/MendenLab/TwinWeaver cd twinweaver pip install -e . pip install -r examples/requirements.txt pip install pre-commit pytest pytest-cov pip install -r docs/requirements.txt
-
Install pre-commit hooks: We use
pre-committo ensure code formatting and quality checks run before you commit.pre-commit install
We use pytest for testing. To run the full test suite:
pytest tests/The documentation is built with mkdocs. To preview it locally:
mkdocs serve- Create a New Branch: Always create a new branch for your feature or fix.
git checkout -b feature/my-new-feature
- Make Changes: Implement your feature or fix.
- Run Tests & Linting: Ensure your code passes all tests and pre-commit hooks.
- Submit a Merge Request:
- Push your branch to the repository.
- Open a Merge Request (Pull Request) against the
mainbranch. - Describe your changes clearly in the MR description.