MBL2 ML-HTLV: Machine Learning for HAM/TSP Prediction

Python codes implementing ten Machine Learning Models (MLMs) to predict progression to HAM/TSP in People Living with HTLV (PLwHTLV).

📁 Repository Structure

The repository organizes four scenarios by dataset, each in a separate folder:

• clinical_dataset: MBL2 as biomarker (haplotypes) with clinical and demographic data.
• MBL2_ILs_dataset: MBL2 (haplotypes) with interleukin levels (TNF, IL10, IL6, IL1, IL8) and demographics.
• MBL2_ILs_significant_variants: MBL2 (per-locus variants) with IL6 (HAM/TSP-associated) and demographics.
• MBL2_non_clinical_dataset: MBL2 (per-locus variants) with demographics only.

For reproducibility and consistency between the analysis scripts and the manuscript, different dataset names were used in the codebase and in the article text. The correspondence between script-level dataset names and manuscript dataset names is described below.

clinical_dataset (Manuscript: MBL2-Haplotypes-Clinical) Dataset containing MBL2 haplotypes evaluated as biomarkers, combined with clinical status (HAM/TSP) and demographic variables.

MBL2_ILs_dataset (Manuscript: MBL2-Haplotypes-ILs) Dataset including MBL2 haplotypes, plasma interleukin levels (TNF, IL-10, IL-6, IL-1β, IL-8), and demographic information.

MBL2_ILs_significant_variants (Manuscript: MBL2_ILs_significant_variants) Dataset comprising per-locus MBL2 genetic variants (MBL-550, MBL-221, MBL EXON), interleukin levels associated with HAM/TSP (IL-6), and demographic variables.

MBL2_non_clinical_dataset (Manuscript: MBL2-Variants-Demographics) Dataset containing per-locus MBL2 genetic variants and demographic variables only, without clinical status or cytokine measurements.

Each folder contains:

• datasets/: Datasets used in the pipeline.
• exploratoryanalysis/: Exploratory data analysis results.
• models/: Trained ML models.
• results/: Performance metrics and XAI outputs.
• scripts/: Jupyter notebooks and auxiliary scripts.

📋 Main Notebooks

Four main notebooks per scenario implement the complete pipeline:

• 1_MEST-HTLV_MBL2_CLINICAL_Exploratory_analysis.ipynb: Exploratory data analysis.
• 2_MEST-HTLV_MBL2_CLINICAL_Define_models_and_optimization.ipynb: Model definition and hyperparameter optimization.
• 3_MEST-HTLV_MBL2_CLINICAL_Evaluation_metrics.ipynb: Predictive performance evaluation.
• 4_MEST-HTLV_MBL2_CLINICAL_XAI.ipynb: Explainable AI (XAI) methods.

📊 Data Dictionary

Demographic and Outcome Variables

Column	Encoding
SEX	M=0, F=1
HAMTSP	No myelopathy=0, HAM/TSP=1

• Time living with HTLV: In years (continuous variable)

MBL2 SNPs dictonary and haplotype encoding (3 functional levels)

Applied independently per locus (-550, -221, Exon 1):

• SNPs of MBL2:
  • MBL-550:
    • HH = 0
    • HL = 1
    • LL = 2
  • MBL-221:
    • YY = 0
    • YX = 1
    • XX = 2
  • MBL EXON:
    • AO = 0
    • AA = 1
    • OO = 2

MBL2 Producer Categories (Individual Level)

Genotypes were grouped into three functional categories based on predicted MBL serum levels, considering the combination of high-expression (HYA, LYA) and low-expression (LXA, HYO, LYO) haplotypes. The variant alleles (O) refer to the low-expression haplotypes (LXA, HYO, LYO).

High Producer (Coded as 3):
Individuals carrying two high-expression haplotypes.
Examples: HYA/HYA, HYA/LYA, LYA/LYA.
→ Associated with high serum MBL levels.

Intermediate Producer (Coded as 2):
Individuals carrying one high-expression haplotype and one low-expression haplotype, or the LXA/LXA genotype.
Examples: HYA/LXA, LYA/LXA, HYA/HYO, HYA/LYO, LYA/LYO, LXA/LXA.
→ Associated with intermediate serum MBL levels.

Low/Deficient Producer (Coded as 1):
Individuals carrying two low-expression haplotypes, excluding LXA/LXA.
Examples: HYO/LXA, HYO/LYO, LYO/LYO, LXA/LYO.
→ Associated with low or deficient serum MBL levels.

Haplotype categorization generated according to the literature

• https://doi.org/10.1016/j.ijid.2011.04.008

Clinical Symptoms

• Urinary symptoms: 0=Absence, Polyuria=1, Dysuria=2, Incontinence=3, Nocturia=4.
• Pain: 0=Absence, Nonspecific=1, Joint=2, Lower back=3 and limbs=3.
• Neurological: 0=Absence, Paresthesia=1, Hyperreflexia=2, Spasticity/Neurogenic bladder=3.

🚀 Quick Start

1. Clone: git clone <URL>.
2. Install: pip install -r requirements.txt (create if needed).
3. Run notebooks sequentially per scenario.

Start with 1_Exploratory_analysis.ipynb in Jupyter.

🔬 Scientific Context

Evaluates MBL2 as biomarker for HAM/TSP progression in HTLV using ML with demographic, clinical, and interleukin data. Focuses on functional haplotypes and per-locus variants.