Package 'ratesci'

Title: Confidence Intervals for Comparisons of Binomial or Poisson Rates
Description: Computes confidence intervals for the rate (or risk) difference ('RD') or rate ratio (or relative risk, 'RR') for binomial proportions or Poisson rates, or for odds ratio ('OR', binomial only). Also confidence intervals for a single binomial or Poisson rate, and intervals for matched pairs. Includes skewness-corrected asymptotic score ('SCAS') methods, which have been developed in Laud (2017) <doi:10.1002/pst.1813> from Miettinen & Nurminen (1985) <doi:10.1002/sim.4780040211> and Gart & Nam (1988) <doi:10.2307/2531848>. The same score produces hypothesis tests analogous to the test for binomial RD and RR by Farrington & Manning (1990) <doi:10.1002/sim.4780091208>. The package also includes MOVER methods (Method Of Variance Estimates Recovery) for all contrasts, derived from the Newcombe method but using equal-tailed Jeffreys intervals, and generalised for Bayesian applications incorporating prior information. So-called 'exact' methods for strictly conservative coverage are approximated using continuity corrections. Also includes methods for stratified calculations (e.g. meta-analysis), either assuming fixed effects (matching the CMH test) or incorporating stratum heterogeneity.
Authors: Pete Laud [aut, cre]
Maintainer: Pete Laud <[email protected]>
License: GPL-3
Version: 0.4-0
Built: 2024-10-31 20:51:44 UTC
Source: CRAN

Help Index


ratesci: A package for computing confidence intervals for various comparisons of independent binomial and Poisson rates.

Description

Computes confidence intervals for the rate difference (RD), rate ratio (RR), or odds ratio (OR), or for the single rate (p), for independent binomial or Poisson rates. Includes score-based methods with (or without) skewness correction, developed from the Miettinen-Nurminen and Gart-Nam methods, and the "Method of Variance Estimates Recovery", originating from Newcombe. For the single-stratum case, the skewness-corrected asymptotic score (SCAS) method is recommended (Laud 2017), on the basis of superior equal-tailed coverage. Hypothesis tests (a corrected version of the Farrington-Manning test) follow naturally from the score-based methods, and are equivalent to the Cochran-Mantel-Haenszel (CMH) test if the skewness correction is omitted.

ratesci functions

  • scoreci: for score-based confidence intervals

  • scasci: wrapper function to compute SCAS interval

  • tdasci: wrapper function to compute TDAS stratified interval

  • moverci: for the MOVER method

  • moverbci: wrapper function to compute MOVER-B interval

  • jeffreysci: wrapper function to compute Jeffreys interval for a single rate

  • pairbinci: for paired binomial data

  • scaspci: non-iterative SCAS method for a single rate

  • rateci: wrapper function for SCAS, Jeffreys or 'exact' methods for a single rate

Author(s)

Pete Laud, [email protected]

References

Laud PJ. Equal-tailed confidence intervals for comparison of rates. Pharmaceutical Statistics 2017; 16:334-348.

Laud PJ. Corrigendum: Equal-tailed confidence intervals for comparison of rates. Pharmaceutical Statistics 2018; 17:290-293.

Tang Y. Score confidence intervals and sample sizes for stratified comparisons of binomial proportions. Statistics in Medicine 2020; 39:3427–3457.

Tang Y. Comments on “Equal-tailed confidence intervals for comparison of rates”. Pharmaceutical Statistics 2021; online ahead of print.

Laud PJ. Author's reply to the letter to the editor by Yongqiang Tang: Comments on “Equal-tailed confidence intervals for comparison of rates”. Pharmaceutical Statistics 2021; online ahead of print.

Miettinen OS, Nurminen M. Comparative analysis of two rates. Statistics in Medicine 1985; 4:213-226.

Gart JJ. Analysis of the common odds ratio: corrections for bias and skewness. Bulletin of the International Statistical Institute 1985, 45th session, book 1, 175-176.

Gart JJ, Nam JM. Approximate interval estimation of the ratio of binomial parameters: A review and corrections for skewness. Biometrics 1988; 44(2):323-338.

Gart JJ, Nam JM. Approximate interval estimation of the difference in binomial parameters: correction for skewness and extension to multiple tables. Biometrics 1990; 46(3):637-643.

Farrington CP, Manning G. Test statistics and sample size formulae for comparative binomial trials with null hypothesis of non-zero risk difference or non-unity relative risk. Statistics in Medicine 1990; 9(12):1447–1454.

Newcombe RG. Interval estimation for the difference between independent proportions: comparison of eleven methods. Statistics in Medicine 1998; 17(8):873-890.

Donner A, Zou G. Closed-form confidence intervals for functions of the normal mean and standard deviation. Statistical Methods in Medical Research 2012; 21(4):347-359.


Jeffreys and other approximate Bayesian confidence intervals for a single binomial or Poisson rate.

Description

Generalised approximate Bayesian confidence intervals based on a Beta (for binomial rates) or Gamma (for Poisson rates) conjugate priors. Encompassing the Jeffreys method (with Beta(0.5, 0.5) or Gamma(0.5) respectively), as well as any user-specified prior distribution. Clopper-Pearson method (as quantiles of a Beta distribution as described in Brown et al. 2001) also included by way of a "continuity correction" parameter.

