alphaN_report: Write a settings report for a calibrated alpha level

In alphaN: Set Alpha Based on Sample Size Using Bayes Factors

Write a settings report for a calibrated alpha level

Description

Generates a short, human-readable Markdown report that records every input behind a calibrated alpha level together with the result: the sample size, the evidence target, the calibration method and its prior settings, the resulting alpha, and the decision rule. The report is designed to be attached to a preregistration protocol or a supplementary appendix, so that an alpha level chosen before data collection leaves a citable trace. It mirrors the downloadable report of the package's companion Shiny application.

Usage

alphaN_report(
  n,
  BF = 1,
  method = "JAB",
  upper = 1,
  de = 0.5,
  nu = NULL,
  r = NULL,
  q = 1,
  p = 0,
  file = NULL,
  width = 72,
  power_at = NULL
)

Arguments

n	Sample size. A single positive number (one report describes one design).
BF	Target Bayes factor. A single positive number.
method	Which Bayes factor to calibrate alpha to. The first four options invert Jeffreys' approximate Bayes factor and differ in the choice of the prior fraction 'b'; the last two invert the exact test-statistic Bayes factors of Klauer et al. (2025), whose priors center the alternative hypothesis on a prespecified effect size de. One of: "JAB": this choice of b produces Jeffreys' approximate BF (Wagenmakers, 2022) "min": uses the minimal training sample for the prior (Gu et al., 2018) "robust": a robust version of "min" that prevents too small b (O'Hagan, 1995) "balanced": this choice of b balances the type I and type II errors (Gu et al., 2016) "ES": calibrates alpha to the effect-size Bayes factor (Klauer et al., 2025) "moment": calibrates alpha to the moment Bayes factor (Klauer et al., 2025), under which effects close to zero are a priori implausible
upper	The upper limit for the range of realistic effect sizes. Only relevant when method="balanced". Defaults to 1 such that the range of realistic effect sizes is uniformly distributed between 0 and 1, U(0,1). Conceptually, upper plays for the "balanced" method the role that de plays for "ES" and "moment": both declare which effect sizes the researcher deems realistic. upper treats them as a uniform band whose Type I and Type II error rates are then balanced, whereas de singles out a focal effect size on which the prior concentrates.
de	The prespecified (targeted) effect size in standardized units: Cohen's d for q = 1 and Cohen's f for joint tests (the scales coincide at q = 1). Only used by methods "ES" and "moment". Defaults to 0.5, a medium effect; use 0.2 for small and 0.8 for large effects (Cohen, 1988).
nu	Degrees of freedom of the prior t distribution for methods "ES" and "moment". The default, NULL, uses the values recommended by Klauer et al. (2025): 3 for "ES" and 5 + (q - 1) for "moment".
r	Scale of the two prior mixture components for method "ES". The default, NULL, uses the recommendation of Klauer et al. (2025), r = sqrt((nu - 2)/(nu * q)) * de, which requires nu > 2 and de > 0; otherwise supply r explicitly.
q	Number of coefficients tested jointly. Only used by methods "ES" and "moment". The default, 1, is the test of a single coefficient; for q > 1 the alpha level is set for the F test of the joint null that all q coefficients are zero.
p	Number of parameters retained in the model under the null, including any intercept. Only used by methods "ES" and "moment". The effective sample size of Klauer et al. (2025) is n - p; the default, 0, reproduces the one-sample form, which treats the sample size as effective. For a regression coefficient in a small sample, setting p to the number of other estimated coefficients (including the intercept) gives the residual-degrees-of-freedom behavior of the exact regression case.
file	Optional path. If supplied, the report is also written to this file.
width	Maximum line width of the report; longer lines are wrapped with a hanging indent. Defaults to 72 characters.
power_at	Optional numeric vector of standardized effect sizes. If supplied, the report includes the power of the calibrated test against each of them (computed with alphaN_power()), so the preregistered alpha is documented together with what it costs.

Value

The report as a character vector of lines, invisibly. The report is printed to the console.

See Also

alphaN(), alphaN_power()

Examples

alphaN_report(n = 1000, BF = 3, method = "JAB")

# Effect-size calibration with a power section, written to a file
f <- tempfile(fileext = ".md")
alphaN_report(n = 1000, BF = 3, method = "ES", de = 0.5,
              power_at = c(0.1, 0.2, 0.5), file = f)

alphaN documentation built on July 27, 2026, 5:08 p.m.