Package {qtbi}

Quantum Toxic Burden Index

Description

Compute the Quantum Toxic Burden Index (QTBI) from multi-exposure panels using a fixed quantum-inspired entanglement encoder.

Typical workflow

• estimate_qtbi() adds percentile and QTBI columns to your data frame.

• Optional reference_doses enable potency-weighted readout at the index step. Weights are rescaled automatically so weighted QTBI stays on the same ⁠[0, n]⁠ scale as the unweighted index.

• diagnose_qtbi() summarizes synergy sensitivity and monotonicity.

Author(s)

Maintainer: January G. Msemakweli jmsemak1@jh.edu

See Also

Useful links:

• https://github.com/january-msemakweli/qtbi

• doi:10.5281/zenodo.20476574

• Report bugs at https://github.com/january-msemakweli/qtbi/issues

Build the n-qubit entanglement statevector for one subject

Description

Build the n-qubit entanglement statevector for one subject

Usage

build_statevector(percentiles, synergy = 0.6)

Arguments

Value

Complex statevector of length 2^n.

Gate schedule for circuit diagrams

Description

Gate schedule for circuit diagrams

Usage

circuit_gate_schedule(n_exposures = 4L, n_metals = NULL)

Arguments

Value

List with gate schedule metadata.

Diagnose QTBI encoder behavior on processed data

Description

Diagnose QTBI encoder behavior on processed data

Usage

diagnose_qtbi(
  data,
  synergy_grid = seq(0, 1, by = 0.05),
  synergy_ref = NULL,
  verbose = TRUE
)

Arguments

Value

A qtbi_diagnosis object (also printed when verbose = TRUE).

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

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

Convert exposures to within-cohort percentiles

Description

Convert exposures to within-cohort percentiles

Usage

exposure_percentile(x)

Arguments

Value

Numeric percentiles in ⁠(0, 1]⁠.

Test for a qtbi_data object

Description

Test for a qtbi_data object

Usage

is_qtbi_data(x)

Arguments

Value

TRUE if x inherits from "qtbi_data".

Marginal toxic probabilities from a QTBI statevector

Description

Marginal toxic probabilities from a QTBI statevector

Usage

marginal_toxic_probs(state)

Arguments

Value

Numeric vector of marginal toxic probabilities.

Rescale potency weights to match the unweighted QTBI scale

Description

When potency weights are applied at readout, rescale them so their sum equals the number of exposures in the panel. This keeps weighted QTBI on the same [0, n] scale as the unweighted sum of marginals, which aids comparison between weighted and unweighted analyses.

Usage

normalize_potency_weights(weights, target_sum = NULL)

Arguments

Value

Named numeric vector of rescaled weights aligned with weights.

Build percentile matrix from a data frame

Description

Build percentile matrix from a data frame

Usage

percentile_matrix(data, chemicals)

Arguments

Value

Numeric matrix with one percentile column per chemical.

Derive relative potency weights from reference doses

Description

Computes outcome-independent weights as the ratio of the index chemical reference dose to each component reference dose:

w_i = \mathrm{RfD}_{\mathrm{index}} / \mathrm{RfD}_i

Usage

potency_weights_from_reference_doses(
  reference_doses,
  chemicals,
  reference_index = NULL
)

Arguments

Details

Lower reference doses (more potent toxicants) receive larger weights.

Value

Named numeric vector of potency weights aligned with chemicals.

Compute QTBI from percentile matrix

Description

Compute QTBI from percentile matrix

Usage

qtbi_from_pcts(pct_mat, synergy = 0.6, weights = NULL)

Arguments

Value

Numeric vector of QTBI scores.

Compute QTBI from a statevector

Description

Compute QTBI from a statevector

Usage

qtbi_from_state(state, weights = NULL)

Arguments

Value

Scalar QTBI score (sum of marginal toxic probabilities).

Compute QTBI from one percentile vector

Description

Compute QTBI from one percentile vector

Usage

qtbi_from_vector(pct_vec, synergy = 0.6, weights = NULL)

Arguments

Value

Scalar QTBI score.

Package help index for qtbi

Description

Prints a topic index for the main qtbi functions and optionally opens documentation for a specific topic. Use this when you want a guided entry point to the package; standard R help remains available via ?function_name and help(package = "qtbi").

Usage

qtbi_help(topic = NULL)

Arguments

Value

Invisibly returns NULL. When topic is supplied, the corresponding help page is opened as a side effect.

Examples

qtbi_help()
qtbi_help("estimate_qtbi")

Retrieve QTBI metadata stored on a processed data frame

Description

Retrieve QTBI metadata stored on a processed data frame

Usage

qtbi_meta(data)

Arguments

Value

List with chemicals, synergy strength, and percentile column names.

Full circuit diagnostics for a cohort percentile matrix

Description

Full circuit diagnostics for a cohort percentile matrix

Usage

synergy_diagnostics(
  pct_mat,
  synergy_grid = seq(0, 1, by = 0.05),
  synergy_ref = 0.6,
  exposure_names = NULL,
  metal_names = NULL,
  weights = NULL
)

Arguments

Value

List with cohort_band, marginals, monotonicity, synergy_ref, sens_ref.

Synergy sensitivity on cohort median percentiles

Description

Synergy sensitivity on cohort median percentiles

Usage

synergy_sensitivity(
  pct_mat,
  synergy_grid = seq(0, 1, by = 0.05),
  weights = NULL
)

Arguments

Value

Data frame with synergy, qtbi, and additive_baseline columns.