Usage

jeffreysci(
  x,
  n,
  ai = 0.5,
  bi = 0.5,
  cc = 0,
  level = 0.95,
  distrib = "bin",
  adj = TRUE,
  ...
)

Arguments

x

Numeric vector of number of events.

n

Numeric vector of sample sizes (for binomial rates) or exposure times (for Poisson rates).

ai, bi

Numbers defining the Beta prior distribution (default ai = bi = 0.5 for Jeffreys interval). Gamma prior for Poisson rates requires only ai.

cc

Number or logical specifying (amount of) "continuity correction". cc = 0 (default) gives Jeffreys interval, cc = 0.5 gives the Clopper-Pearson interval (or Garwood for Poisson). A value between 0 and 0.5 allows a compromise between proximate and conservative coverage.

level

Number specifying confidence level (between 0 and 1, default 0.95).

distrib

Character string indicating distribution assumed for the input data: "bin" = binomial (default), "poi" = Poisson.

adj

Logical (default TRUE) indicating whether to apply the boundary adjustment recommended on p108 of Brown et al. (set to FALSE if informative priors are used)

...

Other arguments.

Author(s)

Pete Laud, [email protected]

References

Laud PJ. Equal-tailed confidence intervals for comparison of rates. Pharmaceutical Statistics 2017; 16:334-348.

Brown LD, Cai TT, DasGupta A. Interval estimation for a binomial proportion. Statistical Science 2001; 16(2):101-133

Examples

# Jeffreys method:
jeffreysci(x = 5, n = 56)

Approximate Bayesian ("MOVER-B") confidence intervals for comparisons of independent binomial or Poisson rates.

Description

Wrapper function for the MOVER-B methods. Approximate Bayesian confidence intervals for the rate (or risk) difference ("RD") or ratio ("RR") for independent binomial or Poisson rates, or for odds ratio ("OR", binomial only). (developed from Newcombe, Donner & Zou, Li et al, and Fagerland & Newcombe, and generalised as "MOVER-B" in forthcoming publication) including special case "MOVER-J" using non-informative priors with optional continuity correction. This function is vectorised in x1, x2, n1, and n2.

Usage

moverbci(
  x1,
  n1,
  x2,
  n2,
  a1 = 0.5,
  b1 = 0.5,
  a2 = 0.5,
  b2 = 0.5,
  distrib = "bin",
  contrast = "RD",
  level = 0.95,
  cc = 0,
  ...
)

Arguments

x1, x2

Numeric vectors of numbers of events in group 1 & group 2 respectively.

n1, n2

Numeric vectors of sample sizes (for binomial rates) or exposure times (for Poisson rates) in each group.

a1, b1, a2, b2

Numbers defining the Beta(ai,bi) prior distributions for each group (default ai = bi = 0.5 for Jeffreys uninformative priors). Gamma priors for Poisson rates require only a1, a2.

distrib

Character string indicating distribution assumed for the input data: "bin" = binomial (default), "poi" = Poisson.

contrast

Character string indicating the contrast of interest: "RD" = rate difference (default), "RR" = rate ratio, "OR" = odds ratio. contrast="p" gives an interval for the single proportion x1/n1.

level

Number specifying confidence level (between 0 and 1, default 0.95).

cc

Number or logical specifying (amount of) continuity correction (default FALSE). Numeric value is taken as the gamma parameter in Laud 2017, Appendix S2 (default 0.5 if cc=TRUE). Forced equal to 0.5 if type="exact". NB: cc currently not implemented for type="wilson".

...

Additional arguments.


MOVER confidence intervals for comparisons of independent binomial or Poisson rates.

Description

Confidence intervals applying the MOVER method ("Method of Variance Estimates Recovery", developed from the Newcombe method for binomial RD) across different contrasts (RD, RR, OR) and distributions (binomial, Poisson) using equal-tailed Jeffreys intervals instead of the Wilson score method for the event rates. Also allows more general Beta and Gamma priors for an approximate Bayesian confidence interval incorporating prior beliefs about the group event rates.

Usage

moverci(
  x1,
  n1,
  x2 = NULL,
  n2 = NULL,
  a1 = 0.5,
  b1 = 0.5,
  a2 = 0.5,
  b2 = 0.5,
  cc = FALSE,
  level = 0.95,
  distrib = "bin",
  contrast = "RD",
  type = "jeff",
  adj = FALSE,
  ...
)

Arguments

x1, x2

Numeric vectors of numbers of events in group 1 & group 2 respectively.

n1, n2

Numeric vectors of sample sizes (for binomial rates) or exposure times (for Poisson rates) in each group.

a1, b1, a2, b2

Numbers defining the Beta(ai,bi) prior distributions for each group (default ai = bi = 0.5 for Jeffreys method). Gamma priors for Poisson rates require only a1, a2.

cc

