Weibull Extrapolator

A reproducible pipeline for translating mouse wound-healing data into human-scaled probabilistic transition estimates for health-economic modeling of bacteriophage interventions in diabetic foot ulcers.

Overview

The Weibull Extrapolator is a six-stage, end-to-end modeling framework that integrates:

• Data validation and quality checks
• Weibull survival analysis and parameter fitting
• Transition probability derivation
• Allometric scaling from mouse to human timeframes
• Kaplan-Meier visualization and hazard analysis

This pipeline produces intermediate CSVs and visual outputs suitable for integration into Markov cost-effectiveness analysis models.

Pipeline Architecture

┌─────────────────────────────────────────────────────────────┐
│  Step 01: Load & Inspect Mouse Data                        │
│  • Import wound closure and bacterial CFU datasets          │
│  • Structural validation and completeness checks            │
│  • Exports: closure_data.csv, clearance_data.csv           │
└──────────────────┬──────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────────┐
│  Step 02: Verify & Prepare Closure/Clearance Datasets      │
│  • Normalize to survival function S(t)                      │
│  • Generate summary statistics by cohort/treatment          │
│  • Exports: closure_summary.csv, clearance_summary.csv     │
└──────────────────┬──────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────────┐
│  Step 03: Weibull Fitting & Parameter Extraction           │
│  • Fit Weibull models (scale λ, shape k parameters)        │
│  • Extract characteristic healing/clearance times           │
│  • Exports: weibull_fits.csv, diagnostic plots             │
└──────────────────┬──────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────────┐
│  Step 04: Weekly Transition Probabilities                  │
│  • Derive discrete-time transition matrices                 │
│  • Exports: weekly_transitions_closure.csv                  │
└──────────────────┬──────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────────┐
│  Step 05: Mouse-to-Human Allometric Scaling                │
│  • Apply Wei et al. (2017) scaling factors                  │
│  • Adjust parameters for human physiology                   │
│  • Exports: allometry_summary.csv, scaled parameters       │
└──────────────────┬──────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────────┐
│  Step 06: Kaplan-Meier Curves & Hazard Visualization       │
│  • Generate KM survival curves                              │
│  • Plot hazard functions and confidence intervals           │
│  • Exports: KM_*.png, hazard visualizations                 │
└─────────────────────────────────────────────────────────────┘

Quick Start

Prerequisites

• R >= 4.0.0
• Python >= 3.8
• Quarto >= 1.3

Installation

1. Clone the repository:

git clone git@github.com:jvanleuven-5271/weibull-extrapolator.git
cd weibull-extrapolator

2. Install R dependencies:

# In R console
install.packages("renv")
renv::restore()

3. Install Python dependencies:

pip install -r requirements.txt
# or
pip install sentence-transformers pandas numpy pdfplumber tqdm

Running the Pipeline

Run all steps:

bash run_all_steps.sh

Run individual steps:

quarto render Step_01_Load_and_Inspect_Mouse_Data.qmd
quarto render Step_02_Verify_and_Prepare_Closure_Clearance_Datasets.qmd
# ... etc

Generate website:

quarto render
# Open _site/index.html in browser

Directory Structure

weibull_pipeline_v1_annotated/
├── README.md                    # This file
├── _quarto.yml                  # Quarto configuration
├── index.qmd                    # Pipeline overview document
├── run_all_steps.sh             # Master execution script
├── functions.R                  # Shared R utility functions
├── data/                        # Input datasets
│   ├── mouse_closure_filled.csv
│   ├── mouse_cfu_filled.csv
│   └── human_*.csv
├── outputs/                     # Generated results
│   ├── figures/
│   ├── *.csv                    # Intermediate datasets
│   └── *.png                    # Visualizations
├── scripts/                     # Auxiliary scripts
│   ├── extract_ml_v8p1_resume.py
│   └── various R/Python utilities
├── Step_*.qmd                   # Main pipeline notebooks
└── assets/                      # Static resources

Key Outputs

After running the pipeline, you'll find:

• outputs/weibull_fits.csv - Fitted Weibull parameters (λ, k) by treatment group
• outputs/weekly_transitions_*.csv - Discrete-time transition probabilities
• outputs/allometry_summary.csv - Scaled human-equivalent parameters
• outputs/KM_*.png - Kaplan-Meier survival curves
• outputs/figures/ - Diagnostic plots and visualizations

Mathematical Foundation

Weibull Survival Function

The core model uses the two-parameter Weibull survival function:

$$S(t) = \exp\left[-\left(\frac{t}{\lambda}\right)^k\right]$$

Where:

• λ (lambda) = scale parameter (characteristic time)
• k = shape parameter (determines hazard behavior)
  • k > 1: increasing hazard (accelerating healing)
  • k = 1: constant hazard (exponential decay)
  • k < 1: decreasing hazard (decelerating process)

Hazard Function

$$h(t) = \frac{k}{\lambda}\left(\frac{t}{\lambda}\right)^{k-1}$$

Quantile Function

$$t_p = \lambda \cdot [-\ln(1-p)]^{1/k}$$

Used to extract median (p=0.5) and 90th percentile (p=0.9) healing times.

Methodology References

• Wickham H et al. (2019). Welcome to the Tidyverse. J Open Source Softw 4(43):1686.
• Wei X et al. (2017). Allometric scaling of skin thickness, elasticity, viscoelasticity to mass for micro-medical device translation. Sci Rep 7, 11885.
• Cukjati D et al. (2001). A reliable method of determining wound healing rate. Med Biol Eng Comput 39(2), 263-271.

Project Context

This pipeline supports the pre-clinical modeling component of a health-economic analysis for bacteriophage-based interventions in diabetic foot ulcers (DFUs). The outputs are designed for integration into:

• Markov cohort models
• Discrete event simulations
• Cost-effectiveness analyses (CEA)
• Budget impact models

Usage Examples

Example 1: Extract Parameters for Single Treatment

library(tidyverse)

# Load fitted parameters
fits <- read_csv("outputs/weibull_fits_closure.csv")

# Get phage treatment parameters
pha_params <- fits %>% 
  filter(treatment_group == "PHA") %>%
  select(scale, shape, cohort)

print(pha_params)

Example 2: Generate Custom KM Plot

source("functions.R")
library(ggplot2)

# Create survival curve
times <- seq(0, 28, by = 1)
surv <- S_weibull(times, scale = 14.5, shape = 2.1)

ggplot(data.frame(t = times, S = surv), aes(t, S)) +
  geom_line() +
  labs(title = "Custom Survival Curve",
       x = "Time (days)", y = "S(t)")

Contributing

This is a research pipeline under active development. For questions or suggestions:

• Author: Jason van Leuven
• Contact: vanl0030@flinders.edu.au
• Institution: Flinders University

Known Issues & Limitations

• Steps 07 and 08 are referenced in documentation but not yet implemented
• Large PDF extraction processes may require significant memory
• Some file paths are currently hardcoded and may need adjustment
• Pipeline assumes mouse wound data structure as defined in Step 01

Troubleshooting

Issue: "Cannot find file" errors

Solution: Ensure you're running scripts from the project root directory

Issue: Quarto rendering fails

Solution: Check that all required R packages are installed via renv::restore()

Issue: Python extraction script fails

Solution: Verify HuggingFace cache directory permissions and available disk space

License

[Specify your license here - e.g., MIT, GPL-3, etc.]

Citation

If you use this pipeline in your research, please cite:

@software{weibull_extrapolator,
  author = {van Leuven, Jason},
  title = {Weibull Extrapolator: Mouse-to-Human Wound Healing Translation Pipeline},
  year = {2025},
  url = {https://github.com/jvanleuven-5271/weibull-extrapolator}
}

Acknowledgments

This work is part of a larger health-economic analysis of bacteriophage interventions for diabetic foot infections, conducted at Flinders University.

---

Version: 1.0 (Annotated)
Last Updated: October 2025