Package {epibyhand}

epibyhand: Worked Derivations for Classical Epidemiological Measures

Description

Every function returns the answer together with the reasoning that produced it: each intermediate quantity, the formula in symbols, and the formula with the observed numbers substituted in. The result is a derivation object that can be printed at three levels of detail, converted to a data frame with steps_table(), or compared against a student's own arithmetic with check_work().

Scope

The package covers methods a student can compute by hand on paper. That boundary is deliberate and load-bearing: it is what keeps the package small enough to stay correct without continuous maintenance, and it is why there is no regression modelling here. Anything requiring an iterative fit is out of scope by definition rather than by omission.

Options

epibyhand.verbose

Detail level for printing: 0 result only, 1 adds symbolic formulas, 2 (default) full worked solution.

epibyhand.digits

Decimal places, default 4.

Author(s)

Maintainer: Raj Subedi rajsubediresearch@gmail.com

See Also

Useful links:

• https://github.com/rajsubediresearch/epibyhand

• Report bugs at https://github.com/rajsubediresearch/epibyhand/issues

Attributable fraction, with worked derivation

Description

The proportion of disease that would be prevented by removing the exposure, either among the exposed (among = "exposed") or in the whole population (among = "population").

Usage

attributable_fraction(
  x,
  ...,
  among = c("exposed", "population"),
  conf_level = 0.95
)

Arguments

Details

For the population fraction the derivation computes the same quantity three ways – directly from risks, by Levin's formula from exposure prevalence, and by Miettinen's formula from the proportion of cases exposed – and shows that they agree. They are not competing estimators; they are one quantity written three ways, which is easier to believe once seen numerically.

Value

An epibyhand_derivation.

References

Levin, M. L. (1953). The occurrence of lung cancer in man. Acta Unio Internationalis Contra Cancrum, 9(3), 531-541.

Miettinen, O. S. (1974). Proportion of disease caused or prevented by a given exposure, trait or intervention. American Journal of Epidemiology, 99(5), 325-332.

Examples

attributable_fraction(epi2x2(36, 14, 30, 25))
attributable_fraction(epi2x2(36, 14, 30, 25), among = "population")

Check a hand calculation against a derivation

Description

Compare a value you computed by hand against the final estimate, or against a named intermediate step. When the value does not match, check_work() searches every step of the derivation for one that does – so instead of "wrong", the student is told where they stopped or slipped.

Usage

check_work(x, value, step = NULL, tol = 0.005)

Arguments

Value

Invisibly, TRUE if the value matched the requested target.

Examples

d <- odds_ratio(epi2x2(36, 14, 30, 25))
check_work(d, 2.14)
check_work(d, 2.571)

Collapse strata into a single 2 x 2 table

Description

Adds the strata cell by cell, discarding the stratifying variable. The result is the crude table – the one you would have had if you had never stratified. Comparing a crude estimate with its adjusted counterpart is how confounding is made visible.

Usage

collapse_strata(x)

Arguments

Value

An epi2x2.

Examples

collapse_strata(epi_strata(c(10, 20, 5, 40), c(30, 15, 20, 25)))

Extract the confidence interval from a derivation

Description

Extract the confidence interval from a derivation

Usage

## S3 method for class 'epibyhand_derivation'
confint(object, parm, level, ...)

Arguments

Value

Numeric vector of length 2.

Create a derivation object

Description

Create a derivation object

Usage

derivation(
  method,
  estimate,
  symbol = NULL,
  ci = NULL,
  conf_level = 0.95,
  data = NULL,
  steps = list(),
  notes = character()
)

Arguments

Value

An object of class epibyhand_derivation.

Create one step of a derivation

Description

A step is the atomic unit of a worked solution: a human-readable label, the symbolic formula, the same formula with observed values substituted in, and the numeric result.

Usage

derivation_step(
  label,
  formula,
  substituted,
  result,
  symbol = NULL,
  note = NULL,
  table = NULL
)

Arguments

Value

An object of class epibyhand_step.

Build a 2 x 2 table

Description

Accepts either four cell counts or a 2 x 2 matrix/table. Orientation is exposure in rows, outcome in columns, with the index level first in each – the layout used in standard epidemiology texts.

Usage

epi2x2(
  a,
  b = NULL,
  c = NULL,
  d = NULL,
  exposure = c("Exposed", "Unexposed"),
  outcome = c("Case", "Non-case")
)

Arguments

Value

An object of class epi2x2.

Examples

epi2x2(36, 14, 30, 25)
epi2x2(matrix(c(36, 14, 30, 25), nrow = 2, byrow = TRUE))

Build a set of stratified 2 x 2 tables

Description

Accepts a list of epi2x2() objects, a list of four-element count vectors, or a 2 x 2 x K array. Stratum labels are taken from the names of the list, the third dimnames of the array, or generated as "Stratum 1", and so on.

