BD4QoL-Open-Models

Pre-trained machine learning models for predicting Quality of Life (QoL) trajectory changes in head-and-neck cancer patients, released as part of the BD4QoL (Big Data for Quality of Life) project. Each model predicts whether a patient's QoL on a specific scale will deteriorate, remain stable, or improve at the next clinical follow-up, based on passively-collected smartphone behavioral markers and clinical baseline data.

---

Models

34 models are provided across two questionnaires, trained on longitudinal data from head-and-neck cancer patients enrolled in the BD4QoL study, assessed at 6, 12, 18, and 24 months post-treatment.

QLQ-C30 (15 scales)

Scale	Key
Global Health Status	global_health_status
Physical Functioning	physical_functioning
Role Functioning	role_functioning
Emotional Functioning	emotional_functioning
Cognitive Functioning	cognitive_functioning
Social Functioning	social_functioning
Fatigue	fatigue
Nausea / Vomiting	nausea_vomiting
Pain	pain
Dyspnoea	dyspnoea
Insomnia	insomnia
Appetite Loss	apettite_loss
Constipation	constipation
Diarrhoea	diarrhoea
Financial Difficulties	financial_difficulties

HN43 — Head & Neck Cancer Module (19 scales)

Scale	Key
Pain in Mouth	hn43_pain_in_mouth
Swallowing	hn43_swallowing
Problems with Teeth	hn43_problems_with_teeth
Dry Mouth / Sticky Saliva	hn43_dry_mouth_sticky_saliva
Problems with Senses	hn43_problems_with_senses
Speech	hn43_speech
Body Image	hn43_body_image
Social Eating	hn43_social_eating
Sexuality	hn43_sexuality
Problems with Shoulder	hn43_problems_with_shoulder
Skin Problems	hn43_skin_problems
Problems Opening Mouth	hn43_problems_opening_mouth
Coughing	hn43_coughing
Social Contact	hn43_social_contact
Swelling in the Neck	hn43_swelling_in_the_neck
Weight Loss	hn43_weight_loss
Problems Wound Healing	hn43_problems_wound_healing
Neurological Problems	hn43_neurological_problems
Fear of Progression	hn43_fear_of_progression

Output classes

Class	Meaning
-1	Deterioration — change exceeds the Minimum Important Change (MIC) threshold in the worsening direction
0	Stable — no clinically meaningful change
1	Improvement — change exceeds the MIC threshold in the improving direction

MIC thresholds follow scale-specific values from Singer et al. See onnx_models/metadata.json for the exact thresholds applied to each scale.

Architecture

Each model is a scikit-learn Pipeline, and the full pipeline (scaler + classifier) is serialized to ONNX, so no additional preprocessing is required at inference time beyond preparing the feature columns as described below.

---

Repository Structure

open-models/
    metadata.json ← feature columns, MIC thresholds, class labels
    qlq_c30/ ← QLQ-C30 models (15 files)
        global_health_status.onnx
        physical_functioning.onnx
        ...
    hn43/ ← HN43 models (19 files)
        hn43_pain_in_mouth.onnx
        hn43_swallowing.onnx
        ...
predict.py ← inference script

---

Installation

pip install onnxruntime numpy pandas scikit-learn skl2onnx

---

Quick Start

import pandas as pd
from predict import predict, list_available_models

# List all available models (grouped by questionnaire)
print(list_available_models())

# Filter by questionnaire
print(list_available_models(questionnaire="QLQ-C30"))
print(list_available_models(questionnaire="HN43"))

# Load your pre-processed patient data (one row per patient-period)
data = pd.read_csv("new_patients.csv")

# Predict QoL trajectory for a single scale
results = predict(data, scale="global_health_status")
print(results)
# Columns: prediction (-1/0/1), prediction_label

# Include class probabilities
results = predict(data, scale="global_health_status", return_probabilities=True)
# Additional columns: prob_deterioration, prob_stable, prob_improvement

# Predict across all 34 scales at once
from predict import predict_all_scales
all_results = predict_all_scales(data)

---

Data Format

Each row represents one patient at one post-treatment time point. All 34 models share the same input feature set.

Required columns

All feature column names must exactly match those listed in onnx_models/metadata.json under models.<scale>.feature_columns. The set covers:

Behavioural markers — passively collected from the study smartphone app, expressed as the change from the previous window. Examples:

Column	Description
perimeter	Change in mobility polygon perimeter
time_home	Change in time spent at home
screen_on_count	Change in number of screen-on events
steps	Change in daily step count
sleep_duration	Change in estimated sleep duration

Clinical features — from the baseline clinical assessment:

Column	Description
age_of_diagnosis	Age at diagnosis (years)
sex	Sex (integer-encoded)
Stage	Tumour stage
radiotherapy	Whether radiotherapy was administered
total_dose_gy	Total radiation dose (Gy)
primary_tumor_site	Primary tumour site (integer-encoded)
...	(see metadata.json for the full list)

Post-treatment time (4 one-hot columns):

Column	Value
post_treatment_time_6	1 if assessment at 6 months post-treatment, else 0
post_treatment_time_12	1 if assessment at 12 months post-treatment, else 0
post_treatment_time_18	1 if assessment at 18 months post-treatment, else 0
post_treatment_time_24	1 if assessment at 24 months post-treatment, else 0

Exactly one of the four post_treatment_time_* columns must be 1 per row.

Encoding requirements

• All columns must be appropriately pre-processed and encoded as numeric values. For example, categorical features should be integer-encoded.
• Behavioral features are expressed as differences (e.g., current two-week window minus previous two-week window), not raw values.
• Missing values (NaN) are accepted natively and will be handled by the model.

Example

import pandas as pd
from predict import predict

row = {
    "perimeter": 12.4,
    "time_home": -0.5,
    "screen_on_count": 3.1,
    # ... all other feature columns (see metadata.json) ...
    "age_of_diagnosis": 58,
    "sex": 1,             # integer-encoded
    "Stage": 3,
    "post_treatment_time_6": 0,
    "post_treatment_time_12": 1,
    "post_treatment_time_18": 0,
    "post_treatment_time_24": 0,
}

data = pd.DataFrame([row])

# QLQ-C30 scale
print(predict(data, scale="pain"))

# HN43 scale
print(predict(data, scale="hn43_swallowing"))

---

Command-line interface

# List all available models grouped by questionnaire
python predict.py --list

# Predict a single QLQ-C30 scale
python predict.py --input new_data.csv --scale global_health_status

# Predict a single HN43 scale
python predict.py --input new_data.csv --scale hn43_swallowing

# Predict all 34 scales and save results
python predict.py --input new_data.csv --all --output predictions.csv

# Include class probabilities
python predict.py --input new_data.csv --scale fatigue --probabilities

---

Citation

If you use these models in your research, please cite the BD4QoL project:

BD4QoL Consortium. BD4QoL: Big Data Models and Intelligent tools for Quality of Life monitoring and participatory empowerment of head and neck cancer survivors. [Manuscript in preparation / see project page for current reference.]

---

Licence

See LICENSE. The models are released for research use. Clinical deployment requires independent validation.