Package 'dsrTest' reference manual

Title:	Tests and Confidence Intervals on Directly Standardized Rates for Several Methods
Description:	Perform a test of a simple null hypothesis about a directly standardized rate and obtain the matching confidence interval using a choice of methods.
Authors:	Michael Nelson
Maintainer:	Michael Nelson <[email protected]>
License:	GPL (>= 2)
Version:	1.0.0
Built:	2025-02-12 05:27:01 UTC
Source:	https://github.com/mnelsonr/dsrtest

Tests and Confidence Intervals on Directly Standardized Rates for Several Methods

Description

Perform a test of a simple null hypothesis about a directly standardized rate and obtain the matching confidence interval using a choice of methods.

Details

The DESCRIPTION file:

Package:	dsrTest
Type:	Package
Title:	Tests and Confidence Intervals on Directly Standardized Rates for Several Methods
Version:	1.0.0
Date:	2022-06-12
Author:	Michael Nelson
Maintainer:	Michael Nelson <[email protected]>
Description:	Perform a test of a simple null hypothesis about a directly standardized rate and obtain the matching confidence interval using a choice of methods.
Encoding:	UTF-8
License:	GPL (>= 2)
RoxygenNote:	7.2.0
Roxygen:	list(markdown = TRUE)
Depends:	R (>= 2.10)
Imports:	stats, exactci, asht (>= 0.9.1), loglognorm,
Suggests:	testthat, knitr, rmarkdown, covr
URL:	https://github.com/mnelsonr/dsrTest
BugReports:	https://github.com/mnelsonr/dsrTest/issues
VignetteBuilder:	knitr
LazyData:	true
Config/pak/sysreqs:	make
Repository:	https://mnelsonr.r-universe.dev
RemoteUrl:	https://github.com/mnelsonr/dsrtest
RemoteRef:	HEAD
RemoteSha:	55f4b8ccdff179c2db7f22b5f2582cbba6742f66

Index of help topics:

asymptoticControl       Control Function for Asymptotic Method
                        Confidence Intervals
betaControl             Control Function for Beta Method for Confidence
                        Intervals
dobsonControl           Control Function for Dobson Method Confidence
                        Intervals
downs.mi                Downs' syndrome cases and of total live births
                        by maternal age and birth order, Michigan,
                        1950-1964.
dsrTest                 Tests and Confidence Intervals on Directly
                        Standardized Rates
dsrTest-package         Tests and Confidence Intervals on Directly
                        Standardized Rates for Several Methods
gammaControl            Control Function for Gamma Method Confidence
                        Intervals

The function dsrTest() implements a number of different parameterizations and methods for computing confidence intervals on directly standardized rates. These methods are described in detail in Fay and Feuer (1997), Tiwari et al (2006), Ng et al (2008) and Fay and Kim (2017).

The various <method>Control() functions allow modifications to the general approaches.

Author(s)

Michael Nelson

Maintainer: Michael Nelson <[email protected]>

References

Dobson, AJ, Kuulasmaa, K, Eberle, E and Scherer, J (1991) 'Confidence intervals for weighted sums of Poisson parameters', Statistics in Medicine, 10: 457–462. doi:10.1002/sim.4780100317

Swift, MB (1995) 'Simple confidence intervals for standardized rates based on the approximate bootstrap method', Statistics in Medicine, 14, 1875–1888. doi:10.1002/sim.4780141704.

Fay MP & Feuer EJ (1997) 'Confidence intervals for directly standardized rates: a method based on the gamma distribution.' Statistics in Medicine. 16: 791–801. doi:10.1002/(sici)1097-0258(19970415)16:7<791::aid-sim500>3.0.co;2-#

Tiwari RC, Clegg LX, & Zou Z (2006) 'Efficient interval estimation for age-adjusted cancer rates.' Statistical Methods in Medical Research 15: 547–569. doi:10.1177/0962280206070621

Ng HKT, Filardo, G & Zheng G (2008) 'Confidence interval estimating procedures for standardized incidence rates.' Computational Statistics and Data Analysis 52: 3501–3516. doi:10.1016/j.csda.2007.11.004

Fay, MP & Kim S (2017) 'Confidence intervals for directly standardized rates using mid-p gamma intervals.' Biometrical Journal 59(2): 377–387. doi:10.1002/bimj.201600111

Examples

