estimate_qtbi: Estimate QTBI and append scores to a data frame

In qtbi: Quantum Toxic Burden Index

Estimate QTBI and append scores to a data frame

Description

Computes within-cohort exposure percentiles, runs the fixed entanglement encoder, and returns the input data with percentile and QTBI columns added.

Usage

estimate_qtbi(
  data,
  chemicals,
  synergy_strength = 0.6,
  qtbi_col = "qtbi",
  percentile_prefix = "pct_",
  exposure_names = NULL,
  pct_cols = NULL,
  reference_doses = NULL,
  reference_index = NULL
)

Arguments

data	A data frame containing exposure columns.
chemicals	Character vector of exposure column names.
synergy_strength	Synergy strength in ⁠[0, 1]⁠.
qtbi_col	Name for the QTBI score column (default "qtbi").
percentile_prefix	Prefix for percentile columns (default "pct_").
exposure_names	Optional display names for plots (defaults to chemicals).
pct_cols	Optional percentile column names (same length as chemicals).
reference_doses	Optional named numeric vector of oral reference doses in mg/kg/day, with names matching exposure_names (or chemicals if exposure_names is omitted). The package derives potency weights as reference_index dose divided by each component dose, rescales them so their sum equals the number of exposures (keeping QTBI on the same [0, n] scale as the unweighted index), and applies them at readout only.
reference_index	Name of the index chemical for potency ratios. Defaults to the first exposure_names entry (or first chemicals entry).

Value

A qtbi_data object (data frame) with QTBI and percentile columns.

Examples

df <- data.frame(
  Pb = c(1, 2, 3, 4),
  As = c(4, 3, 2, 1),
  Cd = c(2, 2, 3, 3),
  Hg = c(1, 3, 2, 4)
)
out <- estimate_qtbi(
  df,
  chemicals = c("Pb", "As", "Cd", "Hg"),
  synergy_strength = 0.6,
  reference_doses = c(Pb = 6.3e-4, As = 6.0e-5, Cd = 5.0e-4, Hg = 1.0e-4),
  reference_index = "Pb"
)
out$qtbi

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