Package 'respondeR'

Format responder-analysis results for display

Description

Turns the numeric output of responder_analysis() into a compact, display-ready data frame: proportions and risk differences as percentages, the risk ratio and odds ratio with intervals, and a combined "RD (CI)" string. Used by the bundled Shiny app and handy for reports.

Usage

format_responder_results(results, digits = 1)

Arguments

results	A data frame returned by responder_analysis().
digits	Number of decimal places (default 1).

Value

A data frame with character columns Method, PE, PC, RD, RR and OR (percentages for proportions/RD; ratios for RR/OR). Methods without a variance model show point estimates only.

Examples

format_responder_results(responder_analysis(sample_responder_data, mid = 1))

---

Launch the Responder Analysis Shiny application

Description

Starts the bundled Shiny application, a point-and-click front end to responder_analysis(): upload data (or load the example), set the MID and direction of benefit, and view, plot and download the results.

Usage

launch_responder_analysis(...)

Arguments

...	Additional arguments passed to shiny::runApp().

Value

Called for its side effect of launching the app; invisibly returns the value of shiny::runApp().

Examples

launch_responder_analysis()

---

Responder analysis of continuous trial outcomes

Description

Converts continuous outcomes (mean change, SD and sample size per arm, across studies) into responder proportions and a range of between-arm effect measures: the risk difference (RD), risk ratio (RR), odds ratio (OR) and number needed to treat (NNT), under a parametric model for the change scores. Responders are defined by a minimal important difference (MID) threshold (the cut-point / "dichotomization" approach of Anzures-Cabrera, Sarpatwari and Higgins, 2011). For a threshold-free alternative see responder_cles().

Usage

responder_analysis(
  data,
  mid,
  direction = c("higher", "lower"),
  method = c("individual", "weighted", "unweighted", "median", "smd"),
  se_method = c("binomial", "delta"),
  pooling = c("fixed", "random"),
  control = c("matched", "median"),
  tau_method = c("DL", "REML"),
  dist = c("normal", "lognormal", "t"),
  df = NULL,
  mid_sd = 0,
  ci_type = c("wald", "logit"),
  ci_method = c("wald", "hksj"),
  conf_level = 0.95
)

Arguments