Number or logical specifying (amount of) continuity correction (default FALSE). Numeric value is taken as the gamma parameter in Laud 2017, Appendix S2 (default 0.5 if cc=TRUE). Forced equal to 0.5 if type="exact". NB: cc currently not implemented for type="wilson".

level

Number specifying confidence level (between 0 and 1, default 0.95).

distrib

Character string indicating distribution assumed for the input data: "bin" = binomial (default), "poi" = Poisson.

contrast

Character string indicating the contrast of interest: "RD" = rate difference (default), "RR" = rate ratio, "OR" = odds ratio. contrast="p" gives an interval for the single proportion x1/n1.

type

Character string indicating the method used for the intervals for the individual group rates. "jeff" = Jeffreys equal-tailed intervals (default); "exact" = Clopper-Pearson/Garwood exact intervals (note this does NOT result in a strictly conservative interval for the contrast, except for contrast='p'. The scoreci function with cc=TRUE is recommended as a superior approximation of 'exact' methods); "midp" = mid-p intervals (to be added); "SCAS" = SCAS non-iterative intervals (to be added); "wilson" = Wilson score intervals (as per Newcombe 1998). NB: "wilson" option is included only for legacy validation against previous published method by Newcombe. It is not recommended, as type="jeff" achieves much better coverage properties.

adj

Logical (default FALSE) indicating whether to apply the boundary adjustment for Jeffreys intervals recommended on p108 of Brown et al. (type = "jeff" only: set to FALSE if using informative priors)

...

Additional arguments.

Value

A matrix containing the confidence interval for the requested contrast

Author(s)

Pete Laud, [email protected]

References

Laud PJ. Equal-tailed confidence intervals for comparison of rates. Pharmaceutical Statistics 2017; 16:334-348.

Newcombe RG. Interval estimation for the difference between independent proportions: comparison of eleven methods. Statistics in Medicine 1998;

Donner A, Zou G. Closed-form confidence intervals for functions of the normal mean and standard deviation. Statistical Methods in Medical Research

Fagerland MW, Newcombe RG. Confidence intervals for odds ratio and relative risk based on the inverse hyperbolic sine transformation. Statistics in Medicine 2013; 32(16):2823-2836.

Li HQ, Tang ML, Wong WK. Confidence intervals for ratio of two Poisson rates using the method of variance estimates recovery. Computational Statistics 2014; 29(3-4):869-889.

Examples

# Binomial RD, MOVER-J method:
moverci(x1 = 5, n1 = 56, x2 = 0, n2 = 29)

# Binomial RD, Newcombe method:
moverci(x1 = 5, n1 = 56, x2 = 0, n2 = 29, type = "wilson")

Confidence intervals for comparisons of paired binomial rates.

Description

Score-based confidence intervals for the rate (or risk) difference ('RD'), rate ratio ('RR') or odds ratio ('OR'), for paired binomial data. [For paired Poisson rates, use the tdasci function with distrib='poi', and weighting='MH', with pairs as strata.]. This function applies the Tango and Tang methods for RD and RR respectively, as well as an experimental method using the stratified TDAS method with pairs as strata. For OR, intervals are produced based on transforming various intervals for the single proportion, including SCAS, mid-p and Jeffreys.

Usage

pairbinci(
  x,
  contrast = "RD",
  level = 0.95,
  method_RD = "Score",
  method_RR = "Score",
  method_OR = "SCAS",
  theta0 = NULL,
  precis = 6
)

Arguments

x

A numeric vector object specified as c(a,b,c,d) where: a is the number of pairs with the event (e.g. success) under both conditions (e.g. treated/untreated, or case/control) b is the count of the number with the event on condition 1 only (=n12) c is the count of the number with the event on condition 2 only (=n21) d is the number of pairs with no event under both conditions (Note the order of a and d is only important for contrast="RR".)

contrast

Character string indicating the contrast of interest: "RD" = rate difference (default), "RR" = rate ratio, "OR" = odds ratio.

level

Number specifying confidence level (between 0 and 1, default 0.95).

method_RD

Character string indicating the confidence interval method to be used for contrast="RD". "Score" = Tango asymptotic score (default), "TDAS" = t-distribution asymptotic score (experimental method, seems to struggle with low numbers).

method_RR

Character string indicating the confidence interval method to be used for contrast="RR". "Score" = Tang asymptotic score (default), "TDAS" t-distribution asymptotic score (experimental method, seems to struggle with low numbers).

method_OR

Character string indicating the confidence interval method to be used for contrast="OR", all of which are based on transformation of an interval for a single proportion b/(b+c): "SCAS" = transformed skewness-corrected score (default), "Jeffreys" = transformed Jeffreys (to be added), "midp" = transformed mid-p, ("Wilson" = transformed Wilson score - not yet included, would be for reference only, not recommended).

theta0

Number to be used in a one-sided significance test (e.g. non-inferiority margin). 1-sided p-value will be <0.025 iff 2-sided 95% CI excludes theta0. NB: can also be used for a superiority test by setting theta0=0.

precis

Number (default 6) specifying precision (i.e. number of decimal places) to be used in optimisation subroutine for the confidence interval.

Author(s)

Pete Laud, [email protected]

