Package 'qtbi'

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

percentiles	Numeric vector of exposure percentiles in ⁠[0, 1]⁠.
synergy	Synergy strength in ⁠[0, 1]⁠.

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

n_exposures	Number of exposures (qubits).
n_metals	Deprecated alias for n_exposures.

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

data	A qtbi_data object from estimate_qtbi().
synergy_grid	Grid of synergy values for sensitivity curves.
synergy_ref	Reference synergy for summary statistics (defaults to the value used in estimate_qtbi()).
verbose	If TRUE, print a concise summary.

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

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

---

Convert exposures to within-cohort percentiles

Description

Convert exposures to within-cohort percentiles

Usage

exposure_percentile(x)

Arguments

x	Numeric exposure vector.

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

x	Object to test.

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

state

Complex statevector from build_statevector().

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

weights	Named numeric vector of raw potency ratios from potency_weights_from_reference_doses().
target_sum	Target sum for the rescaled weights. Defaults to the number of exposures (length(weights)).

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

data	Data frame containing exposure columns.
chemicals	Character vector of column names.

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

reference_doses	Named numeric vector of oral reference doses in mg/kg/day, with one value per exposure in chemicals.
chemicals	Character vector of exposure identifiers in panel order. Names must match names(reference_doses).
reference_index	Name of the index chemical. Defaults to the first entry in chemicals.

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

pct_mat	Numeric matrix of within-cohort percentiles (rows = subjects).
synergy	Synergy strength in ⁠[0, 1]⁠.
weights	Optional named numeric potency weights aligned with columns.

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

state	Complex statevector from build_statevector().
weights	Optional named numeric potency weights aligned with qubits. When NULL, marginals are summed with equal weight.

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

pct_vec	Numeric vector of within-cohort percentiles.
synergy	Synergy strength in ⁠[0, 1]⁠.
weights	Optional named numeric potency weights aligned with pct_vec.

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

topic

Optional character string naming a function or topic to open. If omitted, a summary index is printed.

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

data	A qtbi_data object from estimate_qtbi().

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

pct_mat	Numeric matrix of within-cohort percentiles (rows = subjects).
synergy_grid	Grid of synergy values in ⁠[0, 1]⁠.
synergy_ref	Reference synergy for summary statistics.
exposure_names	Labels for exposures (columns of pct_mat).
metal_names	Deprecated alias for exposure_names.
weights	Optional potency weights aligned with columns of pct_mat.

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

pct_mat	Numeric matrix of within-cohort percentiles.
synergy_grid	Grid of synergy values in ⁠[0, 1]⁠.
weights	Optional potency weights aligned with columns of pct_mat.

Value

Data frame with synergy, qtbi, and additive_baseline columns.

---