Empirical Type I Error at the Least-Favorable Null

Generates a boundary-null configuration and estimates its empirical rejection probability using simPower(). The comparator convention is c(test, reference). For normal ROM and count RR, a lower-bound null sets mean(test) / mean(reference) = L. For log-normal ROM, the boundary is imposed on the log-analysis scale used by the test; this coincides with the arithmetic mean ratio when the two arms have the same coefficient of variation.

type1Error(
  null = c("lower", "upper", "both"),
  x = NULL,
  comparator = NULL,
  endpoint = NULL,
  joint = FALSE,
  conf.level = 0.95,
  ...
)

Arguments

null: Boundary to evaluate: "lower", "upper", or "both".
x: Optional existing simss or simpower object. When supplied, its design and outcome parameters are reused; arguments in ... override stored settings such as n or nsim.
comparator: Optional comparator name identifying the boundary scenario when joint = FALSE. It must be one of the names in list_comparator; by default, the first comparator is used. It is ignored when joint = TRUE, because joint mode evaluates all comparators.
endpoint: Optional endpoint identifying the boundary component when joint = FALSE. It is available for the all-endpoints-required case (k equal to the number of endpoints), where one endpoint is placed on the boundary. For k smaller than the number of endpoints, use joint = TRUE so that all composite boundary configurations are evaluated.
joint: Logical. If TRUE, evaluate every comparator and every endpoint partial-null configuration and return the joint Type I-error result for each complete-trial decision. For a comparator with m endpoints and an at-least-k rule, all boundary counts from m - k + 1 through m are evaluated. Defaults to FALSE for backward compatibility.
conf.level: Confidence level for the simultaneous one-sided Monte Carlo upper bound across the evaluated joint scenarios. Defaults to 0.95.
...: Arguments passed to simPower(). The call must include the outcome parameters, comparator definitions, and equivalence margins.

Value

For null = "lower" or "upper", an object of class type1error containing the empirical Type I error in type1_error and its Monte Carlo interval. For null = "both", a named list containing the lower- and upper-bound results. With joint = TRUE, a type1error_joint object containing one joint result for every valid comparator, endpoint-subset, boundary-direction combination is returned.

Details

Comparators use the convention c(test, reference). For ROM, the tested estimand is test / reference; for DOM it is test - reference. With log-normal ROM, the test is performed after converting the supplied original-scale means and variances to the log-analysis scale, so the boundary scenario is calibrated on that scale. For count rate ratios, the analogous midpoint is sqrt(L * U) on the rate-ratio scale because the test is performed on the log-rate-ratio scale. Absolute rates and dispersion remain nuisance parameters, so this midpoint should be supplemented by a grid or optimization when a global supremum is required. If a comparator has m endpoints and requires k endpoints to pass, a composite null configuration has at least m - k + 1 non-equivalent endpoints. With joint = TRUE, all endpoint subsets with boundary counts from m - k + 1 through m, and all lower/upper direction combinations, are evaluated, while the complete decision still requires the k-of-m rule for every comparator in the same simulated trial. The returned joint object includes a Bonferroni simultaneous one-sided Monte Carlo upper bound for the maximum scenario probability.