References

Laud PJ. Equal-tailed confidence intervals for comparison of rates. Pharmaceutical Statistics 2017; 16:334-348.

Tango T. Equivalence test and confidence interval for the difference in proportions for the paired-sample design. Statistics in Medicine 1998; 17:891-908

Tango T. Improved confidence intervals for the difference between binomial proportions based on paired data by Robert G. Newcombe, Statistics in Medicine, 17, 2635–2650 (1998). Statistics in Medicine 1999; 18(24):3511-3513

Tang N-S, Tang M-L, Chan ISF. On tests of equivalence via non-unity relative risk for matched-pair design. Statistics in Medicine 2003; 22:1217-1233

Fagerland MW, Lydersen S, Laake P. Recommended tests and confidence intervals for paired binomial proportions. Statistics in Medicine 2014; 33(16):2850–2875

Agresti A, Min Y. Simple improved confidence intervals for comparing matched proportions. Statistics in Medicine 2005; 24:729-740

Examples

# Data example from Agresti-Min 2005
pairbinci(x = c(53, 16, 8, 9), contrast = "RD", method_RD = "Score")
pairbinci(x = c(53, 16, 8, 9), contrast = "RD", method_RD = "TDAS")
pairbinci(x = c(53, 16, 8, 9), contrast = "RR", method_RR = "Score")
pairbinci(x = c(53, 16, 8, 9), contrast = "RR", method_RR = "TDAS")
pairbinci(x = c(53, 16, 8, 9), contrast = "OR", method_OR = "SCAS")

Selected confidence intervals for the single binomial or Poisson rate.

Description

Confidence intervals for the single binomial or Poisson rate. Including SCAS or Jeffreys intervals, with or without continuity correction, and 'exact' Clopper-Pearson/Garwood or mid-p intervals.

Usage

rateci(x, n, distrib = "bin", level = 0.95, cc = FALSE, precis = 6)

Arguments

x

Numeric vector of number of events.

n

Numeric vector of sample size (for binomial rate) or exposure times (for Poisson rate).

distrib

Character string indicating distribution assumed for the input data: "bin" = binomial (default), "poi" = Poisson.

level

Number specifying confidence level (between 0 and 1, default 0.95).

cc

Number or logical (default FALSE) specifying continuity correction.

precis

Number (default 6) specifying precision (i.e. number of decimal places) to be used in optimisation subroutine for the SCAS and exact methods.

Value

A list containing, for each method, a matrix containing lower and upper confidence limits for each value of x and n. Methods shown depend on the cc parameter, which specifies whether the continuity correction is applied to the SCAS and Jeffreys methods. The corresponding 'exact' method is Clopper-Pearson/Garwood if cc == TRUE and mid-p if cc == FALSE.

Author(s)

Pete Laud, [email protected]


Skewness-corrected asymptotic score ("SCAS") confidence intervals for comparisons of independent binomial or Poisson rates.

Description

Wrapper function for the SCAS method. Score-based confidence intervals for the rate (or risk) difference ("RD") or ratio ("RR") for independent binomial or Poisson rates, or for odds ratio ("OR", binomial only), or the single rate ("p"). (This is the "GNbc" method from Laud & Dane, developed from Gart & Nam, and generalised as "SCAS" in Laud 2017) including optional continuity correction. This function is vectorised in x1, x2, n1, and n2. Vector inputs may also be combined into a single stratified analysis (e.g. meta-analysis). This method assumes the contrast is constant across strata (fixed effects). For a 'random-effects' method use tdasci (or scoreci with random = TRUE).

Usage

scasci(
  x1,
  n1,
  x2 = NULL,
  n2 = NULL,
  distrib = "bin",
  contrast = "RD",
  level = 0.95,
  cc = FALSE,
  theta0 = NULL,
  precis = 6,
  plot = FALSE,
  hetplot = FALSE,
  xlim = NULL,
  ylim = NULL,
  plotmax = 100,
  stratified = FALSE,
  weighting = NULL,
  MNtol = 1e-08,
  wt = NULL,
  warn = TRUE,
  ...
)

Arguments

x1, x2

Numeric vectors of numbers of events in group 1 & group 2 respectively.

n1, n2

Numeric vectors of sample sizes (for binomial rates) or exposure times (for Poisson rates) in each group.

distrib

Character string indicating distribution assumed for the input data: "bin" = binomial (default), "poi" = Poisson.

contrast

Character string indicating the contrast of interest: "RD" = rate difference (default), "RR" = rate ratio, "OR" = odds ratio. contrast="p" gives an interval for the single proportion or rate x1/n1.

level

Number specifying confidence level (between 0 and 1, default 0.95).

cc

Number or logical (default FALSE) specifying (amount of) continuity correction. Numeric value is taken as the gamma parameter in Laud 2017, Appendix S2 (default 0.5 if cc = TRUE). IMPORTANT NOTES: 1) This is a 'continuity correction' aimed at approximating strictly conservative coverage, NOT for dealing with zero cell counts. Such 'sparse data adjustments' are not needed in the score method, except to deal with double-zero cells for RD (& double-100 binomial RD & RR) with IVS/INV weights. 2) The continuity corrections provided here have not been fully tested for stratified methods.

