Exact conditional Poisson regression (multivariate-shift algorithm)
Source:R/ep-multivariate-shift.R
ep_multi_shift.RdExact conditional inference for one or more categorical effects in a
Poisson regression with a log link, an optional offset, and optional
stratification. Nuisance parameters (stratum intercepts and every model
effect not listed in exact_vars) are eliminated by conditioning on
their sufficient statistics, and the resulting exact conditional
distribution of each requested effect's sufficient statistic is
obtained by the multivariate-shift algorithm: a per-stratum dynamic
program combined with explicit cross-stratum convolution, generalizing
the multivariate shift algorithm of Hirji, Mehta, and Patel (1987) for
exact logistic regression to bounded Poisson counts, following the
EXACTMAX/OFFSET rules documented for SAS PROC GENMOD's EXACT
statement.
Arguments
- formula
A model formula.
- data
A data frame.
- exact_vars
Character vector of model terms to compute exact results for. Each entry must name a term that appears in
formula, exactly as SAS'sEXACTstatement requires. An entry can be a main effect ("region") or an interaction of any order, named by joining every variable in it with*or:("region:gender"and"region*gender"both work, and the variables may be listed in either order). Interaction columns are matched via the model's ownterms()/assignstructure, not by name-guessing, so a term is never confused with a different term that happens to share a text prefix (e.g. requesting"region"in a model that also containsregion:genderselects only region's own main-effect columns). Requesting a term does not automatically request any other term built from the same variable(s): a main effect and its interactions are entirely independent entries, so testingregionwhile leavingregion:genderuntested keeps the interaction as an ordinary nuisance covariate (conditioned on undercondition_on = "model", never tested); to test the interaction itself, add it as its own entry, e.g.exact_vars = c("region", "region:gender").- offset
Name of an offset variable in
data, orNULL(default). IfNULL, every observation is treated as contributing one unit of exposure (offset = 0 on the log scale).- offset_log
If
TRUE(default),offsetalready holds log(exposure); ifFALSE, it holds raw exposure.- exactmax
NULL(not specified),TRUE(specified without a variable), or a character variable name (SASEXACTMAX=).- strata
Optional character vector of stratification variable names in
data.- ref_levels
Optional named list of reference levels for categorical variables.
- alpha
Significance level for confidence intervals.
- ci_type
"two-sided"(default) or"one-sided", matchingep_closed_form()'s argument of the same name. For"one-sided", only the confidence limit on the informative side is computed for each parameter (the other is left at its boundary,-InforInf); which side is informative is determined per parameter from the two one-sided tail probabilities at the null (seetwo_sided_from_tails()'sdirection), exactly as inep_closed_form().- chunk_size
Maximum number of rows processed at once while combining two strata's coefficient tables. Combining strata requires pairing every row of one stratum's table with every row of the other's;
chunk_sizebounds how many such pairs are materialized simultaneously, trading memory for speed. The default is generous for typical problems; lower it if combining strata runs out of memory, or raise it if memory is plentiful and speed matters more.- condition_on
"model"(default; condition on every other model effect, matching SAS) or"exact"(condition only on the other requestedexact_vars).- verbose
If
TRUE(default), prints progress and which SAS rule determined the per-observation caps.
Value
An object of class c("ep_multi_shift", "ep_fit"): a list with
elements exactparmest (a one-row data frame with Parameter,
Estimate (the coefficient beta = log rate ratio, not the rate
ratio), StdError, Alpha, LowerCL, UpperCL (beta scale),
PValue, and SuffStat), OUTDIST (the exact distribution of the
sufficient statistic), and call.
Details
formula may contain interaction terms (a*b, a:b, or higher-order
interactions) freely, in two distinct roles. An interaction can be a
plain adjustment covariate, left out of exact_vars entirely, in
which case it is conditioned on like any other nuisance term (under
the default condition_on = "model") but never itself tested. Or an
interaction can be the effect of interest, including an interaction
of the effect of interest with another covariate, by listing it as
its own entry in exact_vars; see that argument's documentation for
the exact naming rules. The two roles are independent: listing a main
effect in exact_vars never implicitly tests its interactions, and
listing an interaction never implicitly tests the main effects it is
built from, each term to be tested must be named explicitly.
References
Hirji KF, Mehta CR, Patel NR. Computing Distributions for Exact Logistic Regression. JASA, 82(400):1110-1117, 1987.
Mehta CR, Patel NR. Exact logistic regression: theory and examples. Statistics in Medicine, 14(19):2143-2160, 1995.
Examples
df <- data.frame(
group = c(1L, 1L, 1L, 0L, 0L, 0L),
age = c(50L, 60L, 70L, 50L, 60L, 70L),
subjects = c(3492, 2141, 1711, 3525, 2166, 1724),
cases = c(3, 2, 1, 10, 7, 5),
futime = c(50, 60, 40, 51, 62, 42)
)
df$lnfutime <- log(df$futime)
ep_multi_shift(
formula = cases ~ group,
data = df,
offset = "lnfutime",
offset_log = TRUE,
strata = "age",
exact_vars = "group",
ref_levels = list(group="0", age="50"),
alpha = 0.05,
verbose = TRUE,
ci_type = "two-sided"
)
#>
#> SAS rule (3): OFFSET specified and EXACTMAX not specified =>
#> S_i = max(ceil(exp(o_i)),1).
#>
#> === EXACT for parameter column: group1 ===
#> stratum 50: n=2, M=13
#> stratum 60: n=2, M=9
#> stratum 70: n=2, M=6
#> after combining 2/3 strata: joint rows = 16
#> after combining 3/3 strata: joint rows = 29
#>
#> Exact conditional Poisson (categorical + STRATA; multivariate-shift algorithm)
#> ------------------------------------------------------------------------------
#> Parameter Estimate StdError Alpha LowerCL UpperCL PValue SuffStat
#> group1 -1.26913 0.4605711 0.05 -2.372642 -0.335739 0.004763324 6