Package {PICOTsize}

Adjust a raw sample size for expected dropout

Description

Studies with follow-up, non-response, or attrition need to enrol more participants than the raw formula suggests, so that enough complete observations remain at the end. This function applies the statistically correct inflation formula:

Usage

apply_dropout(n, dropout_rate = 0.2)

Arguments

Details

n* = n / (1 - dropout_rate)

Note: Bhardwaj et al. (2024), the primary reference for this package, states this same formula in the text, but their worked numeric examples actually use the simpler approximation n * (1 + dropout_rate), which gives a slightly smaller (less conservative) sample size. This package follows the formula as stated in the text, not the arithmetic in the worked examples. See the package Validation vignette for a side-by-side comparison.

Value

A single integer: the dropout-adjusted sample size, rounded up to the nearest whole participant.

Examples

apply_dropout(323, dropout_rate = 0.10)

Build the dynamic parameter form for a given study design

Description

Returns the input widgets appropriate to design_key. Field inputIds are shared across designs where the underlying meaning is analogous (e.g. calc_p1 is "prevalence" for a cross-sectional study but "outcome rate in controls" for a case-control study) – this keeps server.R simple, since it can always read from the same small set of inputIds regardless of which form is showing.

Usage

build_calculator_form(design_key)

Arguments

Value

A shiny tag list of input widgets.

Sample size for a case-control study

Description

Estimates the number of cases and controls needed to detect an association between an exposure and an outcome, following Bhardwaj et al. (2024) and using epiR::epi.sscc() as the validated computational backend.

Usage

calc_casecontrol(
  p_exposed_controls,
  p_exposed_cases,
  control_case_ratio = 1,
  power = 0.8,
  sig_level = 0.05,
  dropout_rate = 0.2
)

Arguments

Details

Bhardwaj et al. (2024) express the exposure/outcome association in terms of the proportion exposed among cases and among controls (p1 and p0). epiR's epi.sscc() instead takes an odds ratio (OR). This function converts p1/p0 to an OR internally, so the user can keep thinking in the same terms as the source paper.

Value

A list with n_raw (total, before dropout adjustment), n_final (total, after dropout adjustment), the derived odds ratio, and the inputs used.

Examples

# Reproduces the worked lymphoma example in Bhardwaj et al. (2024):
# 25\% exposed in controls, 40\% exposed in cases, equal groups,
# 80\% power, 10\% dropout
calc_casecontrol(p_exposed_controls = 0.25, p_exposed_cases = 0.40,
                  dropout_rate = 0.10)

Sample size for a cohort study

Description

Estimates the number of exposed and unexposed subjects needed to detect a difference in incidence between two groups, following Bhardwaj et al. (2024) and using epiR::epi.sscohortc() as the validated computational backend.

Usage

calc_cohort(
  incidence_unexposed,
  incidence_exposed,
  exposed_unexposed_ratio = 1,
  power = 0.8,
  sig_level = 0.05,
  dropout_rate = 0.2
)

Arguments

Value

A list with n_raw (total, before dropout adjustment), n_final (total, after dropout adjustment), and the inputs used.

Examples

# Reproduces the worked air pollution / asthma example in
# Bhardwaj et al. (2024): 20\% incidence unexposed, 30\% incidence
# exposed, equal groups, 80\% power, 10\% dropout
calc_cohort(incidence_unexposed = 0.20, incidence_exposed = 0.30,
            dropout_rate = 0.10)

Sample size for a cross-sectional study with a binary outcome

Description

Estimates the sample size needed to estimate a proportion or prevalence in a population, following Bhardwaj et al. (2024) and using epiR::epi.sssimpleestb() as the validated computational backend.

Usage

calc_crosssectional_binary(
  p,
  precision,
  error_type = "absolute",
  conf_level = 0.95,
  dropout_rate = 0.2
)

Arguments

Value

A list with the raw sample size (n_raw), the dropout-adjusted sample size (n_final), and the inputs used, so the result can be fed directly into report generation.

Examples

# Reproduces the worked example in Bhardwaj et al. (2024):
# prevalence 30\%, 5\% absolute precision, 95\% CI, 10\% dropout
calc_crosssectional_binary(p = 0.30, precision = 0.05,
                            dropout_rate = 0.10)

Sample size for a cross-sectional study with a continuous outcome

Description

Estimates the sample size needed to estimate a population mean, following Bhardwaj et al. (2024) and using epiR::epi.sssimpleestc() as the validated computational backend.

Usage

calc_crosssectional_continuous(
  mean,
  sd,
  precision,
  error_type = "absolute",
  conf_level = 0.95,
  dropout_rate = 0.2
)

Arguments

Value

A list with the same structure as [calc_crosssectional_binary()].

Examples

# Reproduces the worked SBP example in Bhardwaj et al. (2024):
# mean SBP unspecified in the paper's formula, SD = 3 mmHg,
# precision = 0.5 mmHg, 95\% CI, 10\% dropout
calc_crosssectional_continuous(mean = 120, sd = 3, precision = 0.5,
                                dropout_rate = 0.10)

Sample size to estimate the sensitivity and specificity of a diagnostic test

Description

Estimates the sample size needed to evaluate a diagnostic test's accuracy, using epiR::epi.ssdxsesp() as the validated computational backend. That function implements the method of Buderer (1996) and Hajian-Tilaki (2014), which calculates the required n for sensitivity and for specificity separately, then takes the LARGER of the two as the total study sample size – because the same group of subjects is used to estimate both simultaneously, not two separate samples.

Usage

calc_diagnostic_accuracy(
  expected_sensitivity,
  expected_specificity,
  prevalence,
  precision,
  error_type = "absolute",
  conf_level = 0.95,
  dropout_rate = 0
)

