Type: Package
Title: Frequentist Confidence Analysis for Clinical Trials
Version: 0.1.0
Description: Frequentist confidence analysis answers the question: How confident are we in a particular treatment effect? This package calculates the frequentist confidence in a treatment effect of interest given observed data, and returns the family of confidence curves associated with that data.
License: MIT + file LICENSE
Imports: cowplot (≥ 1.1.3), DescTools (≥ 0.99.54), ggplot2 (≥ 3.5.1), rlang (≥ 1.1.4)
Encoding: UTF-8
RoxygenNote: 7.3.2
Suggests: rmarkdown, stats, testthat (≥ 3.0.0), utils
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2025-08-01 05:31:18 UTC; fwerdiger
Author: Freda Werdiger [aut, cre]
Maintainer: Freda Werdiger <freda.werdiger@unimelb.edu.au>
Repository: CRAN
Date/Publication: 2025-08-19 15:20:02 UTC

Frequentist confidence analysis for any treatment effect

Description

This function performs frequentist confidence analysis, given a point estimate and associated error estimation, to answer the question: How much confidence can we have in a particular treatment effect of interest?

Usage

makeConfidenceCurves(
  theta.estimator = NULL,
  estimator.type = NULL,
  treat.var = NULL,
  standard.error = NULL,
  confidence.lower = NULL,
  confidence.upper = NULL,
  sample.size = NULL,
  num.resp.ctrl = NULL,
  num.resp.trmt = NULL,
  num.ctrl = NULL,
  num.trmt = NULL,
  directory = "",
  show = "BENEFIT",
  pval = "TWO-SIDED",
  min.effect = -0.05,
  neutral.effect = 0,
  dir.benefit = 0,
  dir.min.effect = NULL,
  equiv = NULL,
  save.plot = FALSE,
  return.plot = FALSE,
  tag = ""
)

Arguments

theta.estimator

Enter the point estimate, assumed to follow a Normal distribution.

estimator.type

when entering binary data into inputs, specify "risk difference" or "odds ratio". For "odds ratio" option, the log odds with be used.

treat.var

Variance associated with the point estimate. Must be supplied with sample size.

standard.error

Standard error associated with the point estimate.

confidence.lower

Lower boundary of 95% confidence interval.

confidence.upper

Upper boundary of 95% confidence interval.

sample.size

Sample size. Can be calculated from num.ctrl and num.trmt.

num.resp.ctrl

When specifying binary input data; Number of responders in control group (who experienced the outcome).

num.resp.trmt

When specifying binary input data; Number of responders in treatment group (who experienced the outcome).

num.ctrl

When specifying binary input data; Number of subjects in the control group.

num.trmt

When specifying binary input data; Number of subjects in the treatment group.

directory

Character string expressing directory where you want to save the confidence curve family. Default is "".

show

On the confidence density function, which region to display in shaded blue: BENEFIT' (default), 'LMB' (lack of meaningful benefit), 'MB' (meaningful benefit) or 'EQUIV' (equivalence).

pval

Specify "ONE-SIDED" or "TWO_SIDED" test for returned p-value. Default is "TWO-SIDED".

min.effect

The minimally clinically interesting effect (meaningful benefit). Default is -0.05.

neutral.effect

Value corresponding to no effect. Default is 0. If using odds ratio, data should be on the log scale for a neutral effect of 0.

dir.benefit

Direction (0 or 1) around the neutral effect corresponding to benefit. 0: less than no effect value (default); 1: more than no effect value.

dir.min.effect

Direction (0 or 1) around the min effect that you're interested in. 0: less than min effect value; 1: more than min effect value. Default assumes LACK of meaningful benefit.

equiv

If interested in expressing confidence in treatment equivalence, you can specify two numbers as c(a,b) to bound the equivalency region. Default uses min.effect and -min.effect as a and b

save.plot

save the plot as png to directory, TRUE or FALSE (default).

return.plot

Return the plots from the function, TRUE or FALSE (default).

tag

phrase to append to the image filename as <directory>/confidence_curves_<tag>.png. Default is "".

Details

This is a function to perform frequentist confidence analysis on a observed treatment estimate. You may either supply a point estimate and associated precision estimate via standard error, variance and sample size, and 95% CI interval, or enter outcome data directly (the latter option is only available for binary data). Then, define a neutral effect, and a meaningful clinical effect, and the direction of interest (above or below these) and the function will calculate how much confidence one can have in the associated treatment effect (e.g., beneficial, lacking meaningful benefit). Also returned is the traditional frequentist p-value.

Value

Returns a list of values associated with confidence analysis (under $text) and (if supplied TRUE to return.plot) four confidence curves

References

Equations used in this function are derived from Marschner, I. "Confidence distributions for treatment effects in Clinical Trials: Posteriors without Priors", Statistics in Medicine, 2024;43:1271-1289.

Examples

makeConfidenceCurves(
theta.estimator = -0.22,
confidence.lower = -0.36,
confidence.upper = -0.07
)

Test confidence curves

Description

A short function to test makeConfidenceCurves for binary data

Usage

testConfidenceCurves(
  num.ctrl = 50,
  num.trmt = 50,
  vary.ctrl = seq(16, 20, by = 2),
  vary.trmt = seq(26, 30, by = 2),
  vary.lmb = c(-0.05, -0.1),
  estimate.type = "odds ratio",
  return.plot = TRUE,
  save.plot = FALSE,
  directory = "./test"
)

Arguments

num.ctrl

Number of subjects in control group. Default is 50.

num.trmt

Number of subjects in treatment group. Default is 50.

vary.ctrl

List of numbers to vary response in control group. Default is c(16, 18, 20).

vary.trmt

List of numbers to vary response in treatment group. Default is c(26, 28,30).

vary.lmb

List of numbers to vary definition of meaningful benefit. Default is c(-0.05, -0.1).

estimate.type

Type of estimator, options are "risk difference" and "odds ratio" (default).

return.plot

Return and print the CFD plot. TRUE (default) or FALSE.

save.plot

Save the family of confidence curves to directory. TRUE or FALSE (default).

directory

Location to save images. Default is './test'.

Value

Returns a dataframe

Examples

# to fix control and treatment responders
testConfidenceCurves(vary.lmb = c(-0.05, -0.1), vary.ctrl = c(18), vary.trmt = c(28))
# to run without showing plots
testConfidenceCurves(
vary.lmb = c(-0.05, -0.1),
vary.ctrl = c(18),
vary.trmt = c(28),
return.plot=FALSE)