Package 'precisely'

Launch precisely Shiny app

Description

launch_precisely_app() launches a Shiny app to calculate and plot precision, sample size, and upper limit calculations.

Usage

launch_precisely_app()

---

Calculate with precisely functions across values

Description

map_precisely() is a wrapper around tidyr::crossing() and purrr::pmap_dfr() to give a set of values to any of the calculation functions in precisely. All possible combinations of the values are passed to the function, returning a tibble where each row is the result for each combination.

Usage

map_precisely(.f, ...)

Arguments

.f	a function in precisely
...	arguments passed to .f. All possible combinations of argument values are given to the function.

Value

a tibble

Examples

map_precisely(
  n_risk_difference,
  precision = seq(from = .02, to = .20, by = .005),
  exposed = c(.2, .4),
  unexposed = c(.1, .3),
  group_ratio = 1
)

---

Estimate sample size based on precision of a measure

Description

These functions calculate the sample size needed to estimate a measure with a certain precision. For ratio measures, like the risk ratio, rate ratio, and odds ratio, this is the ratio of the upper to lower limit of the confidence interval. For difference measures, like the risk difference or rate difference, this is the absolute width of the confidence interval.

Usage

n_risk_difference(precision, exposed, unexposed, group_ratio, ci = 0.95)

n_risk_ratio(precision, exposed, unexposed, group_ratio, ci = 0.95)

n_rate_difference(precision, exposed, unexposed, group_ratio, ci = 0.95)

n_rate_ratio(precision, exposed, unexposed, group_ratio, ci = 0.95)

n_odds_ratio(
  precision,
  exposed_cases,
  exposed_controls,
  group_ratio,
  ci = 0.95
)

Arguments

precision	For differences, the width of the CI. For ratios, the ratio of the upper to lower CI.
exposed	The risk or rate among the exposed cohort.
unexposed	The risk or rate among the unexposed cohort.
group_ratio	In cohort studies, the ratio of the unexposed to the exposed. In case-control studies, the ratio of the controls to the cases.
ci	The confidence interval as a probability or percent. Default is .95.
exposed_cases	The proportion of exposed cases.
exposed_controls	The proportion of exposed controls.

Value

a tibble with sample size, effect measure, and precision

References

Rothman, K.J. and Greenland, S. 2018. Planning Study Size Based on Precision Rather Than Power. 29(5):599-603.

Examples

# From Rothman and Greenland 2018

n_risk_difference(
  precision = .08,
  exposed = .4,
  unexposed = .3,
  group_ratio = 3,
  ci = .90
)

n_risk_ratio(
  precision = 2,
  exposed = .4,
  unexposed = .3,
  group_ratio = 3
)

---

Plot precisely

Description

Simple line plots for the output of map_precisely(). Use dplyr::group_by() to create multiple lines on the plot.

Usage

plot_sample_size(.df, xlab = "Sample Size", ylab = "Precision", line_size = 1)

plot_precision(.df, xlab = "Precision", ylab = "Sample Size", line_size = 1)

plot_upper_limit(
  .df,
  xlab = "Sample Size",
  ylab = "Upper Limit",
  line_size = 1
)

Arguments

.df	a data frame with values to plot, possibly from map_precisely().
xlab	Label for the x-axis.
ylab	Label for the y-axis.
line_size	The width of the line. Default is 1.

Value

a ggplot

Examples

library(dplyr)
library(ggplot2)

map_precisely(
  n_risk_difference,
  precision = seq(from = .02, to = .20, by = .005),
  exposed = .4,
  unexposed = .3,
  group_ratio = 1
 ) %>%
  plot_sample_size()

map_precisely(
  precision_odds_ratio,
  n_cases = seq(from = 500, to = 1000, by = 10),
  exposed_cases = .6,
  exposed_controls = .4,
  group_ratio = 1:4
) %>%
  group_by("Control/Case Ratio" = factor(group_ratio)) %>%
  plot_precision()

map_precisely(
  upper_rate_ratio,
  upper_limit = seq(1.5, 2.5, by = .1),
  prob = seq(.50, .95, by = .05),
  exposed = .01,
  unexposed = .01,
  group_ratio = 1:4
 ) %>%
  group_by("Probability" = factor(prob)) %>%
  plot_upper_limit(line_size = 1) +
    scale_color_viridis_d() +
    theme_precisely() +
    theme(legend.position = "right",
          strip.text = element_text(margin = margin(b = 5), hjust = 0)) +
    facet_wrap(~ group_ratio,
               labeller = as_labeller(function(x) paste("Unexposed/Exposed:", x)))

