Package {uroscores}

uroscores: scoring tools for urology and pelvic health research

Description

Instruments are declarative definitions (see uro_instrument()) consumed by one generic engine, score_instrument(). Design principles:

Details

1. An instrument is data, not code.

2. Every scoring rule is documented to its primary source and unit-tested against published worked examples before validated = TRUE.

3. Missing-item handling is explicit. Where no published rule exists, the package scores strictly and refuses to prorate.

4. Vectorized, data.frame in / data.frame out.

Author(s)

Maintainer: Muhammad Faiz Amirullah Nurhadi faizamirullah@gmail.com

See Also

Useful links:

• https://github.com/faizamirullah/uroscores

• Report bugs at https://github.com/faizamirullah/uroscores/issues

Achievable total scores of an instrument

Description

Computes every total the instrument can produce from valid item responses under its registered missing-item rule. For sum and mean-scaled instruments with a published prorating rule, the prorated totals are included (UDI-6/IIQ-7 totals are fractions when items are missing). For product instruments the set is the products of the item values.

Usage

achievable_totals(instrument)

Arguments

Details

classify_severity() and responder() check scores against this set, which catches hand-entered typos and totals computed elsewhere under a different convention.

Value

A sorted numeric vector of achievable totals.

Examples

achievable_totals("isi")

Classify total scores into severity bands

Description

Converts numeric total scores into an ordered factor using the severity bands declared in the instrument's registry definition. Classification is by explicit band membership, not by cut points: published bands are not always contiguous (e.g. the Sandvik severity index bands 3-6 and 8-9), and a value falling between bands gets NA with a warning rather than an invented label.

Usage

classify_severity(x, instrument)

Arguments

Value

An ordered factor with the instrument's severity labels. Scores outside the instrument's score range, not achievable from the instrument's items (see achievable_totals()), or falling between published bands become NA with a warning.

Examples

classify_severity(c(5, 12, 24), "ipss")

Retrieve an instrument definition by id

Description

Retrieve an instrument definition by id

Usage

get_instrument(id)

Arguments

Value

A uro_instrument object.

List registered instruments

Description

List registered instruments

Usage

list_instruments()

Value

A data.frame with one row per registered instrument.

Examples

list_instruments()

Published anchor-based change statistics ("MID estimates")

Description

Returns published statistics that researchers commonly use to justify minimal-important-difference thresholds, one row per estimate, with the anchor, subgroup, and citation carried on every row. These are descriptive, published values, not canonical MIDs: the source itself (Barry 1995) emphasises that any threshold choice is arbitrary and that perceptible change depends strongly on the baseline score. Choosing among them, or against them, is the analyst's decision; responder() therefore requires an explicit threshold.

Usage

mid_estimates(instrument = NULL)

Arguments

Details

All Barry 1995 rows come from a trial that used the 1-week recall version of the AUA symptom index and BPH impact index in men with BPH; check transferability before applying them elsewhere.

value is a signed score change; negative means a score decrease, which is improvement on all built-in instruments.

Value

A data.frame with columns instrument, statistic, value, anchor, subgroup, note, reference.

Examples

mid_estimates("ipss")[, c("statistic", "value", "subgroup")]

Declare that no published missing-item rule exists for an instrument

Description

Instruments carrying this rule are scored strictly: any missing item makes the score NA. Requests to prorate such instruments are refused, because inventing an unpublished prorated-scoring rule would codify exactly the kind of ad hoc practice this package exists to prevent.

Usage

missing_rule_none()

Value

An object of class uro_missing_rule.

Declare a published prorated-scoring rule for missing items

Description

Declare a published prorated-scoring rule for missing items

Usage

missing_rule_prorate(max_missing = NA_integer_, reference = NA_character_)

Arguments

Value

An object of class uro_missing_rule.

Register an instrument definition

Description

Adds a user-supplied uro_instrument() definition to the session registry, making it available to score_instrument() by its id. Registering an existing id overwrites it with a message.

Usage

register_instrument(definition)

Arguments

Value

The definition, invisibly.

Classify responders by an explicitly chosen change threshold

Description

Computes followup - baseline and classifies each pair as responder or not against a threshold the analyst chooses. There is no default threshold on purpose: no canonical MID exists, and the published estimates depend on anchor, method, population, and baseline severity (see mid_estimates(), and consider baseline-stratified thresholds).

Usage

responder(
  baseline,
  followup,
  instrument,
  threshold,
  direction = c("decrease", "increase")
)

Arguments

Value

A logical vector: TRUE responder, FALSE not, NA when either score is missing, out of range, or not an achievable total (see achievable_totals()).

Examples

responder(baseline = c(20, 12), followup = c(14, 11),
          "ipss", threshold = 3)

Score an instrument from a data frame of item responses

Description

Score an instrument from a data frame of item responses

Usage

score_instrument(
  data,
  instrument,
  items = NULL,
  missing = c("registry", "strict", "prorate"),
  keep_items = FALSE
)

Arguments

Value

A data.frame with one row per row of data, containing ⁠<id>_total⁠, one ⁠<id>_<subscale>⁠ column per subscale, and ⁠<id>_n_missing⁠. Subscale scores are always computed strictly in this version (any missing subscale item gives NA for that subscale).

Examples

d <- data.frame(oabss_q1 = c(1, 2), oabss_q2 = c(2, 3),
                oabss_q3 = c(3, 5), oabss_q4 = c(2, 5))
score_instrument(d, "oabss")

Score the International Prostate Symptom Score (IPSS)

Description

Convenience wrapper around score_instrument() for the IPSS. Returns the 7-item symptom total, the voiding and storage subscores, and optionally the separate quality-of-life item and a severity classification.

Usage

score_ipss(
  data,
  items = paste0("ipss_q", 1:7),
  qol = NULL,
  classify = FALSE,
  missing = c("registry", "strict", "prorate"),
  keep_items = FALSE
)

Arguments

Details

The QoL item is not part of the symptom total; it is validated (0-6) and passed through as ipss_qol.

Value

A data.frame of scores; see score_instrument().

Examples

d <- data.frame(
  ipss_q1 = c(1, 3), ipss_q2 = c(2, 4), ipss_q3 = c(3, 5),
  ipss_q4 = c(0, 2), ipss_q5 = c(4, 5), ipss_q6 = c(5, 3),
  ipss_q7 = c(2, 4), qol = c(3, 5)
)
score_ipss(d, qol = "qol", classify = TRUE)

Define a scoring instrument

Description

Constructs the declarative definition of a clinical instrument. All clinical content (item ranges, scoring rule, severity cutoffs, missing-item policy) lives here, as data; score_instrument() is a generic engine that consumes it.

Usage

uro_instrument(
  id,
  full_name,
  items,
  item_min = NULL,
  item_max = NULL,
  item_values = NULL,
  scoring = c("sum", "mean_scaled", "product"),
  scale_max = NULL,
  subscales = NULL,
  severity = NULL,
  missing_rule = missing_rule_none(),
  references = character(),
  validated = FALSE
)

Arguments

Value

An object of class uro_instrument.

Examples

vas <- uro_instrument(
  id = "vas10", full_name = "Single-item 0-10 rating",
  items = "vas10", item_min = 0L, item_max = 10L,
  references = "add the primary source before use"
)
vas
suppressWarnings(score_instrument(data.frame(vas10 = 7), vas))