Usage

epi_strata(
  ...,
  labels = NULL,
  exposure = c("Exposed", "Unexposed"),
  outcome = c("Case", "Non-case")
)

Arguments

Value

An object of class epi_strata.

Examples

epi_strata(c(10, 20, 5, 40), c(30, 15, 20, 25), labels = c("Men", "Women"))

Extract the point estimate from a derivation

Description

Extract the point estimate from a derivation

Usage

estimate(x)

Arguments

Value

Numeric scalar.

Breslow-Day test of homogeneity, with worked derivation

Description

Tests whether one common odds ratio can be assumed across strata – the assumption that makes mh_odds_ratio() meaningful. The statistic is a sum of per-stratum contributions, and those contributions are shown, so a single badly behaved stratum can be seen rather than inferred.

Usage

homogeneity(x, ..., tarone = TRUE)

Arguments

Details

Tarone's correction is applied by default; without it the statistic is slightly too large.

Value

An epibyhand_derivation.

References

Breslow, N. E. and Day, N. E. (1980). Statistical Methods in Cancer Research, Volume I: The Analysis of Case-Control Studies. IARC Scientific Publications No. 32, Lyon.

Tarone, R. E. (1985). On heterogeneity tests based on efficient scores. Biometrika, 72(1), 91-95.

Examples

homogeneity(epi_strata(c(10, 20, 5, 40), c(30, 15, 20, 25)))

Mantel-Haenszel odds ratio with worked derivation

Description

Pools stratum-specific odds ratios into a single adjusted estimate, showing the stratum weights explicitly and comparing the result against the crude estimate so that confounding is visible as arithmetic.

Usage

mh_odds_ratio(x, ..., conf_level = 0.95)

Arguments

Details

The confidence interval uses the Robins-Breslow-Greenland variance, which is valid both for a few large strata and for many small ones.

Value

An epibyhand_derivation.

References

Mantel, N. and Haenszel, W. (1959). Statistical aspects of the analysis of data from retrospective studies of disease. Journal of the National Cancer Institute, 22(4), 719-748. doi:10.1093/jnci/22.4.719

Robins, J., Breslow, N. and Greenland, S. (1986). Estimators of the Mantel-Haenszel variance consistent in both sparse data and large-strata limiting models. Biometrics, 42(2), 311-323.

Examples

s <- epi_strata(c(10, 20, 5, 40), c(30, 15, 20, 25),
                labels = c("Men", "Women"))
mh_odds_ratio(s)

Mantel-Haenszel risk ratio with worked derivation

Description

Mantel-Haenszel risk ratio with worked derivation

Usage

mh_risk_ratio(x, ..., conf_level = 0.95)

Arguments

Value

An epibyhand_derivation.

References

Greenland, S. and Robins, J. M. (1985). Estimation of a common effect parameter from sparse follow-up data. Biometrics, 41, 55-68.

Examples

mh_risk_ratio(epi_strata(c(10, 20, 5, 40), c(30, 15, 20, 25)))

Odds ratio with worked derivation

Description

Odds ratio with worked derivation

Usage

odds_ratio(x, ..., conf_level = 0.95)

Arguments

Value

An epibyhand_derivation.

References

Woolf, B. (1955). On estimating the relation between blood group and disease. Annals of Human Genetics, 19, 251-253.

Examples

odds_ratio(epi2x2(36, 14, 30, 25))

Print a 2 x 2 table with margins

Description

Print a 2 x 2 table with margins

Usage

## S3 method for class 'epi2x2'
print(x, indent = "", ...)

Arguments

Value

x, invisibly.

Print stratified tables

Description

Print stratified tables

Usage

## S3 method for class 'epi_strata'
print(x, indent = "", ...)

Arguments

Value

x, invisibly.

Print a worked derivation

Description

Print a worked derivation

Usage

## S3 method for class 'epibyhand_derivation'
print(x, verbose = NULL, digits = NULL, ...)

Arguments

Value

x, invisibly.

Risk difference with worked derivation

Description

Risk difference with worked derivation

Usage

risk_difference(x, ..., conf_level = 0.95)

Arguments

Value

An epibyhand_derivation.

Examples

risk_difference(epi2x2(36, 14, 30, 25))

Risk ratio with worked derivation

Description

Risk ratio with worked derivation

Usage

risk_ratio(x, ..., conf_level = 0.95)

Arguments

Value

An epibyhand_derivation.

Examples

risk_ratio(epi2x2(36, 14, 30, 25))

Return the steps of a derivation as a data frame

Description

Useful for building answer keys, or for rendering the derivation in a format this package does not provide.

Usage

steps_table(x)

Arguments

Value

A data frame with one row per step.