theta0

Number to be used in a one-sided significance test (e.g. non-inferiority margin). 1-sided p-value will be <0.025 iff 2-sided 95% CI excludes theta0. By default, a two-sided test against theta0 = 0 (for RD) or 1 (for RR/OR) is also output.

precis

Number (default 6) specifying precision (i.e. number of decimal places) to be used in optimisation subroutine for the confidence interval.

plot

Logical (default FALSE) indicating whether to output plot of the score function

hetplot

Logical (default FALSE) indicating whether to output plots for evaluating heterogeneity of stratified datasets.

xlim

pair of values indicating range of values to be plotted.

ylim

pair of values indicating range of values to be plotted.

plotmax

Numeric value indicating maximum value to be displayed on x-axis of plots (useful for ratio contrasts which can be infinite).

stratified

Logical (default FALSE) indicating whether to combine vector inputs into a single stratified analysis. IMPORTANT NOTE: The mechanism for stratified calculations is enabled for contrast = "p", but the performance of the resulting intervals has not been fully evaluated.

weighting

String indicating which weighting method to use if stratified = "TRUE": "IVS" = Inverse Variance of Score (see Laud 2017 for details), "INV" = Inverse Variance (bcf omitted, default for contrast = "OR"), "MH" = Mantel-Haenszel (default for contrast = "RD" or "RR"), "MN" = Miettinen-Nurminen iterative weights. For CI consistent with a CMH test, select skew = FALSE and use MH weighting for RD/RR and IVS for OR.

MNtol

Numeric value indicating convergence tolerance to be used in iteration with weighting = "MN".

wt

Numeric vector containing (optional) user-specified weights.

warn

Logical (default TRUE) giving the option to suppress warnings.

...

Other arguments.

Value

A list containing the following components:

estimates

a matrix containing estimates of the rates in each group and of the requested contrast, with its confidence interval

pval

a matrix containing details of the corresponding 2-sided significance test against the null hypothesis that p_1 = p_2, and one-sided significance tests against the null hypothesis that theta >= or <= theta0

call

details of the function call

If stratified = TRUE, the following outputs are added:

Qtest

a vector of values describing and testing heterogeneity

weighting

a string indicating the selected weighting method

stratdata

a matrix containing stratum estimates and weights


Skewness-corrected asymptotic score ("SCAS") confidence intervals for single binomial or Poisson rate using closed-form calculations. This function is vectorised in x, n.

Description

Skewness-corrected asymptotic score ("SCAS") confidence intervals for single binomial or Poisson rate using closed-form calculations. This function is vectorised in x, n.

Usage

scaspci(x, n, distrib = "bin", level = 0.95, cc = FALSE, ...)

Arguments

x

Numeric vector of number of events.

n

Numeric vector of sample sizes (for binomial rates) or exposure times (for Poisson rates).

distrib

Character string indicating distribution assumed for the input data: "bin" = binomial (default), "poi" = Poisson.

level

Number specifying confidence level (between 0 and 1, default 0.95).

cc

Number or logical (default FALSE) specifying (amount of) continuity correction. Numeric value is taken as the gamma parameter in Laud 2017, Appendix S2 (default 0.5 if cc = TRUE). IMPORTANT NOTES: 1) This is a 'continuity correction' aimed at approximating strictly conservative coverage, NOT for dealing with zero cell counts. Such 'sparse data adjustments' are not needed in the score method, except to deal with double-zero cells for RD (& double-100 binomial RD & RR) with IVS/INV weights. 2) The continuity corrections provided here have not been fully tested for stratified methods.

...

Other arguments.


Score confidence intervals for comparisons of independent binomial or Poisson rates.

Description

Score-based confidence intervals for the rate (or risk) difference ("RD") or ratio ("RR") for independent binomial or Poisson rates, or for odds ratio ("OR", binomial only). Including options for bias correction (from Miettinen & Nurminen), skewness correction ("GNbc" method from Laud & Dane, developed from Gart & Nam, and generalised as "SCAS" in Laud 2017) and continuity correction (for strictly conservative coverage). Also includes score intervals for a single binomial proportion or Poisson rate. Based on the Wilson score interval, when corrected for skewness, coverage is almost identical to the mid-p method, or Clopper-Pearson when also continuity-corrected. Hypothesis tests for superiority or non-inferiority are provided using the same score, to ensure consistency between test and CI. This function is vectorised in x1, x2, n1, and n2. Vector inputs may also be combined into a single stratified analysis (e.g. meta-analysis), either using fixed effects, or the more general random effects "TDAS" method, which incorporates stratum variability using a t-distribution score (inspired by Hartung-Knapp-Sidik-Jonkman). For fixed-effects analysis of stratified datasets, with weighting = "MH" for RD or RR, or weighting = "IVS" for OR, omitting the skewness correction produces the CMH test, together with a coherent confidence interval for the required contrast.

Usage

