clinicalplan 0.1.0

ClinicalPLAN is a Python package for predicting postoperative risks from clinical notes using language models. It provides training and inference workflows for fine-tuned models, semi-supervised methods, and multi-task prediction of multiple clinical outcomes. The package is intended for clinical research and educational use, notably for the American College of Surgeons.

Overview

ClinicalPLAN (Clinical Postoperative Risk Prediction with Language Models Adapting to Clinical Notes) is a Python package for predicting postoperative risks from clinical notes using language models. It provides flexible and clinically oriented workflows that support a range of perioperative use cases, enabling clinicians, researchers, and healthcare institutions to train and fine-tune models using preoperative or intraoperative clinical text.

The package is designed to be accessible to a broad range of users, including clinicians, surgeons, and researchers with limited programming experience. It minimizes the need to interact with lower-level machine learning frameworks such as PyTorch. With just a few lines of high-level functions, users can begin training and fine-tuning their own models.

ClinicalPLAN supports multiple modeling strategies, including:

1. Direct inference with fine-tuned language models
2. Semi-supervised learning approaches for leveraging partially labeled data
3. A multi-task learning framework that enables simultaneous prediction of multiple postoperative outcomes

The package was developed for the American College of Surgeons (ACS) workshop, AI for Clinicians and Surgeons: A Hands-On Introduction Across the Care Continuum.

The accompanying work is:
The foundational capabilities of large language models in predicting postoperative risks using clinical notes
Alba, Xue, Abraham, Kannampallil, and Lu (2025), npj Digital Medicine

---

Installation

pip install clinicalplan

Because torch CUDA wheels aren't hosted on PyPI, install PyTorch first matching your GPU's CUDA version, then install this package. For example, on a machine with CUDA 11.8 drivers:

pip install torch==2.1.2 --index-url https://download.pytorch.org/whl/cu118
pip install clinicalplan

Python version: 3.9–3.11 (tested on 3.11).

---

Quick example

import pandas as pd
from MultiTaskLearningPrediction import mtl_finetune, get_postoperative_outcome_scores

df = pd.read_csv("my_clinical_data.csv")
# df columns: "text", "Outcome_1", "Outcome_2", "Outcome_3", "Outcome_4"

# 1. Fine-tune
mtl_finetune(
    df,
    text_col="text",
    outcome_cols=["Outcome_1", "Outcome_2", "Outcome_3", "Outcome_4"],
    output_dir="my_finetuned_model",
)

# 2. Score a new scenario
scores = get_postoperative_outcome_scores(
    "my_finetuned_model",
    "total knee arthroplasty"
)
# {'Outcome_1': 0.12, 'Outcome_2': 0.28, 'Outcome_3': 0.04, 'Outcome_4': 0.39}

---

API reference

MultiTaskLearningPrediction

Multi-Task Learning (MTL) allows you to train a single versatile model capable of predicting multiple postoperative outcomes from the same clinical notes. Unlike traditional finetuning strategies — where you'd need to train a single model for each outcome — MTL allows you to create a model capable of simultaneously predicting multiple risks — analogous to foundation models.

Example

mtl_finetune(
    df,
    text_col="clincal_notes",
    outcome_cols=["death_30d", "dvt", "pneumonia", "aki", "AUR", "PE"],
    output_dir="my_run",
    training_configs={
        "num_train_epochs": 3,
        "per_device_train_batch_size": 16,
        "evaluation_strategy": "steps",
        "eval_steps": 100,
        "logging_steps": 100,     
        "learning_rate": 2e-5
        }
)

Fine-tune Bio+ClinicalBERT on MLM jointly with one binary classification head per outcome.

Parameters

• df (pandas.DataFrame, required): Must contain text_col and all outcome_cols.
• text_col (str, required): Name of the free-text column.
• outcome_cols (list[str], required): Names of binary (0/1) outcome columns. One auxiliary head is trained per outcome. Rows with NaN in a given outcome are dropped for that outcome's task but used for the others.
• output_dir (str, default "mtl_finetuned"): Directory to save the fine-tuned model, tokenizer, and metadata. Also used as the HuggingFace Trainer output_dir for checkpoints and logs.
• base_model (str, default "emilyalsentzer/Bio_ClinicalBERT"): HuggingFace model id to start from. Any BERT-architecture model should work.
• max_length (int, default 512): Token sequence length for tokenization.
• lambda_constant (float, default 2): Weight on the auxiliary (per-outcome BCE) loss relative to MLM loss. Total loss = MLM + λ · mean(per-task BCE).
• val_fraction (float, default 1/8): Fraction of df held out for validation during training.
• training_configs (dict | None, default None): Any keyword arguments accepted by transformers.TrainingArguments. User-provided values override the defaults below. Default training_configs is {"num_train_epochs": 5, "per_device_train_batch_size": 24, "per_device_eval_batch_size": 24, "learning_rate": 1e-5, "warmup_ratio": 0.06, "weight_decay": 1e-3, "logging_steps": 1000 "save_strategy": "epoch", "seed": 42,}

Returns

str — the output_dir path. After training, this directory contains:

• pytorch_model.bin (or model.safetensors) — model weights
• config.json — model architecture config
• tokenizer.json, vocab.txt, tokenizer_config.json, special_tokens_map.json — tokenizer
• mtl_metadata.json — records outcome_cols, text_col, max_length, base_model, lambda_constant, num_tasks so inference can recover them automatically
• checkpoint-* — per-epoch training checkpoints (can be deleted after training)
• logs/ — TensorBoard-compatible training logs

---

get_postoperative_outcome_scores

Score a text scenario (or list of scenarios) against each auxiliary head of a fine-tuned MTL model.

Example

get_postoperative_outcome_scores(
    model_name,
    text,
    outcomes=["death_30d", "dvt", "pneumonia", "aki", "AUR", "PE"],
)

Parameters

• model_name (str, required): Path to a directory saved by mtl_finetune.
• text (str | list[str], required): One scenario string, or a list of them. Determines the shape of the return value.
• outcomes (list[str] | None, default: None): Which outcomes to score. Defaults to all outcomes the model was trained on, recovered from mtl_metadata.json. Pass a subset to score only some. Names must match those used in mtl_finetune.
• max_length (int | None, default: None): Token sequence length. Defaults to the value used during fine-tuning, recovered from metadata, otherwise 512.
• device (str | None, default: None): "cuda", "cpu", or None to auto-detect.

Returns

• dict[str, float] when text is a string — maps each outcome name to a probability in [0, 1].
• list[dict[str, float]] when text is a list — one dict per input, in the same order.