data	A data frame with one row per study and columns study, change_e, sd_e, n_e, change_c, sd_c, n_c. See sample_responder_data.
mid	Single finite number: the minimal important difference threshold.
direction	"higher" (a larger change indicates response) or "lower".
method	Methods to compute: any of "individual", "weighted", "unweighted", "median", "smd". Defaults to the first four.
se_method	Per-study SE model for "individual": "binomial" (default) or "delta". The "binomial" variance p(1 - p) / n is a pseudo-binomial approximation: p is a probability implied by the estimated mean and SD, not a proportion of observed dichotomized patients, so it does not include the uncertainty in the reported mean and SD. "delta" propagates that uncertainty and is generally preferable for summary-statistic inputs; "binomial" is the default only for continuity with earlier results.
pooling	"fixed" (default) or "random" effects, for the "individual" and "smd" methods.
control	Baseline-risk rule for the summary methods (median, unweighted, weighted): "matched" (default) pools the control arm the same way as the experimental arm; "median" always takes the control responder proportion from the median control arm (the Sofi-Mahmudi 2024 baseline), which yields point estimates only. Ignored by "individual" and "smd".
tau_method	Between-study variance estimator when pooling = "random": "DL" (DerSimonian-Laird, default) or "REML" (needs the metafor package; falls back to DL with a warning if unavailable).
dist	Change-score distribution: "normal" (default), "lognormal" or "t".
df	Degrees of freedom when dist = "t".
mid_sd	Optional standard deviation of the MID threshold; when ⁠> 0⁠ its uncertainty is propagated into the effect-measure variances.
ci_type	"wald" (default) or "logit" (keeps proportion and risk-difference intervals within valid bounds via the logit transform and Newcombe's MOVER method).
ci_method	Random-effects interval method: "wald" (Normal, default) or "hksj" (Hartung-Knapp-Sidik-Jonkman, a t-based interval that is better calibrated when the number of studies is small).
conf_level	Confidence level (default 0.95).

Value

A data frame with one row per requested method and columns: method, pooling, k, p_e, p_c, rd/rd_lb/rd_ub, rr/rr_lb/rr_ub, or/or_lb/or_ub, nnt/nnt_lb/nnt_ub, var_rd, and the heterogeneity statistics tau2, i2, q, q_p, pi_lb, pi_ub (for the pooled methods). Proportions, risk differences and CLES are on the proportion scale; multiply by 100 for percentages.

Methods

individual

Dichotomize each study, then pool the per-study effect measures (fixed or random effects). The most defensible option; the per-study SE follows se_method.

weighted

Pool the mean change by inverse variance and the SD by the within-study pooled SD, dichotomize the pooled summaries, and obtain variances by the delta method.

unweighted, median

Dichotomize the arithmetic mean / median of the study means and SDs. Summaries with no variance model: intervals are NA.

smd

Pool the standardized mean difference (Hedges' g), bridge to an odds ratio via the logistic link (⁠lnOR = (pi / sqrt(3)) g⁠), and combine with the weighted-pooled control responder rate to recover risks. The second approach of the reference; not included by default.

For the summary methods (median, unweighted, weighted) the control proportion is, by default, pooled the same way as the experimental arm (control = "matched"). Set control = "median" to instead take the baseline risk from the median control arm for every summary method, as in the Sofi-Mahmudi (2024) simulation study; the experimental arm is still pooled by the chosen method. Because the median control arm carries no sampling-variance model, control = "median" reports point estimates only (no intervals) for the summary methods. The individual and smd methods pool per-study contrasts and ignore control.

References

Sofi-Mahmudi A (2024). Identifying an optimal strategy for converting pain as a continuous outcome to a responder analysis. Master's thesis, McMaster University. https://hdl.handle.net/11375/30210

Thorlund K, Walter SD, Johnston BC, Furukawa TA, Guyatt GH (2011). Pooling health-related quality of life outcomes in meta-analysis: a tutorial and review of methods for enhancing interpretability. Research Synthesis Methods, 2(3), 188 to 203. doi:10.1002/jrsm.46

Anzures-Cabrera J, Sarpatwari A, Higgins JPT (2011). Expressing findings from meta-analyses of continuous outcomes in terms of risks. Statistics in Medicine, 30(25), 2867 to 2880. doi:10.1002/sim.4298

See Also

responder_rd_individual(), responder_cles(), responder_proportions()

Examples

responder_analysis(sample_responder_data, mid = 1)

# Random-effects individual method with relative measures:
responder_analysis(sample_responder_data, mid = 1,
  method = "individual", pooling = "random")

---

Common-language effect size (probabilistic index)

Description

A threshold-free responder-type measure: the probability that a randomly chosen treated patient has a better change score than a randomly chosen control. Under a Normal model this is exact, $\mathrm{CLES} = \Phi(\delta)$ with $\delta = (\mu_e - \mu_c) / \sqrt{\sigma_e^2 + \sigma_c^2}$ (the sign is flipped when direction = "lower"). Per-study $\delta$ values are pooled by fixed- or random-effect inverse variance and back-transformed, so no minimal important difference is required.

Usage

responder_cles(
  data,
  direction = c("higher", "lower"),
  pooling = c("fixed", "random"),
  tau_method = c("DL", "REML"),
  ci_method = c("wald", "hksj"),
  conf_level = 0.95
)

Arguments

data	A data frame with columns study, change_e, sd_e, n_e, change_c, sd_c, n_c. See sample_responder_data.
direction	"higher" (a larger change is better) or "lower".
pooling	"fixed" (default) or "random" effects.
tau_method	Between-study variance estimator for random effects: "DL" (default) or "REML".
ci_method	Random-effects interval method: "wald" (default) or "hksj" (Hartung-Knapp-Sidik-Jonkman, better for small numbers of studies).
conf_level	Confidence level (default 0.95).

Value

A list with:

studies

Per-study data frame: study, delta, cles, cles_lb, cles_ub.

cles, cles_lb, cles_ub

Pooled CLES and its interval.

delta, se_delta

Pooled standardized difference and its SE.

tau2, i2, q, q_p, pi_lb, pi_ub

Heterogeneity statistics; the prediction interval is back-transformed to the CLES scale.

pooling, k

Settings echoed back.

References

McGraw KO, Wong SP (1992). A common language effect size statistic. Psychological Bulletin, 111(2), 361 to 365.

Examples

cles <- responder_cles(sample_responder_data)
cles$cles

---

Responder proportions from continuous arm summaries

Description

Estimates, for each study arm, the probability that a patient's change score crosses the minimal important difference (MID) threshold under a parametric model for the change scores, together with a delta-method (sampling) variance for that probability.

Usage

responder_proportions(
  change,
  sd,
  n,
  mid,
  direction = c("higher", "lower"),
  dist = c("normal", "lognormal", "t"),
  df = NULL
)

Arguments

change	Numeric vector of mean change scores.
sd	Numeric vector of standard deviations (⁠> 0⁠).
n	Numeric vector of sample sizes (⁠>= 2⁠).
mid	Single finite number: the minimal important difference threshold.
direction	"higher" (a larger change indicates response) or "lower".
dist	Change-score distribution: "normal" (default), "lognormal" or "t".
df	Degrees of freedom when dist = "t".

Value

A data frame with one row per input element and columns p (responder probability) and var_p (delta-method variance).

References

Thorlund K, Walter SD, Johnston BC, Furukawa TA, Guyatt GH (2011). Pooling health-related quality of life outcomes in meta-analysis: a tutorial and review of methods for enhancing interpretability. Research Synthesis Methods, 2(3), 188 to 203. doi:10.1002/jrsm.46

Anzures-Cabrera J, Sarpatwari A, Higgins JPT (2011). Expressing findings from meta-analyses of continuous outcomes in terms of risks. Statistics in Medicine, 30(25), 2867 to 2880. doi:10.1002/sim.4298

Examples

responder_proportions(
  change = c(0.96, 0.79, 1.02), sd = c(1.26, 1.28, 1.34),
  n = c(43, 139, 156), mid = 1
)

---

Per-study responder risk differences

Description

Dichotomizes each study at the MID threshold and returns the per-study responder risk difference (experimental minus control) with a confidence interval. Building block for the "individual" method of responder_analysis(); also feeds the forest plot and per-study table.

Usage

responder_rd_individual(
  data,
  mid,
  direction = c("higher", "lower"),
  se_method = c("binomial", "delta"),
  conf_level = 0.95,
  dist = c("normal", "lognormal", "t"),
  df = NULL,
  mid_sd = 0
)

Arguments

data	A data frame with one row per study and columns study, change_e, sd_e, n_e, change_c, sd_c, n_c. See sample_responder_data.
mid	Single finite number: the minimal important difference threshold.
direction	"higher" (a larger change indicates response) or "lower".
se_method	Per-study SE model for "individual": "binomial" (default) or "delta". The "binomial" variance p(1 - p) / n is a pseudo-binomial approximation: p is a probability implied by the estimated mean and SD, not a proportion of observed dichotomized patients, so it does not include the uncertainty in the reported mean and SD. "delta" propagates that uncertainty and is generally preferable for summary-statistic inputs; "binomial" is the default only for continuity with earlier results.
conf_level	Confidence level (default 0.95).
dist	Change-score distribution: "normal" (default), "lognormal" or "t".
df	Degrees of freedom when dist = "t".
mid_sd	Optional standard deviation of the MID threshold; when ⁠> 0⁠ its uncertainty is propagated into the effect-measure variances.

Value

A data frame with one row per study and columns study, p_e, p_c, rd, se, ci_lb, ci_ub (proportion scale).

See Also

responder_analysis()

Examples

responder_rd_individual(sample_responder_data, mid = 1)

---

Example responder-analysis dataset

Description

A small illustrative dataset of three trials reporting continuous change scores per arm. Used in examples, the bundled Shiny app and the package tests. Values are fictional but plausible.

Usage

sample_responder_data

Format

A data frame with 3 rows and 7 columns:

study

Study identifier.

change_e

Mean change in the experimental arm.

sd_e

Standard deviation of change in the experimental arm.

n_e

Sample size of the experimental arm.

change_c

Mean change in the control arm.

sd_c

Standard deviation of change in the control arm.

n_c

Sample size of the control arm.

Examples

responder_analysis(sample_responder_data, mid = 1)

---

VAS pain change scores from a spinal-health exercise meta-analysis

Description

Per-study change in pain on a 0-10 cm visual analogue scale (VAS) for an exercise-therapy arm versus a control arm, from the 20 randomized trials pooled for the VAS outcome by Li, Bao, Wang and Zhao (2025). The change scores are post minus baseline VAS, so a more negative value is a larger pain reduction; analyze with direction = "lower" and a negative MID equal to the required reduction (for example mid = -1.5 for a 1.5 cm responder threshold).

Usage

vas_pain

Format

A data frame with 20 rows and 7 columns:

study

Study label (first author and year).

change_e

Mean VAS change in the exercise (experimental) arm.

sd_e

Standard deviation of the change in the exercise arm.

n_e

Exercise-arm sample size.

change_c

Mean VAS change in the control arm.

sd_c

Standard deviation of the change in the control arm.

n_c

Control-arm sample size.

Source

Li Z, Bao Z, Wang S, Zhao M (2025). Meta-analysis of the best exercise mode and dose study for improving spinal health. Frontiers in Sports and Active Living, 7, 1614906. doi:10.3389/fspor.2025.1614906. Figure 3 (VAS pain). Reproduced under the Creative Commons Attribution License (CC BY 4.0); the original authors and journal are credited as required.

Examples

# Proportion achieving at least a 1.5 cm VAS reduction (responder),
# exercise versus control, random-effects with HKSJ intervals.
responder_analysis(vas_pain, mid = -1.5, direction = "lower",
  pooling = "random", ci_method = "hksj")

---