## using the example from asht::wspoissonTest
## birth data on Down's syndrome from Michigan, 1950-1964
## see Table II  of Fay and Feuer (1997)
## xfive = counts for mothers who have had 5 or more children
## nfive and ntotal are number of live births 
xfive<-c(0, 8, 63, 112, 262, 295)
nfive<-c(327, 30666, 123419, 149919, 104088, 34392)
ntotal<-c(319933, 931318, 786511, 488235, 237863, 61313)
## use mult =10^5 to give rates per 100,000
## gamma method of Fay and Feuer (1997) is default
dsrTest(xfive, nfive, ntotal, method = "gamma", mult = 1e5)
## Dobson et al (1991)
dsrTest(xfive, nfive, ntotal, method = "dobson", mult = 1e5)
## Asymptotic with log transformation
dsrTest(xfive, nfive, ntotal, method = "asymptotic", mult = 1e5,
control = list(trans = "log"))
## using the example from asht::wspoissonTest
## birth data on Down's syndrome from Michigan, 1950-1964
## see Table II  of Fay and Feuer (1997)
## xfive = counts for mothers who have had 5 or more children
## nfive and ntotal are number of live births 
xfive<-c(0, 8, 63, 112, 262, 295)
nfive<-c(327, 30666, 123419, 149919, 104088, 34392)
ntotal<-c(319933, 931318, 786511, 488235, 237863, 61313)
## use mult =10^5 to give rates per 100,000
## gamma method of Fay and Feuer (1997) is default
dsrTest(xfive, nfive, ntotal, method = "gamma", mult = 1e5)
## Dobson et al (1991)
dsrTest(xfive, nfive, ntotal, method = "dobson", mult = 1e5)
## Asymptotic with log transformation
dsrTest(xfive, nfive, ntotal, method = "asymptotic", mult = 1e5,
control = list(trans = "log"))

Control Function for Asymptotic Method Confidence Intervals

Description

Specify the transformation to apply to the distribution of the MLE.

Usage

asymptoticControl(trans = c("none", "log", "loglog", "logit"), ...)
asymptoticControl(trans = c("none", "log", "loglog", "logit"), ...)

Arguments

`trans`	Transformation apply to the MLE distribution.
`...`	Currently ignored.

Value

A list with values

trans

Control Function for Beta Method for Confidence Intervals

Description

Modification to the Beta method. The options are "none" or the same modifications as applied to the Gamma Method (see gammaControl) are implemented. wmtype="none" and wmtype="tcz" have been investigated by Tiwari et al (2006) and Ng et al (2008).

Usage

betaControl(wmtype = c("none", "tcz", "max", "mean", "minmaxavg"), ...)
betaControl(wmtype = c("none", "tcz", "max", "mean", "minmaxavg"), ...)

Arguments

`wmtype`	`character` type of modification to the Beta Confidence Interval
`...`	Currently ignored.

Value

a list with values

wmtype

modification to Beta Confidence Interval to implement

References

Tiwari RC, Clegg LX, & Zou Z (2006). 'Efficient interval estimation for age-adjusted cancer rates.' Statistical Methods in Medical Research 15: 547–569. doi:10.1177/0962280206070621

Ng HKT, Filardo, G & Zheng G (2008). 'Confidence interval estimating procedures for standardized incidence rates.' Computational Statistics and Data Analysis 52 3501–3516. doi:10.1016/j.csda.2007.11.004

Control Function for Dobson Method Confidence Intervals

Description

Provides a list of arguments to pass to poisson.exact.

Usage

dobsonControl(midp = FALSE, tsmethod = c("central", "minlike", "blaker"), ...)
dobsonControl(midp = FALSE, tsmethod = c("central", "minlike", "blaker"), ...)

Arguments

`midp`	logical, use mid-p values? Currently only permitted where `tsmethod = "central"`.
`tsmethod`	`character` giving two-sided method
`...`	Currently ignored..

Value

a list with values

`midp`
`tsmethod`

Downs' syndrome cases and of total live births by maternal age and birth order, Michigan, 1950-1964.

Description

This data reproduces table 14.4 in Fleiss (1981) and which is drawn from a large-scale study in Michigan 1950-1964 of the effect of Maternal age and Birth order on Down Syndrome and Leukemia (Stark and Mantell, 1966).

Usage

downs.mi
downs.mi

Format

This data.frame contains the following columns:

Age: The age category of the mothers.
BirthOrder: The birth order.
Cases: The number of cases of Down's Syndrome.
Births: The number of live births.
Standard: A "standard" population, derived as the total number of births in each age category

Source

The data were obtained from table 14.4 (p 249) in

Fleiss, JL (1981) Statistical Methods for Rates and Proportions, Wiley, New York.

The original study is

Stark CR and Mantel N (1966) 'Effects of maternal age and birth order on the risk of mongolism and leukemia' J Natl Cancer Inst 37 (5) 687–698. doi:10.1093/jnci/37.5.687

Tests and Confidence Intervals on Directly Standardized Rates

Description

A number of methods have been proposed for calculating confidence intervals for directly standardized rates. Ng et al (2008), compare a number of methods, some of which are implemented here. The default uses the Gamma method by Fay and Feuer (1997) and implemented in wspoissonTest.

Usage

dsrTest(
  x,
  n,
  w,
  null.value = NULL,
  alternative = c("two.sided", "less", "greater"),
  conf.level = 0.95,
  mult = 1,
  method = c("gamma", "asymptotic", "dobson", "beta", "bootstrap"),
  control = list()
)
dsrTest(
  x,
  n,
  w,
  null.value = NULL,
  alternative = c("two.sided", "less", "greater"),
  conf.level = 0.95,
  mult = 1,
  method = c("gamma", "asymptotic", "dobson", "beta", "bootstrap"),
  control = list()
)

