Usage Guide

This page walks through common package workflows.

Quick Start

from opendose_poppk import PKModel, PDModel, PopulationSimulator

pk = PKModel(F=0.80, ka=1.80, ke=0.28, Vd=65.0)
pd = PDModel(EC50=10.0, Emax=100.0, n=1.5)

sim = PopulationSimulator(pk=pk, pd=pd, dose=1000.0)
result = sim.run(n_subjects=1000, t_max=12.0, n_points=200, seed=42)
print(result["percentiles_pk"][50].max())

Single-Subject PK

import numpy as np
from opendose_poppk import PKModel

pk = PKModel(F=0.80, ka=1.80, ke=0.28, Vd=65.0)
times = np.linspace(0, 24, 200)
conc = pk.concentration(times, D=1000.0)

Multiple-Dose Regimen

import numpy as np
from opendose_poppk import PKModel

pk = PKModel(F=0.80, ka=1.80, ke=0.28, Vd=65.0)
times = np.linspace(0, 48, 400)
conc = pk.concentration_multiple_dose(times, D=1000.0, interval_h=12.0, n_doses=4)

CLI Regimen Simulation

opendose simulate-regimen \
  --drug Paracetamol \
  --interval-h 12 \
  --n-doses 4 \
  --output-csv output/tables/paracetamol_regimen.csv \
  --plot-png output/figures/paracetamol_regimen.png

CLI IV Simulation

opendose simulate-iv \
  --drug Paracetamol \
  --mode bolus \
  --dose 1000 \
  --output-csv output/tables/paracetamol_iv_bolus.csv

opendose simulate-iv \
  --drug Paracetamol \
  --mode infusion \
  --infusion-rate 200 \
  --infusion-duration-h 2 \
  --infusion-start-h 0 \
  --output-csv output/tables/paracetamol_iv_infusion.csv

CLI Steady-State Metrics

opendose steady-state \
  --drug Paracetamol \
  --interval-h 12 \
  --n-doses 20 \
  --output-csv output/tables/paracetamol_steady_state.csv

CLI Nonlinear PK Simulation

opendose simulate-nonlinear \
  --drug Paracetamol \
  --dose 1000 \
  --vmax 200 \
  --km 15 \
  --output-csv output/tables/paracetamol_nonlinear.csv

CLI Cohort Simulation

opendose simulate-cohort \
  --drug Paracetamol \
  --input data/cohort.csv \
  --output-csv output/tables/cohort_simulation.csv

CLI Cohort Template

opendose init-cohort-template \
  --output data/cohort_template.csv

CLI Sensitivity Analysis

opendose sensitivity \
  --drug Paracetamol \
  --dose 1000 \
  --rel-step 0.1 \
  --output-csv output/tables/sensitivity_paracetamol.csv

CLI Dose Sweep

opendose dose-sweep \
  --drug Paracetamol \
  --doses 250,500,750,1000 \
  --output-csv output/tables/dose_sweep_paracetamol.csv

CLI Multi-Drug Regimen Benchmark

opendose benchmark-regimen \
  --drugs Paracetamol,Ibuprofen,Diazepam \
  --interval-h 12 \
  --n-doses 4 \
  --output-csv output/tables/regimen_benchmark.csv

CLI Environment Check

Note

If cloud CI/CD billing/credits are unavailable, local checks/tests are the primary validation path.

opendose doctor --strict

CLI Project Report

opendose project-report \
  --drug Paracetamol \
  --output-md output/reports/project_report.md

CLI Drug Dataset Validation

opendose validate-dataset \
  --dataset datasets/drugs_parameters.csv \
  --output-clean output/tables/drugs_parameters_clean.csv

CLI TDM Validation

opendose validate-tdm \
  --input data/tdm.csv \
  --output-clean output/tables/tdm_clean.csv

opendose validate-tdm \
  --input data/tdm_raw.csv \
  --time-unit min \
  --conc-unit ng/mL \
  --dose-unit g \
  --output-clean output/tables/tdm_clean.csv

CLI TDM Templates

opendose init-tdm-template --output data/tdm_template.csv
opendose init-tdm-template --format clinical --output data/tdm_template_clinical.csv

CLI Population Mixed-Effects Fit

opendose fit-population-mixed \
  --drug Paracetamol \
  --input data/tdm.csv \
  --maxiter 1200 \
  --eta-csv output/tables/pop_mixed_eta.csv \
  --output-json output/reports/pop_mixed_fit.json

CLI External Validation

Note

Direct one-to-one benchmarking against licensed software (NONMEM/Monolix/Pumas) requires paid licenses. Without licenses, external validation is limited to public datasets and/or precomputed ref_conc.

opendose init-external-template --output data/external_validation_template.csv

opendose validate-external \
  --drug Paracetamol \
  --input data/external_validation.csv \
  --predictions-csv output/tables/external_predictions.csv \
  --output-json output/reports/external_validation.json

CLI Web App Baseline

# Dry-run mode (testable): generates HTML and exits.
opendose web-app \
  --drug Paracetamol \
  --dose 750 \
  --t-end 12 \
  --output-html output/web/web_app.html \
  --dry-run

# Local server mode:
opendose web-app --drug Paracetamol --host 127.0.0.1 --port 8000

CLI Validation Report

opendose validation-report \
  --drug Paracetamol \
  --output-md output/reports/validation_report.md \
  --output-json output/reports/validation_report.json

CLI Release Readiness

opendose release-readiness \
  --repo-root . \
  --output-md output/reports/release_readiness.md \
  --strict

CLI Dose Recommendation

opendose recommend-dose \
  --drug Paracetamol \
  --target-cmax 10 \
  --weight 80 \
  --crcl 70 \
  --age 55 \
  --output-json output/reports/dose_recommendation.json

CLI Regimen Dose Recommendation

opendose recommend-regimen-dose \
  --drug Paracetamol \
  --target-trough 1.0 \
  --interval-h 12 \
  --n-doses 4 \
  --output-json output/reports/regimen_dose_recommendation.json

CLI Regimen Window Recommendation

opendose recommend-regimen-window \
  --drug Paracetamol \
  --target-trough-min 0.05 \
  --target-cmax-max 12.0 \
  --interval-h 12 \
  --n-doses 4 \
  --strategy midpoint \
  --output-json output/reports/regimen_window_recommendation.json

Covariate Modelling

from opendose_poppk import PKModel, CovariateModel

pk = PKModel(F=0.80, ka=1.80, ke=0.28, Vd=65.0)
cov = CovariateModel(pk)
individual_params = cov.individualize({"weight": 90.0, "crcl": 40.0, "age": 65.0}, sex="M")
print(individual_params)

MAP (Bayesian) Individual Estimation

import numpy as np
from opendose_poppk import PKModel, CovariateModel, MAPEstimator

pk = PKModel()
cov = CovariateModel(pk)
est = MAPEstimator(pk, covariate_model=cov, sigma_obs=0.8)

times_obs = np.array([1.0, 2.0, 4.0, 8.0])
conc_obs = np.array([6.8, 7.5, 5.9, 4.1])

result = est.fit(
    times=times_obs,
    obs=conc_obs,
    patient_covariates={"weight": 90.0, "crcl": 50.0, "age": 60.0},
    dose=1000.0,
)
print(result["params_map"])

Drug Database

from opendose_poppk import DrugDatabase, PKModel

db = DrugDatabase("datasets/drugs_parameters.csv")
drug = db.get_drug("Paracetamol")
pk = PKModel(**drug.pk_kwargs)
print(drug.dose)