双重织者

Requirements

• Python 3.8 or higher
• Core dependencies: pandas, numpy, transformers, scikit-learn

The following sections will explain the tutorials/examples and afterwards the quick start guide.

⚙️ Installation

Install from PyPi

To install the package:

pip install twinweaver

Development Setup

1. 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
    

2. Install pre-commit hooks: We use pre-commit to ensure code formatting and quality checks run before you commit.

    pip install pre-commit
    pre-commit install
    

Building Documentation

The documentation is built with mkdocs. To preview it locally:

mkdocs serve

💡 Tutorials & Examples

The examples/ directory provides comprehensive tutorials to help you get up and running.

🔰 Core Tutorials

These notebooks cover the primary workflows for most users:

• 0. Raw Data Preprocessing: examples/data_preprocessing/raw_data_preprocessing.ipynb
• Start here if you have raw clinical data (e.g., EHR exports). Shows how to transform raw data into the three TwinWeaver dataframes (df_events, df_constant, df_constant_description), including handling death events and other time-to-event outcomes.
• 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)

🚀 Advanced Usage & Integrations

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.
• End-to-End LLM Training with Pretrain Data: examples/advanced/pretraining/end_to_end_llm_training_with_pretrain.ipynb
• A complete notebook demonstrating how to fine-tune an LLM on pretraining data (full patient histories without specific tasks). This enables training models for synthetic patient generation or creating patient embeddings. Uses QLoRA for efficient training on consumer GPUs.
• NOTE: Requires a GPU with at least 30GB of memory. Install fine-tuning packages with pip install twinweaver[fine-tuning-example].
• 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.
• examples/advanced/custom_splitting/training_custom_split_events.ipynb: Notebook showing how to customize split events and forecast different event categories.
• examples/advanced/custom_splitting/training_forecasting_splitter_only.ipynb: Forecasting-only example showing training data generation using only the DataSplitterForecasting (no event splitter).
• examples/advanced/custom_splitting/training_forecasting_qa.ipynb: Demonstrates the Forecasting QA mode, which bins continuous target values into discrete categories for classification-style prediction, and compares all three forecasting modes ("forecasting", "forecasting_qa", "both").
• Custom Text Generation: examples/advanced/custom_output/customizing_text_generation.ipynb
• A comprehensive tutorial on customizing every textual component of the instruction generation pipeline. Learn how to modify preambles, event formatting, time units, genetic data tags, forecasting prompts, and more to adapt outputs for different LLMs, languages, or institutional requirements.
• Custom Summarized Row: examples/advanced/custom_output/custom_summarized_row.ipynb
• Shows how to customize the summarized row section of the instruction prompt using set_custom_summarized_row_fn(). Includes minimal and advanced examples, plus error handling guidance.
• TTE Probability Inference: examples/advanced/tte_inference/tte_probability_inference.ipynb
• Demonstrates how to estimate calibrated probabilities for time-to-event outcomes (e.g., death, disease progression) using a fine-tuned LLM served via vLLM. Scores three mutually exclusive completions per patient and derives softmax probabilities from length-normalised log-probabilities. Includes evaluation across multiple time horizons. See the TTE Probability Inference documentation for a detailed explanation of the mechanism.
• NOTE: Requires a fine-tuned model for meaningful results and a GPU with enough memory for vLLM.
• 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.

🚀 Quick Start

Here's a minimal example to get you started with TwinWeaver:

```python import pandas as pd

from twinweaver import ( DataManager, Config, DataSplitterForecasting, DataSplitterEvents, ConverterInstruction, DataSplitter, )

Initialize config and set up splitting/prediction variables

config = Config()

<---------------------- CRITICAL CONFIGURATION ---------------------->

We will also use the easier interface that combines both data splitters

data_splitter = DataSplitter(data_splitter_events, data_splitter_forecasting)

Core Components

1. Text Serialization: Transforms multi-modal inputs (diagnoses, laboratory measurements, genetic mutation panels) into a structured textual representation of longitudinal patient trajectories. 2. 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. 3. Flexible Horizon: Supports sampling split times and prediction horizons to avoid overfitting to specific canonical time points.

Contribution Workflow

1. Create a New Branch: Always create a new branch for your feature or fix.

    git checkout -b feature/my-new-feature
    

📂 Dataset Types: Instruction vs. Pretraining

TwinWeaver supports two primary data formats, each serving a distinct stage in the model training pipeline:

1. 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

2. 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

Further details at https://mendenlab.github.io/TwinWeaver/framework/.