Arguments

Details

Note this differs from Bhardwaj et al. (2024), who calculate the two requirements separately and add them together. Summing effectively assumes two independent studies, which is not how diagnostic accuracy studies are actually run. This package follows the epiR/Buderer approach (the larger of the two), as the methodologically correct one. See the package Validation vignette for a side-by-side comparison.

Value

A list with n_sensitivity, n_specificity, n_raw (the larger of the two – the actual required enrolment), n_final (dropout-adjusted), and the inputs used.

Examples

# Reproduces the worked hypertension test example in
# Bhardwaj et al. (2024): sensitivity 80\%, specificity 90\%,
# prevalence 20\%, 5\% absolute margin of error
calc_diagnostic_accuracy(expected_sensitivity = 0.80,
                          expected_specificity = 0.90,
                          prevalence = 0.20, precision = 0.05)

Sample size for an equivalence trial (binary outcome)

Description

Estimates the sample size needed to demonstrate that two treatments are, for practical purposes, equally effective, using epiR::epi.ssequb() as the validated computational backend.

Usage

calc_trial_equivalence(
  p_standard,
  p_new,
  delta,
  power = 0.8,
  sig_level = 0.05,
  treat_control_ratio = 1,
  dropout_rate = 0.2
)

Arguments

Value

A list with n_raw, n_final, and the inputs used.

Examples

calc_trial_equivalence(p_standard = 0.45, p_new = 0.45,
                        delta = 0.10)

Sample size for a non-inferiority trial (binary outcome)

Description

Estimates the sample size needed to demonstrate that a new treatment is not unacceptably worse than a standard treatment, using epiR::epi.ssninfb() as the validated computational backend.

Usage

calc_trial_noninferiority(
  p_standard,
  p_new,
  delta,
  power = 0.8,
  sig_level = 0.05,
  treat_control_ratio = 1,
  dropout_rate = 0.2
)

Arguments

Value

A list with n_raw, n_final, and the inputs used.

Examples

calc_trial_noninferiority(p_standard = 0.45, p_new = 0.45,
                           delta = 0.10)

Sample size for a superiority trial (binary outcome)

Description

Estimates the sample size needed to demonstrate that a new treatment is better than a standard treatment, following Bhardwaj et al. (2024) and using epiR::epi.sssupb() as the validated computational backend.

Usage

calc_trial_superiority(
  p_standard,
  p_new,
  delta,
  power = 0.8,
  sig_level = 0.05,
  sided_test = 2,
  treat_control_ratio = 1,
  dropout_rate = 0.2
)

Arguments

Value

A list with n_raw, n_final, and the inputs used.

Examples

# Reproduces the worked cancer survival example in
# Bhardwaj et al. (2024) -- use sided_test = 1 to match their
# one-sided convention exactly
calc_trial_superiority(p_standard = 0.45, p_new = 0.61,
                        delta = 0.10, sided_test = 1)

Generate a Methods-section paragraph from a sample size result

Description

Takes the list returned by any of the calc_* functions in this package and produces a ready-to-use paragraph describing the sample size calculation, written in the style of a Methods section, following Bhardwaj et al. (2024)'s own reporting conventions.

Usage

generate_report_text(result)

Arguments

Value

A single character string containing the report paragraph.

Examples

result <- calc_crosssectional_binary(p = 0.30, precision = 0.05,
                                      dropout_rate = 0.10)
generate_report_text(result)

The PICOTsize bslib theme

Description

The PICOTsize bslib theme

Usage

picotsize_theme

Format

An object of class bs_theme_with_preset (inherits from bs_version_5, bs_theme, sass_bundle) of length 1.

The list of parameters that can be varied on the sensitivity plot, for a given design

Description

The list of parameters that can be varied on the sensitivity plot, for a given design

Usage

plot_parameter_choices(design_key)

Arguments

Value

A named character vector suitable for selectInput(choices = ...). Values are generic field names used internally by server.R (not the form's inputIds), so the plot can vary one field in isolation. Parameters available for the sensitivity plot, by design

Launch the PICOTsize Shiny app

Description

Launch the PICOTsize Shiny app

Usage

run_app()

Value

No return value. Launches the Shiny app in a browser or the RStudio Viewer pane.

Examples

if (interactive()){
run_app()
}

Main Shiny server function for PICOTsize

Description

Main Shiny server function for PICOTsize

Usage

server(input, output, session)

Arguments

The title footer

Description

The title footer

Usage

tile_footer()

The title header

Description

The title header

Usage

tile_header()

The ui

Description

The ui

Usage

ui()

UI for the Calculator tab

Description

This tab's parameter form changes depending on which study design was chosen in the Wizard tab, so most of it is built dynamically on the server side (see server.R and ui_calculator_forms.R). This function only lays out the static skeleton: a slot for the dynamic input form, a results card, an interactive plot, and the auto-generated report text.

Usage

ui_calculator()

Value

A shiny tag list, ready to be placed inside a nav_panel().

UI for the Validation tab

Description

A static comparison table showing this package's output against the worked numeric examples in Bhardwaj et al. (2024), along with a short explanation of every case where the two differ and why.

Usage

ui_validation()

Value

A shiny tag list, ready to be placed inside a nav_panel().

UI for the PICOT Wizard tab

Description

Builds the step-by-step questionnaire that walks the user through the PICOT framework and determines which study design (and therefore which calculator form) applies. This is a UI-building function, not a static object, so it can be called from ui.R.

Usage

ui_wizard()

Value

A shiny tag list, ready to be placed inside a nav_panel().

The static validation dataset used by the table above

Description

Kept as its own small function (rather than inline in server.R) so it can also be reused by tests, if needed later.

Usage

validation_dataset()

Value

A data.frame. Static validation comparsion data