scoreci(
  x1,
  n1,
  x2 = NULL,
  n2 = NULL,
  distrib = "bin",
  contrast = "RD",
  level = 0.95,
  skew = TRUE,
  simpleskew = FALSE,
  ORbias = TRUE,
  RRtang = NULL,
  bcf = TRUE,
  cc = FALSE,
  theta0 = NULL,
  precis = 6,
  plot = FALSE,
  plotmax = 100,
  hetplot = FALSE,
  xlim = NULL,
  ylim = NULL,
  stratified = FALSE,
  weighting = NULL,
  MNtol = 1e-08,
  wt = NULL,
  sda = NULL,
  fda = NULL,
  dropzeros = FALSE,
  tdas = NULL,
  random = FALSE,
  prediction = FALSE,
  warn = TRUE,
  ...
)

Arguments

x1, x2

Numeric vectors of numbers of events in group 1 & group 2 respectively.

n1, n2

Numeric vectors of sample sizes (for binomial rates) or exposure times (for Poisson rates) in each group.

distrib

Character string indicating distribution assumed for the input data: "bin" = binomial (default), "poi" = Poisson.

contrast

Character string indicating the contrast of interest: "RD" = rate difference (default), "RR" = rate ratio, "OR" = odds ratio. contrast="p" gives an interval for the single proportion or rate x1/n1.

level

Number specifying confidence level (between 0 and 1, default 0.95).

skew

Logical (default TRUE) indicating whether to apply skewness correction (for the SCAS method recommended in Laud 2017) or not (for the Miettinen-Nurminen method).

simpleskew

Logical (default FALSE) indicating whether to use the "simplified" skewness correction instead of the quadratic solution. See Laud 2021 for details. NOTE: this version of the score is only suitable for obtaining confidence limits, not p-values.

ORbias

Logical (default is TRUE for contrast="OR", otherwise NULL) indicating whether to apply additional bias correction for OR derived from Gart 1985. (Corrigendum to Laud 2017, published May 2018). Only applies if contrast is "OR".

RRtang

Logical indicating whether to use Tang's score for RR: Stheta = (p1hat - p2hat * theta) / p2d (see Tang 2020). Default TRUE for stratified = TRUE, with weighting = "IVS" or "INV". Forced to FALSE for stratified = TRUE, with fixed weighting. Experimental for distrib = "poi".

bcf

Logical (default TRUE) indicating whether to apply bias correction in the score denominator. Applicable to distrib = "bin" only. (NB: bcf = FALSE option is really only included for legacy validation against previous published methods (i.e. Gart & Nam, Mee, or standard Chi-squared test). Ignored for contrast = "p".

cc

Number or logical (default FALSE) specifying (amount of) continuity correction. Numeric value is taken as the gamma parameter in Laud 2017, Appendix S2 (default 0.5 if cc = TRUE). IMPORTANT NOTES: 1) This is a 'continuity correction' aimed at approximating strictly conservative coverage, NOT for dealing with zero cell counts. Such 'sparse data adjustments' are not needed in the score method, except to deal with double-zero cells for RD (& double-100 binomial RD & RR) with IVS/INV weights. 2) The continuity corrections provided here have not been fully tested for stratified methods.

theta0

Number to be used in a one-sided significance test (e.g. non-inferiority margin). 1-sided p-value will be <0.025 iff 2-sided 95% CI excludes theta0. If bcf = FALSE and skew = FALSE this gives a Farrington-Manning test. By default, a two-sided test against theta0 = 0 (for RD) or 1 (for RR/OR) is also output: if bcf = FALSE and skew = FALSE this is the same as Pearson's Chi-squared test.

precis

Number (default 6) specifying precision (i.e. number of decimal places) to be used in optimisation subroutine for the confidence interval.

plot

Logical (default FALSE) indicating whether to output plot of the score function

plotmax

Numeric value indicating maximum value to be displayed on x-axis of plots (useful for ratio contrasts which can be infinite).

hetplot

Logical (default FALSE) indicating whether to output plots for evaluating heterogeneity of stratified datasets.

xlim

pair of values indicating range of values to be plotted.

ylim

pair of values indicating range of values to be plotted.

stratified

Logical (default FALSE) indicating whether to combine vector inputs into a single stratified analysis. IMPORTANT NOTE: The mechanism for stratified calculations is enabled for contrast = "p", but the performance of the resulting intervals has not been fully evaluated.

weighting

String indicating which weighting method to use if stratified = "TRUE": "IVS" = Inverse Variance of Score (see Laud 2017 for details), "INV" = Inverse Variance (bcf omitted, default for contrast = "OR"), "MH" = Mantel-Haenszel (default for contrast = "RD" or "RR"), "MN" = Miettinen-Nurminen iterative weights. For CI consistent with a CMH test, select skew = FALSE and use MH weighting for RD/RR and IVS for OR.

MNtol

Numeric value indicating convergence tolerance to be used in iteration with weighting = "MN".

wt

Numeric vector containing (optional) user-specified weights.

sda

Sparse data adjustment to avoid zero variance when x1 + x2 = 0: Only applied when stratified = TRUE. Default 0.5 for RD with IVS/INV weights. Not required for RR/OR, default is to remove double-zero strata instead.

