README.md

In qtbi: Quantum Toxic Burden Index

qtbi

Quantum Toxic Burden Index (QTBI) — encode correlated environmental exposures into a single, reproducible mixture burden score using a fixed quantum-inspired circuit.

QTBI is designed for environmental mixture epidemiology: you specify the exposure panel and (optionally) external potency benchmarks before outcome modeling. The encoder does not reweight components from the disease outcome.

Why use QTBI?

| Step | What QTBI does | |------|----------------| | 1. Normalize | Each exposure becomes a within-cohort percentile on [0, 1] | | 2. Encode | Percentiles pass through a fixed entanglement circuit controlled by synergy s | | 3. Read out | Marginal toxic probabilities sum to one scalar QTBI on [0, n] | | 4. Analyze | Use the scalar in standard regression (logistic, linear, etc.) |

Optional potency-weighted readout applies external oral reference doses at the final step only, with automatic rescaling so weighted QTBI stays on the same [0, n] scale as the unweighted index.

Installation

install.packages("qtbi")  # after CRAN acceptance
# or:
# install.packages("remotes")
remotes::install_github("january-msemakweli/qtbi")

From a local clone of this repository:

install.packages(".", repos = NULL, type = "source")

Requirements: R (>= 4.1.0). No compiled code. No non-base runtime dependencies.

Quick start: four-metal mixture

library(qtbi)

# Example exposure data (complete cases only)
df <- data.frame(
  LBXBPB = c(0.8, 1.2, 2.1, 0.9),   # blood lead
  URXIAS = c(3.5, 8.2, 4.1, 12.0),  # urinary inorganic As + metabolites
  LBXBCD = c(0.2, 0.4, 0.3, 0.6),   # blood cadmium
  LBXTHG = c(0.5, 1.1, 2.0, 0.7)    # blood mercury
)

# Unweighted QTBI (equal readout weights)
processed <- estimate_qtbi(
  df,
  chemicals = c("LBXBPB", "URXIAS", "LBXBCD", "LBXTHG"),
  exposure_names = c("Pb", "As", "Cd", "Hg"),
  synergy_strength = 0.6
)

processed$qtbi
diagnose_qtbi(processed)

Potency-weighted QTBI

Supply oral reference doses in mg/kg/day (one per exposure). The package derives potency ratios, rescales weights to sum to n, and applies them at readout only.

ref <- c(
  Pb = 6.3e-4,   # external benchmark (mg/kg/day)
  As = 6.0e-5,
  Cd = 5.0e-4,
  Hg = 1.0e-4
)

weighted <- estimate_qtbi(
  df,
  chemicals = c("LBXBPB", "URXIAS", "LBXBCD", "LBXTHG"),
  exposure_names = c("Pb", "As", "Cd", "Hg"),
  synergy_strength = 0.6,
  reference_doses = ref,
  reference_index = "Pb"
)

qtbi_meta(weighted)$potency_weights

Inspect weights explicitly:

raw <- potency_weights_from_reference_doses(ref, c("Pb", "As", "Cd", "Hg"), "Pb")
normalize_potency_weights(raw)

Important: align each biomarker with the chemical form used in its benchmark, and review absolute cohort distributions before applying potency weights. A high regulatory weight on a background-level exposure can dominate the index.

Recommended workflow for mixture modeling

library(qtbi)

# 1. Prepare a complete-case analytic frame (no missing exposures)
# 2. Choose panel members (known/suspected toxicants, same direction)
# 3. Encode unweighted and (optionally) potency-weighted QTBI
processed_unw <- estimate_qtbi(
  df,
  chemicals = exposure_cols,
  exposure_names = metal_names,
  synergy_strength = 0.6
)

processed_wgt <- estimate_qtbi(
  df,
  chemicals = exposure_cols,
  exposure_names = metal_names,
  synergy_strength = 0.6,
  reference_doses = reference_doses,
  reference_index = "Pb"
)

# 4. Encoder diagnostics (exposure-only; no outcome)
diagnose_qtbi(processed_unw)
synergy_sensitivity(processed_unw, synergy_grid = seq(0, 1, by = 0.1))

# 5. Outcome modeling with standard tools
# glm(ckd ~ qtbi + covariates, data = processed_unw, family = binomial())

Design checklist

1. Panel selection — include only exposures assumed to increase burden in the same direction.
2. Biomarker–benchmark alignment — e.g. speciated inorganic arsenic for an inorganic arsenic RfD, not urinary total arsenic.
3. Distribution review — inspect medians/IQRs; percentiles alone can rank low absolute levels highly.
4. Synergy setting — use diagnose_qtbi() / synergy_sensitivity() over s ∈ [0, 1] without the outcome.
5. Compare readouts — report unweighted and potency-weighted QTBI side by side when weights are used.

Main functions

| Function | Purpose | |----------|---------| | estimate_qtbi() | Percentile encoding + index computation | | diagnose_qtbi() | Synergy sensitivity and monotonicity checks | | potency_weights_from_reference_doses() | Raw potency ratios from oral benchmarks | | normalize_potency_weights() | Rescale weights to the unweighted [0, n] scale | | qtbi_meta() | Chemicals, synergy, weights, column names | | qtbi_help() | Interactive help index |

Advanced exports include build_statevector(), qtbi_from_pcts(), and synergy_diagnostics().

Repository layout

qtbi/
├── R/              # Package source
├── man/            # Documentation
├── tests/          # testthat suite
├── DESCRIPTION
├── NAMESPACE
├── NEWS.md
├── LICENSE
└── README.md

See the illustration/ folder in the GitHub repository for a minimal NHANES metal mixture example.

Development

R CMD build .
R CMD check qtbi_0.1.2.tar.gz --as-cran --no-manual

Run tests in R:

testthat::test_local()

Citation

If you use this package, please cite the methods specification and this software:

Msemakweli JG (2026). The Quantum Toxic Burden Index: Mathematical Specification.
Zenodo. https://doi.org/10.5281/zenodo.20476574

Msemakweli JG (2026). qtbi: Quantum Toxic Burden Index. R package version 0.1.2.
https://github.com/january-msemakweli/qtbi

License

MIT © January G. Msemakweli

qtbi documentation built on June 9, 2026, 5:09 p.m.