Help for package respondeR

Title:

Imputing Responder Proportions from Continuous Outcomes

Version:

0.1.0

Description:

Express meta-analyses of continuous trial outcomes in terms of responder risks, following the interpretability tutorial of Thorlund, Walter, Johnston, Furukawa and Guyatt (2011) <doi:10.1002/jrsm.46>. Given the mean change, standard deviation and sample size per arm across studies, respondeR estimates the proportion of patients who cross a minimal important difference (MID) threshold under a parametric model for the change scores, and contrasts the arms as a risk difference, risk ratio, odds ratio or number needed to treat. It provides median, unweighted-mean, weighted-mean and per-study (fixed- or random-effects) pooling, the standardized-mean-difference to odds-ratio bridge of Anzures-Cabrera, Sarpatwari and Higgins (2011) <doi:10.1002/sim.4298>, a threshold-free common-language effect size, and a point-and-click 'Shiny' application. The estimation methods were evaluated in a simulation study by Sofi-Mahmudi (2024) https://hdl.handle.net/11375/30210.

License:

GPL-3

URL:

https://github.com/choxos/respondeR, https://choxos.github.io/respondeR/

BugReports:

https://github.com/choxos/respondeR/issues

Encoding:

UTF-8

Depends:

R (≥ 3.5)

Imports:

stats

Suggests:

shiny, shinydashboard, DT, testthat (≥ 3.0.0), metafor, knitr, rmarkdown

LazyData:

true

VignetteBuilder:

knitr

Config/testthat/edition:

Config/roxygen2/version:

8.0.0

NeedsCompilation:

Packaged:

2026-06-12 18:42:12 UTC; choxos

Author:

Ahmad Sofi-Mahmudi

[aut, cre]

Maintainer:

Ahmad Sofi-Mahmudi <a.sofimahmudi@gmail.com>

Repository:

CRAN

Date/Publication:

2026-06-19 12:10:02 UTC

respondeR: Responder Analysis for Continuous Outcomes

Description

Express meta-analyses of continuous trial outcomes in terms of responder risks, following the interpretability tutorial of Thorlund, Walter, Johnston, Furukawa and Guyatt (2011) doi:10.1002/jrsm.46. Given the mean change, standard deviation and sample size per arm across studies, respondeR estimates the proportion of patients who cross a minimal important difference (MID) threshold under a parametric model for the change scores, and contrasts the arms as a risk difference, risk ratio, odds ratio or number needed to treat. It provides median, unweighted-mean, weighted-mean and per-study (fixed- or random-effects) pooling, the standardized-mean-difference to odds-ratio bridge of Anzures-Cabrera, Sarpatwari and Higgins (2011) doi:10.1002/sim.4298, a threshold-free common-language effect size, and a point-and-click 'Shiny' application. The estimation methods were evaluated in a simulation study by Sofi-Mahmudi (2024) https://hdl.handle.net/11375/30210.

Details

The package converts continuous trial outcomes (mean change, standard deviation and sample size per arm, across studies) into the proportion of "responders": patients whose change crosses a minimal important difference (MID) threshold, under a Normal model for the change scores. It expresses the between-arm contrast as a risk difference (RD). Four pooling strategies are provided (median, unweighted mean, weighted mean and individual), following the interpretability methods reviewed by Thorlund and colleagues (2011) and the cut-point ("dichotomization") and standardized-mean-difference approaches of Anzures-Cabrera, Sarpatwari and Higgins (2011).

The statistical engine lives in exported, side-effect-free functions (responder_analysis(), responder_proportions(), responder_rd_individual(), responder_cles()) so that results are reproducible and unit tested independently of the bundled Shiny application (launch_responder_analysis()).

Author(s)

Maintainer: Ahmad Sofi-Mahmudi a.sofimahmudi@gmail.com (ORCID)

Authors:

Ahmad Sofi-Mahmudi a.sofimahmudi@gmail.com (ORCID)

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

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

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

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

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).

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")

Package {respondeR}

respondeR: Responder Analysis for Continuous Outcomes

Description

Details

Author(s)

References

See Also

Format responder-analysis results for display

Description

Usage

Arguments

Value

Examples

Launch the Responder Analysis Shiny application

Description

Usage

Arguments

Value

Examples

Responder analysis of continuous trial outcomes

Description

Usage

Arguments

Value

Methods

References

See Also

Examples

Common-language effect size (probabilistic index)

Description

Usage

Arguments

Value

References

Examples

Responder proportions from continuous arm summaries

Description

Usage

Arguments

Value

References

Examples

Per-study responder risk differences

Description

Usage

Arguments

Value

See Also

Examples

Example responder-analysis dataset

Description

Usage

Format

Examples

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

Description

Usage

Format

Source

Examples