fda

Full data adjustment to avoid zero variance when x1 + x2 = n1 + n2: Only applied when stratified = TRUE. Default 0.5 for RD & RR with IVS/INV weights. Not required for OR, default is to remove affected strata.

dropzeros

Logical (default FALSE) indicating whether to drop uninformative strata for RR/OR, even when the choice of weights would allow them to be retained for a fixed effects analysis. Has no effect on estimates, just the heterogeneity test.

tdas

(deprecated: parameter renamed to random)

random

Logical (default FALSE) indicating whether to perform random effects meta-analysis for stratified data, using the t-distribution (TDAS) method for stratified data (defined in Laud 2017). NOTE: If random = TRUE, then skew = TRUE only affects the per-stratum estimates.

prediction

Logical (default FALSE) indicating whether to produce a prediction interval (work in progress).

warn

Logical (default TRUE) giving the option to suppress warnings.

...

Other arguments.

Value

A list containing the following components:

estimates

a matrix containing estimates of the rates in each group and of the requested contrast, with its confidence interval

pval

a matrix containing details of the corresponding 2-sided significance test against the null hypothesis that p_1 = p_2, and one-sided significance tests against the null hypothesis that theta >= or <= theta0

call

details of the function call

If stratified = TRUE, the following outputs are added:

Qtest

a vector of values describing and testing heterogeneity

weighting

a string indicating the selected weighting method

stratdata

a matrix containing stratum estimates and weights

Author(s)

Pete Laud, [email protected]

References

Laud PJ. Equal-tailed confidence intervals for comparison of rates. Pharmaceutical Statistics 2017; 16:334-348.

Laud PJ. Corrigendum: Equal-tailed confidence intervals for comparison of rates. Pharmaceutical Statistics 2018; 17:290-293.

Laud PJ, Dane A. Confidence intervals for the difference between independent binomial proportions: comparison using a graphical approach and moving averages. Pharmaceutical Statistics 2014; 13(5):294–308.

Miettinen OS, Nurminen M. Comparative analysis of two rates. Statistics in Medicine 1985; 4:213-226.

Farrington CP, Manning G. Test statistics and sample size formulae for comparative binomial trials with null hypothesis of non-zero risk difference or non-unity relative risk. Statistics in Medicine 1990; 9(12):1447-1454.

Gart JJ. Analysis of the common odds ratio: corrections for bias and skewness. Bulletin of the International Statistical Institute 1985, 45th session, book 1, 175-176.

Gart JJ, Nam Jm. Approximate interval estimation of the ratio of binomial parameters: a review and corrections for skewness. Biometrics 1988; 44(2):323-338.

Gart JJ, Nam Jm. Approximate interval estimation of the difference in binomial parameters: correction for skewness and extension to multiple tables. Biometrics 1990; 46(3):637-643.

Tang Y. Score confidence intervals and sample sizes for stratified comparisons of binomial proportions. Statistics in Medicine 2020; 39:3427–3457.

Examples

# Binomial RD, SCAS method:
scoreci(
  x1 = c(12, 19, 5), n1 = c(16, 29, 56),
  x2 = c(1, 22, 0), n2 = c(16, 30, 29)
)

# Binomial RD, MN method:
scoreci(
  x1 = c(12, 19, 5), n1 = c(16, 29, 56),
  x2 = c(1, 22, 0), n2 = c(16, 30, 29), skew = FALSE
)

# Poisson RR, SCAS method:
scoreci(x1 = 5, n1 = 56, x2 = 0, n2 = 29, distrib = "poi", contrast = "RR")

# Poisson RR, MN method:
scoreci(
  x1 = 5, n1 = 56, x2 = 0, n2 = 29, distrib = "poi",
  contrast = "RR", skew = FALSE
)

# Binomial rate, SCAS method:
scoreci(x1 = c(5, 0), n1 = c(56, 29), contrast = "p")

# Binomial rate, Wilson score method:
scoreci(x1 = c(5, 0), n1 = c(56, 29), contrast = "p", skew = FALSE)

# Poisson rate, SCAS method:
scoreci(x1 = c(5, 0), n1 = c(56, 29), distrib = "poi", contrast = "p")

# Stratified example, using data from Hartung & Knapp:
scoreci(
  x1 = c(15, 12, 29, 42, 14, 44, 14, 29, 10, 17, 38, 19, 21),
  x2 = c(9, 1, 18, 31, 6, 17, 7, 23, 3, 6, 12, 22, 19),
  n1 = c(16, 16, 34, 56, 22, 54, 17, 58, 14, 26, 44, 29, 38),
  n2 = c(16, 16, 34, 56, 22, 55, 15, 58, 15, 27, 45, 30, 38),
  stratified = TRUE
)

# TDAS example, using data from Hartung & Knapp:
scoreci(
  x1 = c(15, 12, 29, 42, 14, 44, 14, 29, 10, 17, 38, 19, 21),
  x2 = c(9, 1, 18, 31, 6, 17, 7, 23, 3, 6, 12, 22, 19),
  n1 = c(16, 16, 34, 56, 22, 54, 17, 58, 14, 26, 44, 29, 38),
  n2 = c(16, 16, 34, 56, 22, 55, 15, 58, 15, 27, 45, 30, 38),
  stratified = TRUE, random = TRUE
)

