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)