Arguments

`x`	a vector of strata-specific counts.
`n`	a vector of strata-specific time bases for counts.
`w`	a vector of strata-specific weights (or standard populations).
`null.value`	a null hypothesis value of the directly rate, if NULL no test is done. If not NULL, provide in rate per mult.
`alternative`	type of alternative hypothesis.
`conf.level`	confidence level for the returned confidence interval.
`mult`	a factor to multiply the estimate and confidence intervals by, to give rates per mult.
`method`	Method used to perform the test and construct the confidence interval. See details.
`control`	list of arguments / type of modification used for each method. See details and relevant `"xxxxControl"` documentation

Details

Five classes of method have been implemented here:

"gamma": Calls wspoissonTest. By default uses the Gamma Method proposed by Fay and Feuer (1997). Modifications proposed by Tiwari et al (2006) and Fay and Kim (2017) also implemented - see gammaControl.
"asymptotic": Using the normal approximation of the MLE or transformed MLE distribution - see asymptoticControl
"dobson": Uses the method proposed by Dobson et al (1991). Estimating the confidence interval on the unweighted sum is done by calling poisson.exact - both the exact method and a mid-p method are possible - see dobsonControl.
"beta": Methods based on the beta distribution by Tiwari et al (2006) - see betaControl.
"bootstrap": Approximate Bootstrap method by Swift (1995). P-values are estimated by solving for p.

For each method there is a control function that will return a list of parameters that can be used to define sub-types of each of the broad groups

Value

a list with class "htest" containing the following components:

`statistic`	number of strata or summands: `k = length(x)`
`parameter`	mult
`p.value`	p-value, set to `NA` if `null.value = NULL`
`conf.int`	confidence interval on the true directly standardized rate
`estimate`	directly standardized rate
`null.value`	null hypothesis value for the DSR
`alternative`	alternative hypothesis type
`method`	description of the method
`data.name`	description of the data

References

Dobson, AJ, Kuulasmaa, K, Eberle, E and Scherer, J (1991) 'Confidence intervals for weighted sums of Poisson parameters', Statistics in Medicine, 10: 457–462. doi:10.1002/sim.4780100317

Swift, MB (1995). 'Simple confidence intervals for standardized rates based on the approximate bootstrap method', Statistics in Medicine, 14, 1875–1888. doi:10.1002/sim.4780141704.

Fay MP & Feuer EJ (1997). 'Confidence intervals for directly standardized rates: a method based on the gamma distribution. Statistics in Medicine*. 16: 791–801. doi:10.1002/(sici)1097-0258(19970415)16:7<791::aid-sim500>3.0.co;2-# Tiwari RC, Clegg LX, & Zou Z (2006). 'Efficient interval estimation for age-adjusted cancer rates.' Statistical Methods in Medical Research 15: 547–569. doi:10.1177/0962280206070621

Control Function for Gamma Method Confidence Intervals

Description

Provides a list of arguments to pass to wspoissonTest.

Usage

gammaControl(
  midp = FALSE,
  nmc = 0,
  wmtype = c("max", "mean", "minmaxavg", "tcz"),
  unirootTolFactor = 1e-06,
  ...
)
gammaControl(
  midp = FALSE,
  nmc = 0,
  wmtype = c("max", "mean", "minmaxavg", "tcz"),
  unirootTolFactor = 1e-06,
  ...
)

Arguments

`midp`	logical. Use mid-p confidence distribution method? Currently only implemented where `wmtype = "max"`
`nmc`	Calculation method when `midp = TRUE`.
`wmtype`	type of modification for the Gamma confidence interval.
`unirootTolFactor`	tolerance factor for uniroot where `midp = TRUE` and `nmc = 0`.
`...`	Currently ignored.

Value

A list of arguments to pass to wspoissonTest.

If midp = TRUE, with values

`midp`
`nmc`
`unirootTolFactor`

If midp = FALSE, with values:

wmtype

Package 'dsrTest'

Help Index

Tests and Confidence Intervals on Directly Standardized Rates for Several Methods

Description

Details

Author(s)

References

See Also

Examples

Control Function for Asymptotic Method Confidence Intervals

Description

Usage

Arguments

Value

Control Function for Beta Method for Confidence Intervals

Description

Usage

Arguments

Value

References

Control Function for Dobson Method Confidence Intervals

Description

Usage

Arguments

Value

See Also

Downs' syndrome cases and of total live births by maternal age and birth order, Michigan, 1950-1964.

Description

Usage

Format

Source

Tests and Confidence Intervals on Directly Standardized Rates

Description

Usage

Arguments

Details

Value

References

See Also

Control Function for Gamma Method Confidence Intervals

Description

Usage

Arguments

Value

See Also