# Stratified example, with extremely rare instance of non-calculable skewness
# correction seen on plot of score function:
scoreci(
  x1 = c(1, 16), n1 = c(20, 40), x2 = c(0, 139), n2 = c(80, 160),
  contrast = "RD", skew = TRUE, simpleskew = FALSE,
  distrib = "bin", stratified = TRUE, plot = TRUE, weighting = "IVS"
)

t-distribution asymptotic score ("TDAS") confidence intervals for comparisons of independent binomial or Poisson rates.

Description

Wrapper function for the TDAS method. Score-based stratified confidence intervals for the rate (or risk) difference ("RD") or ratio ("RR") for independent binomial or Poisson rates, or for odds ratio ("OR", binomial only), or for prevalence or incidence rate ("p"). This function combines vector inputs into a single stratified random effects analysis (e.g. meta-analysis), incorporating any stratum variability into the confidence interval.

Usage

tdasci(
  x1,
  n1,
  x2 = NULL,
  n2 = NULL,
  distrib = "bin",
  contrast = "RD",
  level = 0.95,
  cc = FALSE,
  theta0 = NULL,
  precis = 6,
  plot = FALSE,
  hetplot = FALSE,
  plotmax = 100,
  xlim = NULL,
  ylim = NULL,
  weighting = NULL,
  MNtol = 1e-08,
  wt = NULL,
  skew = TRUE,
  prediction = FALSE,
  warn = TRUE,
  ...
)

Arguments

x1, x2

Numeric vectors of numbers of events in group 1 & group 2 respectively.

n1, n2

Numeric vectors of sample sizes (for binomial rates) or exposure times (for Poisson rates) in each group.

distrib

Character string indicating distribution assumed for the input data: "bin" = binomial (default), "poi" = Poisson.

contrast

Character string indicating the contrast of interest: "RD" = rate difference (default), "RR" = rate ratio, "OR" = odds ratio. contrast="p" gives an interval for the single proportion or rate x1/n1.

level

Number specifying confidence level (between 0 and 1, default 0.95).

cc

Number or logical (default FALSE) specifying (amount of) continuity correction. Numeric value is taken as the gamma parameter in Laud 2017, Appendix S2 (default 0.5 if cc = TRUE). IMPORTANT NOTES: 1) This is a 'continuity correction' aimed at approximating strictly conservative coverage, NOT for dealing with zero cell counts. Such 'sparse data adjustments' are not needed in the score method, except to deal with double-zero cells for RD (& double-100 binomial RD & RR) with IVS/INV weights. 2) The continuity corrections provided here have not been fully tested for stratified methods.

theta0

Number to be used in a one-sided significance test (e.g. non-inferiority margin). 1-sided p-value will be <0.025 iff 2-sided 95% CI excludes theta0. By default, a two-sided test against theta0 = 0 (for RD) or 1 (for RR/OR) is also output.

precis

Number (default 6) specifying precision (i.e. number of decimal places) to be used in optimisation subroutine for the confidence interval.

plot

Logical (default FALSE) indicating whether to output plot of the score function

hetplot

Logical (default FALSE) indicating whether to output plots for evaluating heterogeneity of stratified datasets.

plotmax

Numeric value indicating maximum value to be displayed on x-axis of plots (useful for ratio contrasts which can be infinite).

xlim

pair of values indicating range of values to be plotted.

ylim

pair of values indicating range of values to be plotted.

weighting

String indicating which weighting method to use if stratified = "TRUE": "IVS" = Inverse Variance of Score (see Laud 2017 for details), "INV" = Inverse Variance (bcf omitted, default for contrast = "OR"), "MH" = Mantel-Haenszel (default for contrast = "RD" or "RR"), "MN" = Miettinen-Nurminen iterative weights. For CI consistent with a CMH test, select skew = FALSE and use MH weighting for RD/RR and IVS for OR.

MNtol

Numeric value indicating convergence tolerance to be used in iteration with weighting = "MN".

wt

Numeric vector containing (optional) user-specified weights.

skew

Logical (default TRUE) indicating whether to apply skewness correction (for the SCAS method recommended in Laud 2017) or not (for the Miettinen-Nurminen method) to the per-stratum estimates provided in the output. Has no effect on the TDAS interval itself.

prediction

Logical (default FALSE) indicating whether to produce a prediction interval (work in progress).

warn

Logical (default TRUE) giving the option to suppress warnings.

...

Other arguments.

Value

A list containing the following components:

estimates

a matrix containing estimates of the rates in each group and of the requested contrast, with its confidence interval

pval

a matrix containing details of the corresponding 2-sided significance test against the null hypothesis that p_1 = p_2, and one-sided significance tests against the null hypothesis that theta >= or <= theta0

Qtest

a vector of values describing and testing heterogeneity

weighting

a string indicating the selected weighting method

stratdata

a matrix containing stratum estimates and weights

call

details of the function call