---

Estimate precision of a measure based on sample size

Description

These functions calculate the precision of an estimate given a certain sample size. For ratio measures, like the risk ratio, rate ratio, and odds ratio, this is the ratio of the upper to lower limit of the confidence interval. For difference measures, like the risk difference or rate difference, this is the absolute width of the confidence interval.

Usage

precision_risk_difference(
  n_exposed,
  exposed,
  unexposed,
  group_ratio,
  ci = 0.95
)

precision_risk_ratio(n_exposed, exposed, unexposed, group_ratio, ci = 0.95)

precision_rate_difference(
  n_exposed,
  exposed,
  unexposed,
  group_ratio,
  ci = 0.95
)

precision_rate_ratio(n_exposed, exposed, unexposed, group_ratio, ci = 0.95)

precision_odds_ratio(
  n_cases,
  exposed_cases,
  exposed_controls,
  group_ratio,
  ci = 0.95
)

Arguments

n_exposed, n_cases	In cohort studies, the number of exposed participants. In case-control studies, the number of cases.
exposed	The risk or rate among the exposed cohort.
unexposed	The risk or rate among the unexposed cohort.
group_ratio	In cohort studies, the ratio of the unexposed to the exposed. In case-control studies, the ratio of the controls to the cases.
ci	The confidence interval as a probability or percent. Default is .95.
exposed_cases	The proportion of exposed cases.
exposed_controls	The proportion of exposed controls.

Value

a tibble with precision, effect measure, and sample size

References

Rothman, K.J. and Greenland, S. 2018. Planning Study Size Based on Precision Rather Than Power. 29(5):599-603.

Examples

# From Rothman and Greenland 2018

precision_odds_ratio(
  n_cases = 500,
  exposed_cases = .6,
  exposed_controls = .4,
  group_ratio = 2
)

---

Minimalist themes for precision plots

Description

Minimalist themes for precision plots

Usage

theme_precisely(base_size = 14, base_family = "", ...)

Arguments

base_size	base font size, given in pts.
base_family	base font family
...	additional arguments passed to ggplot2::theme()

---

Estimate sample size based on probability that upper limit is below level of concern.

Description

These functions calculate sample size based on probability that upper limit is below level of concern. The idea behind this approach is to use precision to provide support for the absence of effect. These functions calculate sample size where, when the true effect is null, the upper limit of the confidence interval of the estimate of interest has a probability of being at or under a specified level of concern.

Usage

upper_risk_difference(
  upper_limit,
  prob,
  exposed,
  unexposed,
  group_ratio,
  ci = 0.95
)

upper_risk_ratio(upper_limit, prob, exposed, unexposed, group_ratio, ci = 0.95)

upper_rate_difference(
  upper_limit,
  prob,
  exposed,
  unexposed,
  group_ratio,
  ci = 0.95
)

upper_rate_ratio(upper_limit, prob, exposed, unexposed, group_ratio, ci = 0.95)

upper_odds_ratio(
  upper_limit,
  prob,
  exposed_cases,
  exposed_controls,
  group_ratio,
  ci = 0.95
)

Arguments

upper_limit	The upper limit of the confidence interval, a level of concern.
prob	The probability of the estimated upper limit of the confidence interval being at or below the level of concern.
exposed	The risk or rate among the exposed cohort.
unexposed	The risk or rate among the unexposed cohort.
group_ratio	In cohort studies, the ratio of the unexposed to the exposed. In case-control studies, the ratio of the controls to the cases.
ci	The confidence interval as a probability or percent. Default is .95.
exposed_cases	The proportion of exposed cases.
exposed_controls	The proportion of exposed controls.

Value

a tibble with sample size, effect measure, upper limit, and probability

References

Rothman, K.J. and Greenland, S. 2018. Planning Study Size Based on Precision Rather Than Power. 29(5):599-603.

Examples

# From Rothman and Greenland 2018

upper_rate_ratio(
  upper_limit = 2,
  prob = .90,
  exposed = .01,
  unexposed = .01,
  group_ratio = 1
)

---