Nothing
# Internal implementation functions for mfpi()
#
# None of these functions are exported. They are called exclusively by
# mfpi.default() after all argument checking and pre-processing has been
# completed. Parameters therefore arrive already validated, expanded to full
# length, shifted, and scaled.
# -----------------------------------------------------------------------------
# Adjustment-power extraction -------------------------------------------------
# -----------------------------------------------------------------------------
#' Extract Canonical Powers for Selected MFPI Adjustment Terms
#'
#' Uses the fitted adjustment model's `fp_powers` list as the primary source of
#' selected powers. Unlike the display-oriented `fp_terms` table, this list
#' preserves structural `NA` positions required by ACD terms. For example, an
#' ACD-only linear term is represented as `c(NA, 1)`, where the first slot is
#' the inactive transformation of x and the second slot is the active
#' transformation of A(x).
#'
#' @param adjustment_model Fitted `mfp2` adjustment-model object.
#' @param selected_vars Character vector of selected conceptual adjustment
#' terms.
#'
#' @return A named list of numeric power vectors aligned to `selected_vars`.
#'
#' @keywords internal
#' @noRd
mfpi_extract_adjustment_powers <- function(adjustment_model, selected_vars) {
if (length(selected_vars) == 0L) {
return(stats::setNames(vector("list", 0L), character(0L)))
}
canonical <- adjustment_model$fp_powers
if (!is.null(canonical)) {
if (is.null(names(canonical))) {
stop(
"Internal error: adjustment-model `fp_powers` must be named.",
call. = FALSE
)
}
missing_vars <- setdiff(selected_vars, names(canonical))
if (length(missing_vars) > 0L) {
stop(
paste0(
"Internal error: adjustment-model powers are missing selected term(s): ",
paste(missing_vars, collapse = ", "),
"."
),
call. = FALSE
)
}
powers <- canonical[selected_vars]
} else if (!is.null(adjustment_model$fp_terms)) {
# Compatibility fallback for older fitted objects. This is adequate for
# ordinary FP terms, but display tables may not preserve inactive ACD power
# slots; the ACD validation below therefore remains mandatory.
powers <- get_fp_powers(selected_vars, adjustment_model$fp_terms)
} else {
stop(
paste0(
"Internal error: the adjustment model has neither `fp_powers` nor ",
"`fp_terms` metadata."
),
call. = FALSE
)
}
powers <- lapply(powers, function(p) {
if (is.null(p)) numeric(0L) else unname(as.numeric(p))
})
names(powers) <- selected_vars
missing_power_values <- selected_vars[
vapply(powers, length, integer(1L)) == 0L
]
if (length(missing_power_values) > 0L) {
stop(
paste0(
"Internal error: selected adjustment term(s) have no stored powers: ",
paste(missing_power_values, collapse = ", "),
"."
),
call. = FALSE
)
}
acd_flags <- adjustment_model$acd
acd_selected <- selected_vars[
vapply(selected_vars, function(v) {
!is.null(acd_flags) &&
!is.null(names(acd_flags)) &&
v %in% names(acd_flags) &&
isTRUE(acd_flags[[v]])
}, logical(1L))
]
invalid_acd <- acd_selected[
vapply(powers[acd_selected], length, integer(1L)) != 2L
]
if (length(invalid_acd) > 0L) {
stop(
paste0(
"Internal error: selected ACD adjustment term(s) must retain two ",
"power positions (for x and A(x)): ",
paste(invalid_acd, collapse = ", "),
"."
),
call. = FALSE
)
}
powers
}
# -----------------------------------------------------------------------------
# fit_mfpi() ------------------------------------------------------------------
# -----------------------------------------------------------------------------
#' Fit MFPI Adjustment and Interaction Models
#'
#' Selects an adjustment model and evaluates each specified interaction with
#' the grouping variable separately. Uses inputs prepared by \code{mfpi()}.
#'
#' The selected adjustment terms and transformations are reused in each
#' interaction analysis, excluding the variable being tested. Each interaction
#' uses its resolved functional form; the function does not select between
#' linear, FP1, and FP2 forms.
#'
#' @param x Numeric predictor matrix, including \code{group_var}, with shifts
#' and scales already applied and no intercept column.
#' @param y Response vector, response matrix, or \code{survival::Surv()} object.
#' @param family Resolved model-family specification.
#' @param family_string Character string giving the canonical family name.
#' @param weights Numeric vector of observation weights.
#' @param offset Linear-predictor offsets: a numeric vector or, for multinomial
#' models, a matrix with one column per non-reference outcome category.
#' @param has_offset Logical indicating whether an offset was supplied.
#' @param cycles Maximum number of MFP backfitting cycles.
#' @param center Named logical vector controlling predictor centring.
#' @param criterion Selection criterion: \code{"pvalue"}, \code{"aic"}, or
#' \code{"bic"}. Used for adjustment selection and interaction comparisons.
#' @param select Named numeric vector of significance levels for adjustment
#' variable selection under \code{criterion = "pvalue"}.
#' @param alpha Named numeric vector of significance levels for adjustment
#' FP degree selection under \code{criterion = "pvalue"}.
#' @param keep Character vector naming adjustment terms or columns to retain.
#' Naming a column of a categorical term retains the complete term.
#' @param force_max_fp Named logical vector identifying adjustment variables
#' whose maximum permitted FP degree must be retained. Powers are still
#' selected within that degree.
#' @param df Named integer vector of adjustment degrees of freedom, after
#' restrictions based on the number of distinct values.
#' @param xorder Order of adjustment terms during MFP backfitting:
#' \code{"ascending"}, \code{"descending"}, or \code{"original"}.
#' @param fp_powers Named list of candidate FP powers for each predictor.
#' @param ties Method for handling tied event times in Cox models.
#' @param strata Optional prepared survival-model stratification information.
#' @param nocenter Numeric values excluded from automatic centring by
#' \code{survival::coxph()}.
#' @param acd_vars Named logical vector identifying predictors to receive an
#' approximate cumulative distribution transformation.
#' @param zero_vars Named logical vector identifying predictors whose exact
#' zeros are handled separately during transformation.
#' @param catzero_vars Named logical vector identifying predictors requiring
#' a zero indicator alongside their transformed positive values.
#' @param spike_vars Named logical vector identifying predictors eligible for
#' spike-at-zero modelling.
#' @param min_saz_prop Minimum proportion required in both the zero and
#' positive components of a spike-at-zero adjustment variable.
#' @param use_ftest Whether to use F-tests instead of likelihood-ratio
#' chi-square tests for Gaussian p-value comparisons in both fitting stages.
#' Ignored for other families.
#' @param control List of model-fitting control parameters.
#' @param group_var Character string naming the grouping variable.
#' @param include_group_var Whether to include group main effects during
#' adjustment-model selection.
#' @param flex Interaction procedure: \code{"flex1"}, \code{"flex2"},
#' \code{"flex3"}, or \code{"flex4"}.
#' @param interaction_vars Character vector naming terms to test for
#' interaction with \code{group_var}.
#' @param interaction_forms Named character vector of resolved interaction
#' forms: \code{"linear"}, \code{"fp1"}, or \code{"fp2"}.
#' @param interaction_specs Named list describing each interaction term's
#' type and predictor columns.
#' @param p_interact Significance threshold for retaining interactions under
#' \code{criterion = "pvalue"}.
#' @param min_improvement Minimum AIC or BIC improvement required to retain
#' an interaction.
#' @param show_models Whether to print coefficient tables for selected
#' interaction models when \code{verbose = TRUE}.
#' @param verbose Whether to print progress messages.
#' @param digits Number of decimal places for printed numerical results.
#' @param scale Named numeric vector of predictor scale factors.
#' @param shift Named numeric vector of predictor shifts.
#' @param quiet Internal verbosity flag, reset according to \code{verbose}.
#' @param center_type Centring method for interaction transformations:
#' \code{"grand"} or \code{"group"}.
#' @param p_adjust_method Method passed to \code{stats::p.adjust()} for
#' interaction p-values under \code{criterion = "pvalue"}.
#' @param group_input_levels Numeric group values in the input matrix.
#' @param group_levels_original Original labels corresponding to
#' \code{group_input_levels}.
#' @param term_to_columns Named list mapping adjustment terms to predictor
#' columns. Categorical terms are selected jointly.
#' @param fitter Model-fitting backend.
#'
#' @return A list containing:
#' \describe{
#' \item{\code{best_model_metrics}, \code{all_model_metrics}}{Data frames
#' of comparison metrics for selected and evaluated interactions,
#' respectively.}
#' \item{\code{best_interaction_model},
#' \code{all_interaction_models}}{Named lists of fitted models for selected
#' and evaluated interactions, respectively.}
#' \item{\code{center_vals_list}}{Centring constants for selected interactions.}
#' \item{\code{adjustment_model}, \code{adjust_terms}}{The adjustment-model
#' results and its selected-term table.}
#' \item{\code{adjustment_term_to_columns}}{Mapping of adjustment terms to
#' predictor columns.}
#' \item{\code{var_winners}, \code{univariable_interactions}}{Per-variable
#' results and the complete interaction-analysis results.}
#' \item{\code{x_train_internal}}{Prepared training predictors, including
#' shifted and scaled values and recoded groups.}
#' }
#' The list also contains the family, fitting settings, group labels and
#' mappings, interaction specifications, and transformation information.
#'
#' @seealso \code{mfpi()}
#'
#' @keywords internal
#' @noRd
fit_mfpi <- function(x, y, family, family_string, weights, offset, cycles,
center, criterion, select, alpha, keep,
force_max_fp,
df, xorder,
fp_powers, ties, strata, nocenter, acd_vars, zero_vars,
catzero_vars, spike_vars, min_saz_prop, use_ftest,
control, group_var, include_group_var, flex, interaction_vars,
interaction_forms, interaction_specs,
p_interact, min_improvement, show_models, verbose,
digits, scale, shift = NULL, quiet = FALSE, has_offset,
shift_automatic = NULL,
center_type = c("grand", "group"),
p_adjust_method = "none",
group_input_levels = NULL,
group_levels_original = NULL,
term_to_columns,
fitter = "base") {
center_type <- match.arg(center_type)
quiet <- !isTRUE(verbose)
# Resolve the likelihood-GLM or survival family once for all repeated
# internal model fits. Prepared survival specifications retain their cached
# response representation throughout both MFPI stages.
family_fit <- resolve_fit_model_family(family)
# ---------------------------------------------------------------------------
# Pre-processing: synchronise parameter vectors and remap group levels
# ---------------------------------------------------------------------------
processed_data <- preprocess_data(
x = x,
group_var = group_var,
include_group_var = include_group_var,
select = select,
alpha = alpha,
df = df,
center = center,
acd_vars = acd_vars,
fp_powers = fp_powers,
zero_vars = zero_vars,
catzero_vars = catzero_vars,
spike_vars = spike_vars,
keep = keep,
force_max_fp = force_max_fp,
group_input_levels = group_input_levels,
group_levels_original = group_levels_original,
term_to_columns = term_to_columns
)
# ---------------------------------------------------------------------------
# Step 1: Fit adjustment model via MFP
# ---------------------------------------------------------------------------
if (verbose) {
rule_thick <- strrep("=", 70)
rule_thin <- strrep("-", 70)
mfp2_message("")
mfp2_message(rule_thick)
mfp2_message(" STEP 1: Selected Adjustment Model (MFP)")
mfp2_message(rule_thick)
}
adjustment_model <- fit_adjustment_model(
x = processed_data$x,
y = y,
weights = weights,
offset = offset,
cycles = cycles,
family = family_fit,
family_string = family_string,
fitter = fitter,
criterion = criterion,
updated_params = processed_data$updated_params,
xorder = xorder,
ties = ties,
strata = strata,
nocenter = nocenter,
min_saz_prop = min_saz_prop,
use_ftest = use_ftest,
control = control,
force_max_fp = processed_data$updated_params$force_max_fp,
scale = scale,
has_offset = has_offset,
term_to_columns = processed_data$term_to_columns,
verbose = FALSE
)
# `mfpi.default()` applies the covariate-wide shifts before `fit_mfpi()` is
# called. Consequently, `fit_adjustment_model()` must pass shift = 0 to
# `fit_mfp()` so that those shifts are not applied a second time during Stage 1.
# The zero values stored by `fit_mfp()`, however, describe only that internal
# fitting step. The returned adjustment model is an ordinary `mfp2` object and
# must describe preprocessing relative to raw covariate values, because
# `print.mfp2()` reports `transformations` and `predict.mfp2(newdata = ...)`
# uses the stored shifts to transform raw new data. Restore the actual MFPI
# shifts now that fitting is complete. This does not alter fitted coefficients
# or the training design; it only makes the returned model metadata consistent
# with the shifted, unscaled scale on which its final FP terms were fitted.
adjustment_model <- restore_mfpi_adjustment_shifts(
adjustment_model = adjustment_model,
shift = shift,
term_to_columns = processed_data$term_to_columns
)
if (!identical(family_string, "negbin")) {
# fit_mfpi() calls fit_mfp() directly rather than through mfp2.default(),
# so attach the same public, unprepared family metadata that a standalone
# mfp2 fit receives. This keeps summary/prediction on the nested adjustment
# model complete for survreg families.
adjustment_model$family <- mfp2_strip_prepared_family(family_fit)
}
# fit_mfpi() calls fit_mfp() below the public mfp2.default() boundary, so
# mirror the observation-level offset metadata that mfp2.default() normally
# adds.
adjustment_model$offset <- offset
adjustment_model$has_offset <- has_offset
# Identify variables retained by the adjustment model
selected_vars <- get_selected_variables(adjustment_model)
if (include_group_var) {
# Group dummies form one conceptual term named by group_var. Exclude that
# term from the ordinary adjustment set used in interaction models.
selected_vars <- setdiff(
selected_vars,
c(group_var, processed_data$dummy_names)
)
}
if (verbose) {
adjustment_info <- mfpi_prepare_adjustment_display(
list(
criterion = criterion,
p_interact = p_interact,
min_improvement = min_improvement,
p_adjust_method = p_adjust_method,
adjust_terms = adjustment_model$fp_terms
),
digits = digits
)
mfp2_message("")
mfp2_message(
" Model: ",
mfpi_print_model_label(list(
family_string = family_string,
family = mfp2_strip_prepared_family(family_fit)
))
)
mfp2_message(" Criterion: ", adjustment_info$settings$criterion_label)
mfp2_message("")
if (!is.null(adjustment_info$display) &&
nrow(adjustment_info$display) > 0L) {
mfp2_message_capture(print(adjustment_info$display))
mfp2_message("")
mfp2_message(
" Selected adjustment variables (",
length(adjustment_info$selected_names),
"): ",
paste(adjustment_info$selected_names, collapse = ", ")
)
} else {
mfp2_message(" No adjustment variables selected.")
}
}
# Use the adjustment model's canonical power metadata. In particular,
# ACD terms must retain both structural power positions (x and A(x)); the
# display-oriented fp_terms table can collapse an inactive NA slot and is
# therefore not a safe source for rebuilding the adjustment design matrix.
adj_fp_powers <- mfpi_extract_adjustment_powers(
adjustment_model = adjustment_model,
selected_vars = selected_vars
)
# Extract spike decisions from the adjustment model for use when
# re-transforming adjustment variables inside evaluate_interactions().
# spike_decision is a named numeric vector (1 = FP+binary, 2 = FP only,
# 3 = binary only) stored in the mfp2 object by fit_mfp().
adj_spike_decision <- if (!is.null(adjustment_model$spike_dec)) {
adjustment_model$spike_dec
} else {
setNames(rep(2L, length(selected_vars)), selected_vars)
}
adj_spike_decision <- adj_spike_decision[selected_vars]
# Developer note:
# fit_mfp() may reset zero/catzero/spike flags during adjustment-model fitting,
# especially through the spike-at-zero eligibility checks. When the selected
# adjustment variables are re-transformed inside evaluate_interactions(), we
# must use these final post-fit flags, not the original pre-fit flags from
# processed_data$updated_params.
adj_zero <- mfpi_extract_adjustment_flag(
adjustment_model,
"zero",
selected_vars,
default = FALSE
)
adj_catzero <- mfpi_extract_adjustment_flag(
adjustment_model,
"catzero",
selected_vars,
default = FALSE
)
adj_spike <- mfpi_extract_adjustment_flag(
adjustment_model,
"spike",
selected_vars,
default = FALSE
)
# ---------------------------------------------------------------------------
# Step 2: Evaluate univariable interactions
# ---------------------------------------------------------------------------
if (verbose) {
rule_thick <- strrep("=", 70)
interaction_settings <- mfpi_interaction_settings(
criterion = criterion,
p_interact = p_interact,
min_improvement = min_improvement,
p_adjust_method = p_adjust_method,
digits = digits
)
mfp2_message("")
mfp2_message(rule_thick)
mfp2_message(
sprintf(
" STEP 2: Evaluating Interactions (flex = %s)",
flex
)
)
mfp2_message(rule_thick)
mfp2_message("")
mfp2_message(" Group variable: ", group_var)
mfp2_message(" Selection rule: ", interaction_settings$selection)
if (criterion == "pvalue") {
mfp2_message(
" P-value adjustment: ",
interaction_settings$p_adjust_method
)
}
}
univ_results <- evaluate_interactions(
y = y,
processed_data = processed_data,
selected_vars = selected_vars,
adj_fp_powers = adj_fp_powers,
adj_zero = adj_zero,
adj_catzero = adj_catzero,
adj_spike = adj_spike,
adj_spike_decision = adj_spike_decision,
interaction_vars = interaction_vars,
interaction_forms = interaction_forms,
interaction_specs = interaction_specs,
flex = flex,
weights = weights,
offset = offset,
has_offset = has_offset,
xorder = xorder,
ties = ties,
strata = strata,
use_ftest = use_ftest,
control = control,
nocenter = nocenter,
family = family_fit,
family_string = family_string,
fitter = fitter,
fp_powers = fp_powers,
cycles = cycles,
criterion = criterion,
group_var = group_var,
show_models = show_models,
p_interact = p_interact,
min_improvement = min_improvement,
min_saz_prop = min_saz_prop,
center_type = center_type,
scale = scale,
shift = shift,
shift_automatic = shift_automatic,
adj_acd_parameter = adjustment_model$acd_parameter,
quiet = quiet,
p_adjust_method = p_adjust_method,
digits = digits,
verbose = verbose
)
# Prepared family data are a fitting cache, not public model metadata. Strip
# that cache before storing the full Stage-2 result.
univ_results$family <- mfp2_strip_prepared_family(univ_results$family)
n_selected <- nrow(univ_results$best_model_metrics)
if (verbose) {
mfp2_message(
"Done: ",
n_selected,
" of ",
length(interaction_vars),
" interactions selected."
)
mfp2_message("")
}
# Every proportional-hazards interaction candidate is fitted on the same
# working rows with the same training offset as the final adjustment model.
# fit_mfp() has already calculated predict.coxph()'s offset origin once, so
# expose that scalar at the top level rather than recomputing it per term.
cox_offset_reference <- if (identical(family_string, "cox")) {
adjustment_model$cox_offset_reference
} else {
NULL
}
list(
best_model_metrics = univ_results$best_model_metrics,
all_model_metrics = univ_results$all_model_metrics,
best_interaction_model = univ_results$best_interaction_model,
all_interaction_models = univ_results$all_interaction_models,
center_vals_list = univ_results$center_vals_list,
adjust_terms = adjustment_model$fp_terms,
group_var = univ_results$group_var,
include_group_var = include_group_var,
show_models = univ_results$show_models,
flex = univ_results$flex,
criterion = univ_results$criterion,
group_levels_new = univ_results$group_levels_new,
group_levels_original = univ_results$group_levels_original,
group_level_map = univ_results$group_level_map,
family = univ_results$family,
fitter = fitter,
nobs = univ_results$nobs,
cox_offset_reference = cox_offset_reference,
p_adjust_method = univ_results$p_adjust_method,
scale = scale,
shift = shift,
# Training matrix after MFPI preprocessing.
#
# This matrix contains shifted/scaled predictors and the internally remapped
# group_var codes produced by preprocess_data(). It is the correct matrix for
# manual training-data prediction reconstruction, especially when
# predict.mfpi(newdata = NULL, offset = ...) cannot delegate to the stored fit.
x_train_internal = processed_data$original_x,
var_winners = univ_results$var_winners,
adjustment_model = adjustment_model,
adjustment_term_to_columns = processed_data$term_to_columns,
interaction_specs = interaction_specs,
univariable_interactions = univ_results,
digits = digits
)
}
# -----------------------------------------------------------------------------
# preprocess_data() -----------------------------------------------------------
# -----------------------------------------------------------------------------
#' Prepare Predictors for the MFPI Adjustment Model
#'
#' Removes the grouping variable from the adjustment predictors and optionally
#' replaces it with dummy variables for its non-reference levels. Aligns the
#' modelling settings and term-to-column mapping with the resulting matrix.
#'
#' Group values are recoded as consecutive integers starting at zero.
#' Original labels and their mapping to these codes are retained.
#'
#' @param x Numeric predictor matrix including \code{group_var}.
#' @param group_var Character string naming the grouping variable.
#' @param include_group_var Whether to include group dummy variables in the
#' adjustment model.
#' @param select Named numeric vector of variable-selection significance levels.
#' @param alpha Named numeric vector of FP-degree significance levels.
#' @param df Named numeric vector of adjustment degrees of freedom.
#' @param center Named logical vector controlling predictor centring.
#' @param acd_vars Named logical vector identifying predictors to receive an
#' approximate cumulative distribution transformation.
#' @param fp_powers Named list of candidate FP powers for each predictor.
#' @param zero_vars Named logical vector identifying predictors whose exact
#' zeros are handled separately during transformation.
#' @param catzero_vars Named logical vector identifying predictors requiring
#' a zero indicator alongside their transformed positive values.
#' @param spike_vars Named logical vector identifying predictors eligible for
#' spike-at-zero modelling.
#' @param keep Character vector naming adjustment terms or columns to retain.
#' @param force_max_fp Named logical vector identifying predictors whose
#' maximum permitted FP degree must be retained.
#' @param group_input_levels Numeric group values in \code{x}, in group order.
#' If \code{NULL}, uses the sorted observed values.
#' @param group_levels_original Original labels corresponding to
#' \code{group_input_levels}. If \code{NULL}, uses the numeric group values
#' as labels.
#' @param term_to_columns Named list mapping adjustment terms to predictor
#' columns.
#'
#' @return A list containing:
#' \describe{
#' \item{\code{x}}{Adjustment predictor matrix, with optional group dummy
#' columns.}
#' \item{\code{original_x}}{Input predictor matrix with recoded group values.}
#' \item{\code{cat_info}}{Group values, labels, level mappings, and dummy
#' matrix.}
#' \item{\code{dummy_names}}{Names of appended group dummy columns, or
#' \code{NULL} when group main effects are excluded.}
#' \item{\code{term_to_columns}}{Updated mapping of adjustment terms to
#' predictor columns.}
#' \item{\code{updated_params}}{Modelling settings aligned with the adjustment
#' predictors.}
#' }
#'
#' @keywords internal
#' @noRd
preprocess_data <- function(x, group_var, include_group_var,
select, alpha, df, center, acd_vars,
fp_powers, zero_vars, catzero_vars, spike_vars,
keep, force_max_fp, group_input_levels = NULL,
group_levels_original = NULL,
term_to_columns) {
original_names <- colnames(x)
# Developer note:
# Internally remap group_var to 0, 1, ..., K - 1. Several downstream helpers
# build and parse column names using the group value as a suffix, so arbitrary
# original levels such as 10/20, 0.5/1.5, -1/1, or character labels are unsafe.
#
# `input_levels` are the numeric values currently stored in x[, group_var].
# `original_levels` are the user-facing labels used for printing, summaries,
# plotting, and prediction metadata.
group_values_original <- x[, group_var, drop = FALSE]
input_levels <- if (!is.null(group_input_levels)) {
as.numeric(group_input_levels)
} else {
sort(unique(drop(group_values_original)))
}
original_levels <- if (!is.null(group_levels_original)) {
as.character(group_levels_original)
} else {
as.character(input_levels)
}
if (length(original_levels) != length(input_levels)) {
stop(
"Internal error: `group_levels_original` and `group_input_levels` ",
"must have the same length.",
call. = FALSE
)
}
# Keep only group levels that are still present after any row-level filtering
# such as `subset`. `drop()` removes matrix/data-frame dimensions if present.
observed_input_levels <- sort(unique(drop(group_values_original)))
# Identify metadata levels that were known before filtering but are no longer
# represented in the data. Keeping these would create all-zero group dummies.
unused_input_levels <- setdiff(input_levels, observed_input_levels)
# If filtering removed one or more groups, remove the corresponding entries
# from both the numeric/internal level vector and the original-label vector.
# This keeps the two vectors aligned before new internal levels are assigned.
if (length(unused_input_levels) > 0L) {
keep <- input_levels %in% observed_input_levels
input_levels <- input_levels[keep]
original_levels <- original_levels[keep]
}
new_levels <- seq_along(input_levels) - 1L
n_group_levels <- length(new_levels)
if (isTRUE(include_group_var) && n_group_levels > 6L) {
warning(
paste0(
"`include_group_var = TRUE` will add ",
n_group_levels - 1L,
" forced group dummy variables to the adjustment model. ",
"This may be unstable when group levels are sparse."
),
call. = FALSE
)
}
group_mapped <- new_levels[
match(drop(group_values_original), input_levels)
]
if (anyNA(group_mapped)) {
bad <- unique(drop(group_values_original)[is.na(group_mapped)])
stop(
paste0(
"Internal error: group values could not be mapped to stored group levels. ",
"Unmatched value(s): ",
paste(bad, collapse = ", "),
". This usually indicates that `group_var` was modified before ",
"group-level remapping."
),
call. = FALSE
)
}
group_values <- matrix(
group_mapped,
ncol = 1L,
dimnames = dimnames(group_values_original)
)
x_internal <- x
x_internal[, group_var] <- group_mapped
# Developer note:
# original_x is "original" with respect to later filtering and dummy expansion,
# but it intentionally contains the internally remapped group_var. The raw
# group values are stored separately in cat_info$original_values.
original_x <- x_internal
# Remove group_var from the adjustment predictor set. Interaction-stage code
# still has access to the remapped group variable through original_x/cat_info.
predictor_names <- setdiff(original_names, group_var)
x_filtered <- x_internal[, predictor_names, drop = FALSE]
# Remove the dedicated grouping variable from the adjustment-term lookup but
# retain every other conceptual term and its surviving raw columns.
adjustment_term_to_columns <- lapply(term_to_columns, function(cols) {
intersect(cols, predictor_names)
})
adjustment_term_to_columns <- adjustment_term_to_columns[
lengths(adjustment_term_to_columns) > 0L
]
adjustment_column_to_term <- stats::setNames(
rep(names(adjustment_term_to_columns), lengths(adjustment_term_to_columns)),
unlist(adjustment_term_to_columns, use.names = FALSE)
)
# Convert keep entries to conceptual adjustment terms. A raw member column of
# a grouped categorical term therefore retains the complete block.
keep_filtered <- character(0L)
if (!is.null(keep)) {
keep_filtered <- unique(vapply(keep, function(value) {
if (value %in% names(adjustment_term_to_columns)) {
value
} else if (value %in% names(adjustment_column_to_term)) {
unname(adjustment_column_to_term[[value]])
} else {
NA_character_
}
}, character(1L)))
keep_filtered <- keep_filtered[!is.na(keep_filtered)]
}
# Developer note:
# Slice per-variable parameters by name, not by position. This is safer after
# group_var removal and after formula-interface processing. Required modelling
# parameters must never be NULL here; a NULL value means the upstream interface
# failed to expand defaults correctly before calling fit_mfpi().
slice_param <- function(v, param_name) {
if (is.null(v)) {
stop(
paste0(
"! Internal error in preprocess_data(): `", param_name, "` is NULL.\n",
"i This parameter should have been expanded to one value per column ",
"before calling fit_mfpi()."
),
call. = FALSE
)
}
if (is.null(names(v))) {
if (length(v) != length(original_names)) {
stop(
paste0(
"! Internal error in preprocess_data(): `", param_name,
"` is unnamed and has length ", length(v),
", but expected length ", length(original_names), "."
),
call. = FALSE
)
}
names(v) <- original_names
}
missing_names <- setdiff(predictor_names, names(v))
if (length(missing_names) > 0L) {
stop(
paste0(
"! Internal error in preprocess_data(): `", param_name,
"` is missing entries for: ",
paste(missing_names, collapse = ", "), "."
),
call. = FALSE
)
}
out <- v[predictor_names]
names(out) <- predictor_names
out
}
updated_params <- list(
select = slice_param(select, "select"),
alpha = slice_param(alpha, "alpha"),
df = slice_param(df, "df"),
center = slice_param(center, "center"),
acd_vars = slice_param(acd_vars, "acd_vars"),
fp_powers = slice_param(fp_powers, "fp_powers"),
zero_vars = slice_param(zero_vars, "zero_vars"),
catzero_vars = slice_param(catzero_vars, "catzero_vars"),
spike_vars = slice_param(spike_vars, "spike_vars"),
force_max_fp = slice_param(force_max_fp, "force_max_fp"),
keep = keep_filtered
)
dummy_names <- NULL
# Compute group dummies once. They are always stored in cat_info and are also
# appended to the adjustment matrix when include_group_var = TRUE.
group_dummies_mat <- create_group_dummies(
group_values,
levels = new_levels,
quiet = TRUE
)
# Group dummy names are generated from the pattern paste0(group_var, level),
# for example "trt1". A user-supplied predictor can legitimately have the same
# name. If that happens, duplicate column names would corrupt model fitting,
# adjustment-variable selection, coefficient lookup, and prediction
# reconstruction. Stop early with a clear error instead of allowing silent
# name collisions.
dummy_names_candidate <- colnames(group_dummies_mat)
dummy_name_collisions <- intersect(dummy_names_candidate, colnames(x_filtered))
if (length(dummy_name_collisions) > 0L) {
stop(
paste0(
"Generated group dummy column name(s) collide with existing predictor ",
"column name(s): ",
paste(dummy_name_collisions, collapse = ", "),
". Rename the existing predictor column(s) or the grouping variable."
),
call. = FALSE
)
}
#
if (include_group_var) {
dummy_names <- colnames(group_dummies_mat)
x_filtered <- cbind(x_filtered, group_dummies_mat)
n_dummies <- length(dummy_names)
make_dummy_param <- function(val) {
setNames(rep(val, n_dummies), dummy_names)
}
dummy_params <- list(
select = make_dummy_param(1), # force group dummies into MFP
alpha = make_dummy_param(0), # no FP degree selection
df = make_dummy_param(1L), # linear binary dummy terms
center = make_dummy_param(FALSE), # do not centre dummy terms
acd_vars = make_dummy_param(FALSE),
zero_vars = make_dummy_param(FALSE),
catzero_vars = make_dummy_param(FALSE),
spike_vars = make_dummy_param(FALSE),
force_max_fp = make_dummy_param(FALSE),
fp_powers = setNames(
replicate(n_dummies, 1, simplify = FALSE),
dummy_names
)
)
for (param in names(dummy_params)) {
updated_params[[param]] <- c(
updated_params[[param]],
dummy_params[[param]]
)
}
# Treat all group dummy columns as one conceptual term. They are forced
# into the adjustment model together and removed together before stage 2.
adjustment_term_to_columns[[group_var]] <- dummy_names
updated_params$keep <- unique(c(keep_filtered, group_var))
}
list(
x = x_filtered,
original_x = original_x,
cat_info = list(
values = group_values,
original_values = group_values_original,
original_levels = original_levels,
input_levels = input_levels,
new_levels = new_levels,
level_map = data.frame(
original = original_levels,
input = input_levels,
internal = new_levels,
stringsAsFactors = FALSE
),
group_var = group_var,
dummies = group_dummies_mat
),
dummy_names = dummy_names,
term_to_columns = adjustment_term_to_columns,
updated_params = updated_params
)
}
# -----------------------------------------------------------------------------
# restore_mfpi_adjustment_shifts()
# -----------------------------------------------------------------------------
#' Restore Predictor Shifts in the MFPI Adjustment Model
#'
#' Records the original predictor shifts in the fitted adjustment model so
#' that reported transformations and predictions from new data use the correct
#' values. The predictors are already shifted before fitting, so the adjustment
#' model is initially fitted with zero shifts.
#'
#' @param adjustment_model Fitted \code{mfp2} adjustment model.
#' @param shift Named numeric vector of predictor shifts.
#' @param term_to_columns Named list mapping adjustment terms to predictor
#' columns.
#'
#' @return The adjustment model with the \code{shift} column of
#' \code{transformations} updated to the original predictor shifts.
#'
#' @keywords internal
#' @noRd
restore_mfpi_adjustment_shifts <- function(adjustment_model,
shift,
term_to_columns) {
if (is.null(adjustment_model$transformations) ||
is.null(rownames(adjustment_model$transformations)) ||
!"shift" %in% colnames(adjustment_model$transformations) ||
is.null(shift) || length(shift) == 0L) {
return(adjustment_model)
}
if (is.null(names(shift)) || anyNA(names(shift)) || any(!nzchar(names(shift)))) {
stop(
"Internal error: MFPI shift values must be named before restoring adjustment-model metadata.",
call. = FALSE
)
}
transformation_terms <- rownames(adjustment_model$transformations)
for (term in transformation_terms) {
# A singleton conceptual term normally has the same name as its raw column.
# Prefer that direct lookup because it also covers formula-created singleton
# terms whose mapping is intentionally simple.
if (term %in% names(shift)) {
term_shift <- unname(shift[[term]])
} else {
cols <- term_to_columns[[term]]
cols <- intersect(cols, names(shift))
# The MFPI grouping term can be represented by internally created dummy
# columns that have no entry in the original shift vector. Its shift must
# remain the Stage-1 value (zero), so simply skip terms with no source shift.
if (length(cols) == 0L) next
values <- unname(shift[cols])
if (length(values) > 1L && !all(values == values[[1L]])) {
stop(
sprintf(
"Internal error: grouped adjustment term '%s' has inconsistent MFPI shift values.",
term
),
call. = FALSE
)
}
term_shift <- values[[1L]]
}
if (length(term_shift) != 1L || is.na(term_shift) || !is.finite(term_shift)) {
stop(
sprintf(
"Internal error: adjustment term '%s' does not have a finite MFPI shift.",
term
),
call. = FALSE
)
}
adjustment_model$transformations[term, "shift"] <- term_shift
}
adjustment_model
}
# -----------------------------------------------------------------------------
# fit_adjustment_model() ------------------------------------------------------
# -----------------------------------------------------------------------------
#' Fit the MFP Adjustment Model
#'
#' Selects adjustment terms and their fractional-polynomial transformations
#' using \code{fit_mfp()}. Categorical terms are selected jointly.
#'
#' @param x Prepared numeric adjustment predictor matrix, optionally including
#' group dummy variables.
#' @param y Response vector, response matrix, or \code{survival::Surv()} object.
#' @param weights Numeric vector of observation weights.
#' @param offset Linear-predictor offsets: a numeric vector or, for multinomial
#' models, a matrix with one column per non-reference outcome category.
#' @param cycles Maximum number of MFP backfitting cycles.
#' @param family Resolved model-family specification.
#' @param family_string Character string giving the canonical family name.
#' @param criterion Adjustment selection criterion: \code{"pvalue"},
#' \code{"aic"}, or \code{"bic"}.
#' @param updated_params Named list of modelling settings returned by
#' \code{preprocess_data()}, including selection levels, degrees of freedom,
#' candidate powers, transformation options, and retention settings.
#' @param xorder Order of adjustment terms during MFP backfitting:
#' \code{"ascending"}, \code{"descending"}, or \code{"original"}.
#' @param ties Method for handling tied event times in Cox models.
#' @param strata Optional prepared survival-model stratification information.
#' @param nocenter Numeric values excluded from automatic centring by
#' \code{survival::coxph()}.
#' @param min_saz_prop Minimum proportion required in both the zero and
#' positive components of a spike-at-zero adjustment variable.
#' @param use_ftest Whether to use F-tests instead of likelihood-ratio
#' chi-square tests for Gaussian p-value comparisons. Ignored for other
#' families.
#' @param control List of model-fitting control parameters.
#' @param force_max_fp Retained internal argument. The settings used for
#' fitting are read from \code{updated_params$force_max_fp}.
#' @param scale Named numeric vector of predictor scale factors.
#' @param has_offset Logical indicating whether an offset was supplied.
#' @param term_to_columns Named list mapping adjustment terms to predictor
#' columns.
#' @param verbose Whether to print fitting progress.
#' @param fitter Model-fitting backend.
#'
#' @details
#' Predictors have already been shifted and scaled. Zero shifts are passed to
#' \code{fit_mfp()} to avoid applying shifts twice. Scale factors are retained
#' so that selected terms are constructed on the shifted, unscaled predictor
#' scale. The caller restores the original shifts in the fitted model.
#'
#' Variables marked in \code{updated_params$force_max_fp} retain their maximum
#' permitted FP degree, with powers selected within that degree. For eligible
#' spike-at-zero terms, both the zero indicator and the maximum-degree
#' continuous component are retained.
#'
#' @return The adjustment-model results returned by \code{fit_mfp()}, including
#' the selected-term table \code{fp_terms} and the underlying fitted model.
#'
#' @keywords internal
#' @noRd
fit_adjustment_model <- function(x, y, weights, offset, cycles, family,
family_string, criterion, updated_params,
xorder, ties, strata, nocenter,
min_saz_prop, use_ftest, control,
force_max_fp, scale, has_offset,
term_to_columns,
verbose = FALSE, fitter = "base") {
n_vars <- ncol(x)
x_names <- colnames(x)
# Build raw-column scale values first, then collapse all modelling settings
# to one value per conceptual term for the grouped MFP core. Group dummy and
# categorical contrast columns use scale 1.
scale_vec <- setNames(rep(1, n_vars), x_names)
if (!is.null(scale)) {
shared <- intersect(x_names, names(scale))
scale_vec[shared] <- scale[shared]
}
collapse <- function(values, setting) {
collapse_option_to_terms(values, term_to_columns, setting)
}
df_term <- collapse(updated_params$df, "df")
center_term <- collapse(updated_params$center, "center")
select_term <- collapse(updated_params$select, "select")
alpha_term <- collapse(updated_params$alpha, "alpha")
acd_term <- collapse(updated_params$acd_vars, "acd_vars")
zero_term <- collapse(updated_params$zero_vars, "zero_vars")
catzero_term <- collapse(updated_params$catzero_vars, "catzero_vars")
spike_term <- collapse(updated_params$spike_vars, "spike_vars")
force_term <- collapse(updated_params$force_max_fp, "force_max_fp")
scale_term <- collapse(scale_vec, "scale")
powers_term <- lapply(names(term_to_columns), function(term) {
cols <- term_to_columns[[term]]
if (term_uses_column_mapping(term, cols)) {
1
} else {
updated_params$fp_powers[[cols[[1L]]]]
}
})
names(powers_term) <- names(term_to_columns)
fit_mfp(
x = x,
y = y,
weights = weights,
offset = offset,
cycles = cycles,
method = ties,
strata = strata,
nocenter = nocenter,
scale = scale_term,
shift = stats::setNames(rep(0, length(term_to_columns)), names(term_to_columns)),
ftest = use_ftest,
control = control,
family = family,
family_string = family_string,
fitter = fitter,
criterion = criterion,
xorder = xorder,
df = df_term,
center = center_term,
select = select_term,
alpha = alpha_term,
keep = updated_params$keep,
powers = powers_term,
acdx = acd_term,
zero = zero_term,
catzero = catzero_term,
spike = spike_term,
min_saz_prop = min_saz_prop,
saz_pre_resolved = TRUE,
force_max_fp = force_term,
term_to_columns = term_to_columns,
has_offset = has_offset,
verbose = verbose
)
}
# -----------------------------------------------------------------------------
# format_type_label() ---------------------------------------------------------
# -----------------------------------------------------------------------------
#' Format Functional Form Labels
#'
#' Converts \code{"linear"}, \code{"fp1"}, and \code{"fp2"} to
#' \code{"Linear"}, \code{"FP1"}, and \code{"FP2"}, respectively.
#'
#' @param type Character vector of functional form names.
#'
#' @return Character vector of display labels.
#'
#' @keywords internal
#' @noRd
format_type_label <- function(type) {
ifelse(
tolower(type) == "linear",
"Linear",
toupper(type) # fp1 -> FP1, fp2 -> FP2
)
}
# -----------------------------------------------------------------------------
# format_candidate_table() ----------------------------------------------------
# -----------------------------------------------------------------------------
#' Print an Interaction Comparison Table
#'
#' Prints comparison metrics for one interaction variable. Displayed columns
#' depend on the selection criterion:
#' \itemize{
#' \item \code{"pvalue"}: interaction-model deviance, deviance difference,
#' interaction degrees of freedom, and p-value.
#' \item \code{"aic"}: main-effects and interaction-model AIC values and
#' their difference.
#' \item \code{"bic"}: main-effects and interaction-model BIC values and
#' their difference.
#' }
#'
#' Also displays FP powers for the main-effects and interaction models.
#' For FLEX4, interaction powers are shown separately for each group.
#' AIC and BIC differences are calculated as main-effects minus interaction
#' values, so positive differences favour the interaction model.
#'
#' @param rows Named list of one-row data frames containing comparison metrics
#' and FP powers for the evaluated interaction form.
#' @param criterion Selection criterion: \code{"pvalue"}, \code{"aic"}, or
#' \code{"bic"}.
#' @param digits Number of decimal places for displayed statistics.
#'
#' @return Invisibly returns \code{NULL} after printing the table.
#'
#' @keywords internal
#' @noRd
format_candidate_table <- function(rows, criterion, digits, best_type = NULL) {
# Format a single power entry as a parenthesised string. Always returns a
# length-1 character string ("." for missing/empty).
# For flex1-3, `pow` is a numeric vector e.g. c(1, 2).
# For flex4, `pow` is a list of per-group vectors e.g. list(c(1, 2), c(0.5)).
format_powers <- function(pow) {
if (is.null(pow) || length(pow) == 0L) return(".")
if (is.atomic(pow) && all(is.na(pow))) return(".")
if (is.list(pow)) {
paste(
vapply(pow, function(p) {
if (is.null(p) || length(p) == 0L) "()"
else paste0("(", paste(p, collapse = ", "), ")")
}, character(1L)),
collapse = ", "
)
} else {
paste0("(", paste(pow, collapse = ", "), ")")
}
}
format_row <- function(metrics) {
# Safe extraction helpers
safe_decimal <- function(val) {
if (is.null(val) || length(val) == 0L || is.na(val[1L])) return("NA")
format_print_decimal(val[1L], digits)
}
safe_pvalue <- function(val) {
if (is.null(val) || length(val) == 0L || is.na(val[1L])) return("NA")
format_print_pvalue(val[1L], digits)
}
safe_df <- function(val) {
if (is.null(val) || length(val) == 0L || is.na(val[1L])) return("NA")
format(val[1L], trim = TRUE, scientific = FALSE)
}
safe_chr <- function(val) {
if (is.null(val) || length(val) == 0L) return("")
as.character(val[1L])
}
type_raw <- safe_chr(metrics$type)
type_label <- if (nzchar(type_raw)) format_type_label(type_raw) else "?"
main_pow <- if (length(metrics$fp_powers_main) > 0L)
metrics$fp_powers_main[[1L]] else NULL
int_pow <- if (length(metrics$fp_powers_int) > 0L)
metrics$fp_powers_int[[1L]] else NULL
# Base columns: Type and powers always shown
base_cols <- data.frame(
Type = type_label,
main_power = format_powers(main_pow),
int_power = format_powers(int_pow),
stringsAsFactors = FALSE
)
# Criterion-specific columns inserted between Type and powers
crit_cols <- switch(
criterion,
"pvalue" = data.frame(
deviance_int = safe_decimal(metrics$deviance_int),
deviance_diff = safe_decimal(metrics$deviance_diff),
df = safe_df(metrics$df_int),
pvalue = safe_pvalue(metrics$pvalue),
stringsAsFactors = FALSE
),
"aic" = data.frame(
AIC_main = safe_decimal(metrics$AIC_main),
AIC_interaction = safe_decimal(metrics$AIC_interaction),
dAIC = safe_decimal(metrics$AIC_main_minus_int),
stringsAsFactors = FALSE
),
"bic" = data.frame(
BIC_main = safe_decimal(metrics$BIC_main),
BIC_interaction = safe_decimal(metrics$BIC_interaction),
dBIC = safe_decimal(metrics$BIC_main_minus_int),
stringsAsFactors = FALSE
)
)
# Final column order: Type, criterion metrics, then powers
cbind(base_cols[, "Type", drop = FALSE],
crit_cols,
base_cols[, c("main_power", "int_power"), drop = FALSE])
}
tbl <- do.call(rbind, lapply(rows, format_row))
print(tbl, row.names = FALSE, right = FALSE)
invisible(NULL)
}
# -----------------------------------------------------------------------------
# evaluate_interactions() -----------------------------------------------------
# -----------------------------------------------------------------------------
#' Evaluate Separate MFPI Interactions
#'
#' Evaluates each specified interaction with the grouping variable, adjusting
#' for the selected adjustment terms other than the variable being tested.
#' Continuous, binary, and categorical interaction terms are supported.
#'
#' Each variable uses its resolved interaction form; no selection between
#' linear, FP1, and FP2 forms is performed. Results are retained for all
#' evaluated interactions, with selected interactions also stored separately.
#'
#' @param y Response vector, response matrix, or \code{survival::Surv()} object.
#' @param processed_data List returned by \code{preprocess_data()}.
#' @param selected_vars Character vector naming selected adjustment terms.
#' @param adj_fp_powers Named list of selected adjustment powers, including
#' structural \code{NA} entries for ACD terms.
#' @param adj_zero Named logical vector of fitted zero-handling flags.
#' @param adj_catzero Named logical vector of fitted zero-indicator flags.
#' @param adj_spike Named logical vector of fitted spike-at-zero flags.
#' @param adj_spike_decision Named numeric vector of fitted spike-at-zero
#' decisions: \code{1} for continuous and binary components, \code{2} for
#' the continuous component only, and \code{3} for the binary component only.
#' @param adj_acd_parameter Fitted ACD transformation parameters for adjustment
#' terms.
#' @param interaction_vars Character vector naming terms to test for
#' interaction with the grouping variable.
#' @param interaction_forms Named character vector of resolved interaction
#' forms: \code{"linear"}, \code{"fp1"}, or \code{"fp2"}.
#' @param interaction_specs Named list describing each interaction term's type
#' and predictor columns.
#' @param flex Interaction procedure: \code{"flex1"}, \code{"flex2"},
#' \code{"flex3"}, or \code{"flex4"}.
#' @param weights Numeric vector of observation weights.
#' @param offset Linear-predictor offsets: a numeric vector or, for multinomial
#' models, a matrix with one column per non-reference outcome category.
#' @param xorder Order of terms during MFP backfitting:
#' \code{"ascending"}, \code{"descending"}, or \code{"original"}.
#' @param ties Method for handling tied event times in Cox models.
#' @param strata Optional survival-model stratification information.
#' @param use_ftest Whether to use F-tests instead of likelihood-ratio
#' chi-square tests for Gaussian p-value comparisons. Ignored for other
#' families.
#' @param control List of model-fitting control parameters.
#' @param nocenter Numeric values excluded from automatic centring by
#' \code{survival::coxph()}.
#' @param family Resolved model-family specification.
#' @param family_string Character string giving the canonical family name.
#' @param fp_powers Named list of candidate FP powers for each predictor.
#' @param cycles Maximum number of MFP backfitting cycles.
#' @param criterion Interaction selection criterion: \code{"pvalue"},
#' \code{"aic"}, or \code{"bic"}.
#' @param digits Number of decimal places for printed numerical results.
#' @param scale Named numeric vector of predictor scale factors.
#' @param shift Named numeric vector of predictor shifts.
#' @param center_type Centring method for interaction transformations:
#' \code{"grand"} or \code{"group"}.
#' @param show_models Whether to print coefficient tables for selected
#' interaction models when \code{verbose = TRUE}.
#' @param group_var Character string naming the grouping variable.
#' @param p_interact Significance threshold for p-value selection.
#' @param min_improvement Minimum AIC or BIC improvement required for selection.
#' @param min_saz_prop Minimum proportion required in both components of a
#' spike-at-zero variable.
#' @param xadj Optional matrix of transformed adjustment predictors, used when
#' \code{skip_adjustment = TRUE}.
#' @param skip_adjustment Whether to use \code{xadj} without rebuilding the
#' adjustment transformations.
#' @param p_adjust_method Method passed to \code{stats::p.adjust()} for
#' interaction p-values. Used only under \code{criterion = "pvalue"}.
#' @param has_offset Logical indicating whether an offset was supplied.
#' @param quiet Internal diagnostic-output control.
#' @param verbose Whether to print progress messages.
#' @param fitter Model-fitting backend.
#'
#' @section Selection:
#' Each interaction is compared with its corresponding main-effects model.
#' Under \code{criterion = "pvalue"}, selection requires a p-value strictly
#' below \code{p_interact}. If requested, p-values are adjusted across all
#' interaction variables before selection.
#'
#' Under \code{"aic"} or \code{"bic"}, selection requires the main-effects
#' criterion minus the interaction criterion to exceed \code{min_improvement}.
#' P-value adjustment does not affect AIC or BIC selection.
#'
#' @return A list containing:
#' \describe{
#' \item{\code{best_model_metrics}, \code{all_model_metrics}}{Data frames of
#' comparison metrics for selected and evaluated interactions, respectively.}
#' \item{\code{best_interaction_model},
#' \code{all_interaction_models}}{Named lists of fitted models for selected
#' and evaluated interactions, respectively.}
#' \item{\code{center_vals_list}}{Centring constants for selected interactions.}
#' \item{\code{var_winners}}{Fitted results for each interaction variable,
#' regardless of selection.}
#' }
#' The list also contains group labels and mappings, the family, observation
#' count, selection settings, and predictor shifts and scales.
#'
#' @keywords internal
#' @noRd
evaluate_interactions <- function(y, processed_data, selected_vars,
adj_fp_powers,
adj_zero, adj_catzero, adj_spike,
adj_spike_decision,
interaction_vars, interaction_forms,
interaction_specs, flex,
weights, offset, xorder, ties, strata,
use_ftest, control, nocenter, family,
family_string, fp_powers, cycles, criterion,
digits, group_var, show_models, p_interact,
min_improvement, min_saz_prop,
center_type = c("grand", "group"),
scale = NULL, shift = NULL,
shift_automatic = NULL,
adj_acd_parameter = NULL,
xadj = NULL, skip_adjustment = FALSE,
p_adjust_method = "none", has_offset,
quiet = FALSE, verbose = FALSE, fitter = "base") {
# Normalise the centering strategy. Interaction FP bases can either use one
# grand centering vector shared across groups or group-specific centering.
center_type <- match.arg(center_type)
# ---------------------------------------------------------------------------
# Validate adjustment-matrix control arguments
# ---------------------------------------------------------------------------
# `skip_adjustment = TRUE` means an already prepared adjustment matrix may be
# supplied via `xadj`; otherwise the adjustment matrix is built from selected
# adjustment variables below.
if (!is.logical(skip_adjustment) || length(skip_adjustment) != 1L) {
stop("`skip_adjustment` must be a single logical value.", call. = FALSE)
}
if (skip_adjustment && !is.null(xadj)) {
if (!is.matrix(xadj) || !is.numeric(xadj)) {
stop(
"`xadj` must be a numeric matrix when `skip_adjustment = TRUE`.",
call. = FALSE
)
}
}
# Main processed predictor matrix and group metadata used throughout the
# interaction-evaluation stage.
x <- processed_data$original_x
nobs <- nrow(x)
cat_info <- processed_data$cat_info
# Map the user-facing interaction form to the FP degree expected by flex_fit().
# linear -> degree 0, fp1 -> degree 1, fp2 -> degree 2.
degree_lookup <- c(linear = 0L, fp1 = 1L, fp2 = 2L)
# ---------------------------------------------------------------------------
# Pre-allocate result containers
# ---------------------------------------------------------------------------
# Each variable contributes exactly one candidate form because MFPI now uses
# pre-specified `interaction_forms`; there is no data-driven search over linear,
# FP1, and FP2 inside this loop.
n_vars <- length(interaction_vars)
n_types <- 1L
best_metrics_list <- vector("list", n_vars)
all_metrics_list <- vector("list", n_vars * n_types)
best_interaction_model <- vector("list", n_vars)
all_interaction_models <- vector("list", n_vars)
center_vals_list <- vector("list", n_vars)
names(best_interaction_model) <- interaction_vars
names(all_interaction_models) <- interaction_vars
names(center_vals_list) <- interaction_vars
# Store the best candidate for every variable, even if it is not retained.
# This is needed later for multiplicity-adjusted p-value decisions.
var_winners <- vector("list", n_vars)
names(var_winners) <- interaction_vars
# P-value selection is deferred only when a real multiplicity adjustment is
# requested. If p_adjust_method = "none", raw p-values are final immediately.
adjusting_pvals <- criterion == "pvalue" && p_adjust_method != "none"
# Shared AIC/BIC metadata used by the per-variable winner logic, verbose
# selected/not-selected messages, and the final AIC/BIC summary. Keeping this
# mapping in one place prevents the metric column names and display labels from
# drifting across branches.
ic_col <- NULL
ic_label <- NULL
if (criterion == "aic") {
ic_col <- "AIC_main_minus_int"
ic_label <- "dAIC"
} else if (criterion == "bic") {
ic_col <- "BIC_main_minus_int"
ic_label <- "dBIC"
}
# Write counters for the pre-allocated result lists.
best_idx <- 0L
all_idx <- 0L
# Filled only when p-value adjustment is requested. In that case it becomes
# the authoritative all-model metric table returned by this function.
all_candidate_metrics <- NULL
# ---------------------------------------------------------------------------
# Build the adjustment-block cache once
# ---------------------------------------------------------------------------
# The adjustment set is fixed across the interaction stage except that the
# current tested variable must be removed from its own adjustment set. Instead
# of rebuilding the full transformed adjustment matrix inside every cont_var
# iteration, transform each selected adjustment variable once and reuse the
# cached source-variable blocks.
group_dummy_names <- colnames(processed_data$cat_info$dummies)
adjustment_cache <- mfpi_build_adjustment_block_cache(
x = x,
selected_vars = selected_vars,
group_dummy_names = group_dummy_names,
group_dummy_term = cat_info$group_var,
term_to_columns = processed_data$term_to_columns,
skip_adjustment = skip_adjustment,
scale = scale,
adj_fp_powers = adj_fp_powers,
center = processed_data$updated_params$center,
acd_vars = processed_data$updated_params$acd_vars,
adj_zero = adj_zero,
adj_catzero = adj_catzero,
adj_spike = adj_spike,
adj_spike_decision = adj_spike_decision,
adj_acd_parameter = adj_acd_parameter
)
# Source-variable names for selected adjustment variables after group dummies
# have been removed. This is used both for verbose display and xadj assembly.
selected_adj_vars <- adjustment_cache$selected_adj_vars
# ===========================================================================
# Main loop: evaluate one pre-specified interaction candidate per cont_var
# ===========================================================================
for (var_name in interaction_vars) {
var_idx <- match(var_name, interaction_vars)
res <- evaluate_interaction_for_variable(
var_name = var_name,
var_idx = var_idx,
n_vars = n_vars,
x = x,
y = y,
cat_info = cat_info,
adjustment_cache = adjustment_cache,
selected_adj_vars = selected_adj_vars,
skip_adjustment = skip_adjustment,
xadj = xadj,
interaction_forms = interaction_forms,
interaction_specs = interaction_specs,
degree_lookup = degree_lookup,
processed_data = processed_data,
criterion = criterion,
ties = ties,
family = family,
family_string = family_string,
fitter = fitter,
use_ftest = use_ftest,
center_type = center_type,
xorder = xorder,
weights = weights,
offset = offset,
strata = strata,
control = control,
nocenter = nocenter,
cycles = cycles,
min_saz_prop = min_saz_prop,
flex = flex,
scale = scale,
shift = shift,
shift_automatic = shift_automatic,
has_offset = has_offset,
ic_col = ic_col,
ic_label = ic_label,
adjusting_pvals = adjusting_pvals,
p_interact = p_interact,
min_improvement = min_improvement,
verbose = verbose,
quiet = quiet,
show_models = show_models,
digits = digits
)
# Store this variable's candidate metrics rows in the full all-model
# metrics list, mirroring the original per-candidate all_idx bookkeeping
# (currently always one row per variable, since there is exactly one
# pre-specified candidate form per variable).
for (interaction_type in names(res$candidate_metrics)) {
all_idx <- all_idx + 1L
all_metrics_list[[all_idx]] <- res$candidate_metrics[[interaction_type]]
}
# Store the per-variable winner for later summaries and, when needed,
# multiplicity-adjusted final selection.
var_winners[[var_name]] <- list(
fit = res$best_fit,
metric = res$best_metric,
type = res$best_type,
score = res$best_score,
center_vals = if (!is.null(res$best_fit)) res$best_fit$center_vals else NULL
)
# Immediate final selection when p-values are not being adjusted. The
# decision is stored here but is not printed until the Step 3 summary.
if (!adjusting_pvals && isTRUE(res$retained)) {
best_idx <- best_idx + 1L
best_metrics_list[[best_idx]] <- res$best_metric
best_interaction_model[[var_name]] <-
res$best_fit$test_results$interaction_model
center_vals_list[[var_name]] <- res$best_fit$center_vals
}
# Store the fitted interaction model for this variable directly, regardless
# of whether it was selected. Each variable has exactly one pre-specified
# form, so exposing the legacy candidate-list layer would make the public
# object one level deeper than documented.
interaction_type <- interaction_forms[[var_name]]
interaction_model <- res$candidate_models[[interaction_type]]
if (is.null(interaction_model)) {
stop(
sprintf(
paste0(
"Internal error: no interaction model was stored for '%s' ",
"using form '%s'."
),
var_name,
interaction_type
),
call. = FALSE
)
}
all_interaction_models[[var_name]] <- interaction_model
# Replace the all-metrics row with the canonical best_metric object where
# available, preserving normalized reporting columns.
if (!is.null(res$best_metric)) {
all_metrics_list[[all_idx]] <- res$best_metric
}
}
# ===========================================================================
# Step 3 final interaction summary
# ===========================================================================
# Final selection decisions are reported only after all variables have been
# evaluated. Step 2 deliberately reports observed statistics without a
# provisional selected/not-selected label.
if (verbose && criterion %in% c("aic", "bic") && !adjusting_pvals) {
print_interaction_step3_summary(
var_winners = var_winners,
interaction_vars = interaction_vars,
mode = "ic",
ic_col = ic_col,
ic_label = ic_label,
min_improvement = min_improvement,
digits = digits,
show_models = show_models,
best_interaction_model = best_interaction_model
)
}
if (verbose && criterion == "pvalue" && !adjusting_pvals) {
print_interaction_step3_summary(
var_winners = var_winners,
interaction_vars = interaction_vars,
mode = "pvalue",
p_interact = p_interact,
p_adjust_method = p_adjust_method,
digits = digits,
show_models = show_models,
best_interaction_model = best_interaction_model
)
}
# ===========================================================================
# Phase 2: p-value adjustment and final p-value decisions
# ===========================================================================
# When multiplicity adjustment is requested, raw p-values from all planned
# tests must be collected before any final retain/drop decisions are made.
if (adjusting_pvals) {
finalized <- finalize_adjusted_pvalue_selection(
var_winners = var_winners,
all_metrics_list = all_metrics_list,
all_idx = all_idx,
interaction_vars = interaction_vars,
n_vars = n_vars,
n_types = n_types,
p_adjust_method = p_adjust_method,
p_interact = p_interact
)
var_winners <- finalized$var_winners
all_candidate_metrics <- finalized$all_candidate_metrics
best_idx <- finalized$best_idx
best_metrics_list <- finalized$best_metrics_list
best_interaction_model <- finalized$best_interaction_model
center_vals_list <- finalized$center_vals_list
# Final adjusted p-value interaction summary.
if (verbose) {
print_interaction_step3_summary(
var_winners = var_winners,
interaction_vars = interaction_vars,
mode = "pvalue",
p_interact = p_interact,
p_adjust_method = p_adjust_method,
digits = digits,
show_models = show_models,
best_interaction_model = best_interaction_model
)
}
}
# ---------------------------------------------------------------------------
# Trim pre-allocated containers
# ---------------------------------------------------------------------------
# When p-value adjustment was used, all_candidate_metrics is already the final
# all-model metric table, so all_metrics_list does not need to be rebound for
# the returned all_model_metrics.
best_metrics_list <- best_metrics_list[seq_len(best_idx)]
if (!adjusting_pvals) {
all_metrics_list <- all_metrics_list[seq_len(all_idx)]
}
# Remove variables that were not finally retained.
best_interaction_model <- Filter(Negate(is.null), best_interaction_model)
# ---------------------------------------------------------------------------
# Build returned metric tables
# ---------------------------------------------------------------------------
combined_metrics <- bind_metric_rows(best_metrics_list)
if (nrow(combined_metrics) > 0L && "type" %in% names(combined_metrics)) {
combined_metrics <- combined_metrics[
,
c("type", setdiff(names(combined_metrics), "type")),
drop = FALSE
]
}
all_model_metrics <- if (adjusting_pvals && !is.null(all_candidate_metrics)) {
all_candidate_metrics
} else {
bind_metric_rows(all_metrics_list)
}
# Keep a stable display/storage order for all-model metric columns.
if (nrow(all_model_metrics) > 0L) {
metric_cols <- setdiff(names(all_model_metrics), c("variable", "type"))
all_model_metrics <- all_model_metrics[
,
c("type", "variable", metric_cols),
drop = FALSE
]
}
# ---------------------------------------------------------------------------
# Return MFPI interaction-evaluation result object
# ---------------------------------------------------------------------------
list(
best_model_metrics = combined_metrics,
all_model_metrics = all_model_metrics,
best_interaction_model = best_interaction_model,
all_interaction_models = all_interaction_models,
center_vals_list = center_vals_list,
group_var = group_var,
show_models = show_models,
group_levels_new = cat_info$new_levels,
group_levels_original = cat_info$original_levels,
group_level_map = cat_info$level_map,
flex = flex,
criterion = criterion,
family = family,
nobs = nobs,
p_adjust_method = p_adjust_method,
scale = scale,
shift = shift,
var_winners = var_winners
)
}
# -----------------------------------------------------------------------------
# evaluate_interactions() helpers --------------------------------------------
# -----------------------------------------------------------------------------
#' Evaluate One MFPI Interaction
#'
#' Fits the resolved interaction form for one continuous, binary, or
#' categorical term and compares it with the corresponding main-effects model.
#' Makes the selection decision immediately unless p-value adjustment is
#' requested, in which case selection is deferred.
#'
#' @inheritParams evaluate_interactions
#'
#' @param var_name Character string naming the interaction term.
#' @param var_idx,n_vars Current variable index and total number of interaction
#' variables, used in progress messages.
#' @param x Prepared numeric predictor matrix.
#' @param cat_info Group metadata from \code{preprocess_data()}.
#' @param adjustment_cache Cached transformed adjustment terms.
#' @param selected_adj_vars Character vector naming selected adjustment terms,
#' excluding group dummy variables.
#' @param degree_lookup Named integer vector mapping interaction forms to
#' FP degrees: \code{linear = 0}, \code{fp1 = 1}, and \code{fp2 = 2}.
#' @param ic_col,ic_label Metric column name and display label for the active
#' information criterion, or \code{NULL} for p-value selection.
#' @param adjusting_pvals Whether selection is deferred until interaction
#' p-values have been adjusted across variables.
#'
#' @return A list containing:
#' \describe{
#' \item{\code{candidate_metrics}}{Named list containing the comparison
#' metrics for the evaluated form.}
#' \item{\code{candidate_models}}{Named list containing the fitted
#' interaction model.}
#' \item{\code{best_fit}, \code{best_metric}, \code{best_type},
#' \code{best_score}}{The fitted result, comparison metrics, form, and
#' comparison score for the evaluated interaction.}
#' \item{\code{retained}}{Selection decision, or \code{NA} when selection
#' is deferred for p-value adjustment.}
#' }
#'
#' @keywords internal
#' @noRd
evaluate_interaction_for_variable <- function(var_name,
var_idx,
n_vars,
x,
y,
cat_info,
adjustment_cache,
selected_adj_vars,
skip_adjustment,
xadj,
interaction_forms,
interaction_specs,
degree_lookup,
processed_data,
criterion,
ties,
family,
family_string,
use_ftest,
center_type,
xorder,
weights,
offset,
strata,
control,
nocenter,
cycles,
min_saz_prop,
flex,
scale,
shift,
shift_automatic = NULL,
has_offset,
ic_col,
ic_label,
adjusting_pvals,
p_interact,
min_improvement,
verbose,
quiet,
show_models,
digits,
fitter = "base") {
# -----------------------------------------------------------------------
# Verbose per-variable header
# -----------------------------------------------------------------------
if (verbose) {
rule_thin <- strrep("-", 70)
mfp2_message("")
mfp2_message(rule_thin)
mfp2_message(
sprintf(
" [%d/%d] Variable: '%s' x '%s'",
var_idx, n_vars, var_name, cat_info$group_var
)
)
# Adjustment variables for this variable-specific test. The group dummies
# have already been excluded in the cache; here we only exclude var_name
# itself if it was selected by the adjustment model.
adj_vars <- setdiff(selected_adj_vars, var_name)
if (length(adj_vars) > 0L) {
mfp2_message(" Adjusting for: ", paste(adj_vars, collapse = ", "))
} else {
mfp2_message(" Adjusting for: (none)")
}
mfp2_message(rule_thin)
}
# Track the winning candidate for the current variable. Since there is only
# one pre-specified form per variable, this mostly records successful fit
# state and the relevant score.
best_fit <- NULL
best_metric <- NULL
best_type <- NULL
best_score <- Inf
# The form for this variable is pre-specified by interaction_forms.
active_type <- interaction_forms[[var_name]]
interaction_spec <- interaction_specs[[var_name]]
if (is.null(interaction_spec)) {
stop(
paste0("Internal error: no interaction specification is stored for `",
var_name, "`."),
call. = FALSE
)
}
# Candidate containers are still list-based for consistency with the older
# multi-form structure and with downstream storage conventions.
n_types <- 1L
candidate_models <- vector("list", n_types)
candidate_metrics <- vector("list", n_types)
candidate_full_fits <- vector("list", n_types)
if (verbose) {
verbose_rows <- vector("list", n_types)
names(verbose_rows) <- active_type
}
# Assemble the transformed adjustment matrix for this variable by combining
# cached blocks and excluding the current source-variable block if needed.
xadj_current <- mfpi_make_xadj_current(
var_name = var_name,
adjustment_cache = adjustment_cache,
skip_adjustment = skip_adjustment,
xadj = xadj
)
# -------------------------------------------------------------------------
# Fit the single pre-specified interaction form
# -------------------------------------------------------------------------
for (interaction_type in active_type) {
degree <- degree_lookup[[interaction_type]]
fit_result <- mfpi_with_rank_hint(flex_fit(
x = x,
y = y,
cont_var = var_name,
interaction_columns = interaction_spec$columns,
interaction_kind = interaction_spec$kind,
group_var = cat_info$group_var,
group_dummies = cat_info$dummies,
xadj = xadj_current,
criterion = criterion,
ties = ties,
degree = degree,
family = family,
family_string = family_string,
fitter = fitter,
fp_cand = if (isTRUE(interaction_spec$discrete)) 1 else
processed_data$updated_params$fp_powers[[var_name]],
use_ftest = use_ftest,
center = if (isTRUE(interaction_spec$discrete)) FALSE else
processed_data$updated_params$center[var_name],
center_type = center_type,
xorder = xorder,
weights = weights,
offset = offset,
strata = strata,
control = control,
nocenter = nocenter,
cycles = cycles,
zero_var = if (isTRUE(interaction_spec$discrete)) FALSE else
processed_data$updated_params$zero_vars[var_name],
spike_var = FALSE,
min_saz_prop = min_saz_prop,
flex = flex,
scale_var = if (isTRUE(interaction_spec$discrete)) 1 else if (!is.null(scale)) unname(scale[var_name]) else 1,
shift_var = if (isTRUE(interaction_spec$discrete)) 0 else if (!is.null(shift)) unname(shift[var_name]) else 0,
run_test = TRUE,
has_offset = has_offset
),
var_name = var_name,
interaction_spec = interaction_spec,
interaction_form = interaction_type,
x = x,
scale = scale,
shift = shift,
shift_automatic = shift_automatic,
zero_var = isTRUE(processed_data$updated_params$zero_vars[var_name])
)
# -----------------------------------------------------------------------
# Extract and annotate model-comparison metrics
# -----------------------------------------------------------------------
metrics <- fit_result$test_results$evaluation_metrics
metrics$variable <- var_name
metrics$type <- interaction_type
# Normalise FP power columns for reporting. This keeps metric tables
# readable without changing the fitted interaction model object.
metrics <- normalise_metric_fp_powers(
metrics = metrics,
variable = var_name,
group_levels = cat_info$original_levels
)
candidate_metrics[[interaction_type]] <- metrics
candidate_full_fits[[interaction_type]] <- fit_result
if (verbose) {
verbose_rows[[interaction_type]] <- metrics
}
# Store the fitted interaction model regardless of whether it is retained.
candidate_models[[interaction_type]] <-
fit_result$test_results$interaction_model
# For p-value selection, the only candidate is the per-variable winner if
# its p-value is finite/non-missing.
if (criterion == "pvalue") {
pval <- metrics$pvalue[1L]
if (!is.na(pval)) {
best_fit <- fit_result
best_metric <- metrics
best_type <- interaction_type
best_score <- pval
}
} else if (!criterion %in% c("aic", "bic")) {
stop(
paste0(
"! `criterion` must be one of 'pvalue', 'aic', or 'bic'; got '",
criterion,
"'."
),
call. = FALSE
)
}
}
# -------------------------------------------------------------------------
# Resolve AIC/BIC winner for the current variable
# -------------------------------------------------------------------------
# There is only one active candidate, so this checks whether its improvement
# statistic is finite and records it as the winner.
if (criterion %in% c("aic", "bic")) {
m <- candidate_metrics[[active_type]]
if (!is.null(m)) {
if (!ic_col %in% names(m)) {
stop(
paste0(
"Internal error: interaction metrics are missing `",
ic_col,
"`."
),
call. = FALSE
)
}
dIC <- m[[ic_col]][1L]
if (is.finite(dIC)) {
best_type <- active_type
best_fit <- candidate_full_fits[[active_type]]
best_metric <- m
best_score <- dIC
}
}
}
# -------------------------------------------------------------------------
# Verbose per-variable candidate table
# -------------------------------------------------------------------------
if (verbose) {
mfp2_message_capture(
format_candidate_table(
verbose_rows,
criterion = criterion,
digits = digits,
best_type = best_type
)
)
}
# -------------------------------------------------------------------------
# Immediate final selection when p-values are not being adjusted
# -------------------------------------------------------------------------
retained <- NA
if (!adjusting_pvals && !is.null(best_fit)) {
retained <- if (criterion == "pvalue") {
best_score < p_interact
} else {
best_score > min_improvement
}
} else if (!adjusting_pvals && is.null(best_fit)) {
retained <- FALSE
if (verbose) {
mfp2_message(" >> model fit failed")
}
}
list(
candidate_metrics = candidate_metrics,
candidate_models = candidate_models,
best_fit = best_fit,
best_metric = best_metric,
best_type = best_type,
best_score = best_score,
retained = retained
)
}
#' Select Interactions Using Adjusted P-values
#'
#' Adjusts interaction p-values using \code{stats::p.adjust()} and selects
#' interactions whose adjusted p-values are strictly below \code{p_interact}.
#' Updates the per-variable results and selected-model lists.
#'
#' @param var_winners Named list of per-variable fitted results and comparison
#' metrics.
#' @param all_metrics_list List of comparison-metric data frames.
#' @param all_idx Number of populated entries in \code{all_metrics_list}.
#' @param interaction_vars Character vector naming interaction terms in
#' evaluation order.
#' @param n_vars Number of interaction variables.
#' @param n_types Number of evaluated forms per variable.
#' @param p_adjust_method Adjustment method passed to \code{stats::p.adjust()}.
#' @param p_interact Significance threshold for adjusted p-values.
#'
#' @return A list containing:
#' \describe{
#' \item{\code{var_winners}}{Per-variable results updated with adjusted
#' p-values and scores.}
#' \item{\code{all_candidate_metrics}}{Complete comparison-metric table,
#' including a \code{p_adjusted} column.}
#' \item{\code{best_idx}}{Number of selected interactions.}
#' \item{\code{best_metrics_list}, \code{best_interaction_model},
#' \code{center_vals_list}}{Comparison metrics, fitted models, and centring
#' constants for selected interactions.}
#' }
#'
#' @keywords internal
#' @noRd
finalize_adjusted_pvalue_selection <- function(var_winners,
all_metrics_list,
all_idx,
interaction_vars,
n_vars,
n_types,
p_adjust_method,
p_interact) {
all_candidate_metrics <- bind_metric_rows(all_metrics_list[seq_len(all_idx)])
if (nrow(all_candidate_metrics) > 0L &&
"pvalue" %in% names(all_candidate_metrics)) {
all_candidate_metrics$p_adjusted <- NA_real_
valid_p <- is.finite(all_candidate_metrics$pvalue)
n_planned_tests <- length(interaction_vars) * n_types
if (any(valid_p)) {
all_candidate_metrics$p_adjusted[valid_p] <- if (p_adjust_method == "none") {
all_candidate_metrics$pvalue[valid_p]
} else {
stats::p.adjust(
all_candidate_metrics$pvalue[valid_p],
method = p_adjust_method,
n = n_planned_tests
)
}
}
# Copy adjusted p-values back into the per-variable winners so the final
# selection and verbose summary use adjusted scores.
for (vn in interaction_vars) {
rows_idx <- which(all_candidate_metrics$variable == vn &
is.finite(all_candidate_metrics$p_adjusted))
if (length(rows_idx) == 0L) next
win_idx <- rows_idx[1L]
w <- var_winners[[vn]]
if (!is.null(w$fit)) {
w$metric <- all_candidate_metrics[win_idx, , drop = FALSE]
w$score <- all_candidate_metrics$p_adjusted[win_idx]
var_winners[[vn]] <- w
}
}
}
# Rebuild retained-model containers from adjusted p-value decisions.
best_idx <- 0L
best_metrics_list <- vector("list", n_vars)
best_interaction_model <- stats::setNames(vector("list", n_vars), interaction_vars)
center_vals_list <- stats::setNames(vector("list", n_vars), interaction_vars)
for (vn in interaction_vars) {
w <- var_winners[[vn]]
if (is.null(w$fit) || is.null(w$metric)) next
padj_val <- w$metric$p_adjusted[1L]
if (!is.na(padj_val) && padj_val < p_interact) {
best_idx <- best_idx + 1L
best_metrics_list[[best_idx]] <- w$metric
best_interaction_model[[vn]] <- w$fit$test_results$interaction_model
center_vals_list[[vn]] <- w$center_vals
}
}
list(
var_winners = var_winners,
all_candidate_metrics = all_candidate_metrics,
best_idx = best_idx,
best_metrics_list = best_metrics_list,
best_interaction_model = best_interaction_model,
center_vals_list = center_vals_list
)
}
#' Print the Final Interaction Summary
#'
#' Prints a summary of interaction comparisons. For AIC or BIC selection,
#' shows criterion improvements for selected interactions. For p-value
#' selection, shows p-values and selection decisions, including adjusted
#' p-values when applicable.
#'
#' @param var_winners Named list of per-variable fitted results and comparison
#' metrics.
#' @param interaction_vars Character vector of tested terms in display order.
#' @param mode Summary format: \code{"ic"} or \code{"pvalue"}.
#' @param ic_col,ic_label Metric column name and display label for AIC or BIC
#' improvements. Used when \code{mode = "ic"}.
#' @param min_improvement Selection threshold for AIC or BIC improvements.
#' @param p_interact Significance threshold for p-value selection.
#' @param p_adjust_method P-value adjustment method.
#' @param digits Number of decimal places for displayed statistics.
#' @param show_models Whether to print selected-model summaries after the table.
#' @param best_interaction_model Named list of selected interaction models.
#'
#' @return Invisibly returns \code{NULL} after printing the summary.
#'
#' @keywords internal
#' @noRd
print_interaction_step3_summary <- function(var_winners,
interaction_vars,
mode = c("ic", "pvalue"),
ic_col = NULL,
ic_label = NULL,
min_improvement = NULL,
p_interact = NULL,
p_adjust_method = NULL,
digits = 3,
show_models = FALSE,
best_interaction_model = NULL) {
mode <- match.arg(mode)
rule_thick <- strrep("=", 70)
rule_thin <- strrep("-", 70)
show_adjusted <- mode == "pvalue" &&
is.character(p_adjust_method) &&
length(p_adjust_method) == 1L &&
!is.na(p_adjust_method) &&
!identical(tolower(p_adjust_method), "none")
mfp2_message("")
mfp2_message(rule_thick)
mfp2_message(" STEP 3: Interaction Summary")
mfp2_message(rule_thick)
if (mode == "ic") {
mfp2_message(sprintf(
" %-12s %-8s %12s %10s",
"Variable", "Type", ic_label, "selected"
))
} else if (show_adjusted) {
mfp2_message(sprintf(
" %-12s %-8s %12s %12s %10s",
"Variable", "Type", "p_raw", "p_adjusted", "selected"
))
} else {
mfp2_message(sprintf(
" %-12s %-8s %12s %10s",
"Variable", "Type", "p-value", "selected"
))
}
mfp2_message(rule_thin)
for (vn in interaction_vars) {
w <- var_winners[[vn]]
if (is.null(w$fit) || is.null(w$metric)) {
if (mode == "ic") {
mfp2_message(sprintf(
" %-12s %-8s %12s %10s",
vn, "---", "NA", "NA"
))
} else if (show_adjusted) {
mfp2_message(sprintf(
" %-12s %-8s %12s %12s %10s",
vn, "---", "NA", "NA", "NA"
))
} else {
mfp2_message(sprintf(
" %-12s %-8s %12s %10s",
vn, "---", "NA", "NA"
))
}
next
}
type_label <- format_type_label(w$type)
if (mode == "ic") {
ic_val <- if (ic_col %in% names(w$metric)) {
w$metric[[ic_col]][1L]
} else {
NA_real_
}
selected <- if (is.finite(ic_val) && ic_val > min_improvement) {
"Yes"
} else {
"No"
}
mfp2_message(sprintf(
" %-12s %-8s %12s %10s",
vn,
type_label,
format_print_decimal(ic_val, digits),
selected
))
} else {
p_raw <- w$metric$pvalue[1L]
p_adjusted <- if ("p_adjusted" %in% names(w$metric)) {
w$metric$p_adjusted[1L]
} else {
p_raw
}
p_for_selection <- if (show_adjusted) p_adjusted else p_raw
selected <- if (is.finite(p_for_selection) &&
p_for_selection < p_interact) {
"Yes"
} else {
"No"
}
if (show_adjusted) {
mfp2_message(sprintf(
" %-12s %-8s %12s %12s %10s",
vn,
type_label,
format_print_pvalue(p_raw, digits),
format_print_pvalue(p_adjusted, digits),
selected
))
} else {
mfp2_message(sprintf(
" %-12s %-8s %12s %10s",
vn,
type_label,
format_print_pvalue(p_raw, digits),
selected
))
}
}
}
mfp2_message(rule_thin)
mfp2_message("")
if (show_models) {
for (vn in names(Filter(Negate(is.null), best_interaction_model))) {
w <- var_winners[[vn]]
fit_obj <- w$fit$test_results$interaction_model$fit
if (!is.null(fit_obj)) {
type_label <- format_type_label(w$type)
mfp2_message(" Interaction model (", vn, ", ", type_label, "):")
mfp2_message(strrep("-", 50))
mfp2_message_capture(print(summary(fit_obj)))
mfp2_message("")
}
}
}
invisible(NULL)
}
# -----------------------------------------------------------------------------
# MFPI adjustment-block cache helpers -----------------------------------------
# -----------------------------------------------------------------------------
#' Cache Transformed MFPI Adjustment Terms
#'
#' Transforms each selected adjustment term once and stores its complete
#' design block by term name. Group dummy terms are excluded because
#' interaction models add group main effects separately.
#'
#' The cached blocks allow \code{mfpi_make_xadj_current()} to assemble each
#' interaction's adjustment matrix while excluding the term being tested.
#' Categorical contrasts and multiple transformed columns belonging to one
#' term are kept together.
#'
#' @param x Numeric predictor matrix with shifts and scales already applied.
#' @param selected_vars Character vector naming selected adjustment terms.
#' @param group_dummy_names Names of group dummy columns to exclude, or
#' \code{NULL}.
#' @param group_dummy_term Character string naming the group dummy term.
#' @param term_to_columns Named list mapping adjustment terms to predictor
#' columns.
#' @param skip_adjustment Whether to skip transformation and return an empty
#' cache.
#' @param scale Named numeric vector of scale factors used to restore shifted,
#' unscaled predictor values before transformation, or \code{NULL}.
#' @param adj_fp_powers Named list of selected adjustment powers.
#' @param center Named logical vector controlling adjustment-term centring.
#' @param acd_vars Named logical vector identifying ACD adjustment terms.
#' @param adj_zero Named logical vector of fitted zero-handling flags.
#' @param adj_catzero Fitted zero-indicator settings for adjustment terms.
#' @param adj_spike Named logical vector of fitted spike-at-zero flags.
#' @param adj_spike_decision Named integer vector of fitted spike-at-zero
#' decisions.
#' @param adj_acd_parameter Named list of fitted ACD transformation parameters,
#' or \code{NULL}.
#'
#' @return A list containing:
#' \describe{
#' \item{\code{selected_adj_vars}}{Selected adjustment term names after
#' excluding group dummy terms.}
#' \item{\code{adj_blocks}}{Named list containing the complete transformed
#' predictor block for each adjustment term.}
#' }
#'
#' @keywords internal
#' @noRd
mfpi_build_adjustment_block_cache <- function(x,
selected_vars,
group_dummy_names,
group_dummy_term,
term_to_columns,
skip_adjustment,
scale,
adj_fp_powers,
center,
acd_vars,
adj_zero,
adj_catzero,
adj_spike,
adj_spike_decision,
adj_acd_parameter) {
# Normalize the group dummy names. In some edge cases there may be no dummy
# matrix or no column names; treating that as an empty exclusion set keeps the
# downstream setdiff() simple.
if (is.null(group_dummy_names)) {
group_dummy_names <- character(0L)
}
# Adjustment variables are selected adjustment-model variables excluding the
# group dummies. The current cont_var is not removed here; it is removed later
# by mfpi_make_xadj_current(), because that removal changes per loop iteration.
selected_adj_vars <- setdiff(
selected_vars,
c(group_dummy_term, group_dummy_names)
)
selected_adj_vars <- unique(
selected_adj_vars[!is.na(selected_adj_vars) & nzchar(selected_adj_vars)]
)
# Always return the same cache structure, even when adjustment is skipped.
# This keeps evaluate_interactions() simple and avoids special cases inside
# the interaction_vars loop.
adj_blocks <- stats::setNames(
vector("list", length(selected_adj_vars)),
selected_adj_vars
)
if (isTRUE(skip_adjustment) || length(selected_adj_vars) == 0L) {
return(list(
selected_adj_vars = selected_adj_vars,
adj_blocks = adj_blocks
))
}
for (v in selected_adj_vars) {
cols <- term_to_columns[[v]]
# Work one conceptual term at a time. A categorical term contributes all of
# its raw contrast columns as one cached block; a continuous singleton uses
# its selected FP transformation and optional extensions.
x_one <- x[, cols, drop = FALSE]
scale_cols <- stats::setNames(rep(1, length(cols)), cols)
if (!is.null(scale)) {
shared <- intersect(cols, names(scale))
scale_cols[shared] <- scale[shared]
}
x_one <- sweep(x_one, 2L, scale_cols, "*")
center_term <- collapse_option_to_terms(
if (!is.null(center)) center else {
stats::setNames(rep(FALSE, ncol(x)), colnames(x))
},
term_to_columns[v],
"center"
)
expanded_adjustment <- expand_term_metadata_to_columns(
term_to_columns = term_to_columns[v],
powers = stats::setNames(list(adj_fp_powers[[v]]), v),
raw_columns = cols,
center = center_term,
acdx = acd_vars,
zero = adj_zero,
catzero = adj_catzero,
spike = adj_spike,
spike_decision = adj_spike_decision,
acd_parameter = adj_acd_parameter
)
power_cols <- expanded_adjustment$powers
center_cols <- expanded_adjustment$center
acd_cols <- expanded_adjustment$acdx
zero_cols <- expanded_adjustment$zero
catzero_cols <- expanded_adjustment$catzero
spike_cols <- expanded_adjustment$spike
spike_decision_cols <- expanded_adjustment$spike_decision
acd_parameter_cols <- expanded_adjustment$acd_parameter
transformed <- transform_matrix(
x = x_one,
power_list = power_cols,
center = center_cols,
acdx = acd_cols,
zero = zero_cols,
catzero = catzero_cols,
spike = spike_cols,
spike_decision = spike_decision_cols,
keep_x_order = FALSE,
acd_parameter_list = acd_parameter_cols,
reset_zero = FALSE,
check_binary = TRUE
)
block <- if (is.null(transformed)) NULL else transformed$x_transformed
# A variable may theoretically produce no fitted columns, for example if it
# was selected but represented in a degenerate way after transformation.
# Store NULL explicitly so the assembler can drop it cleanly.
if (is.null(block) || ncol(block) == 0L) {
adj_blocks[[v]] <- NULL
next
}
block <- as.matrix(block)
storage.mode(block) <- "double"
if (is.null(colnames(block)) ||
anyNA(colnames(block)) ||
any(!nzchar(colnames(block)))) {
stop(
paste0(
"! Internal error: transformed adjustment block for `", v,
"` has missing or empty column names."
),
call. = FALSE
)
}
if (anyNA(block) || any(!is.finite(block))) {
stop(
paste0(
"! Internal error: non-finite values in transformed adjustment ",
"block for `", v, "`."
),
call. = FALSE
)
}
adj_blocks[[v]] <- block
}
# Column names must be unique once blocks are cbind()ed. Duplicates would make
# coefficient lookup and downstream prediction reconstruction ambiguous.
adj_colnames <- unlist(
lapply(adj_blocks, function(z) {
if (is.null(z)) character(0L) else colnames(z)
}),
use.names = FALSE
)
if (length(adj_colnames) > 0L && anyDuplicated(adj_colnames)) {
stop(
"! Internal error: duplicated transformed adjustment-column names.",
call. = FALSE
)
}
list(
selected_adj_vars = selected_adj_vars,
adj_blocks = adj_blocks
)
}
#' Assemble the MFPI Adjustment Matrix for One Interaction
#'
#' Combines cached adjustment blocks, excluding the complete block for the
#' term being tested.
#'
#' @param var_name Character string naming the interaction term.
#' @param adjustment_cache List returned by
#' \code{mfpi_build_adjustment_block_cache()}.
#' @param skip_adjustment Whether to return \code{xadj} unchanged instead of
#' assembling cached blocks.
#' @param xadj Existing adjustment matrix or \code{NULL}, used when
#' \code{skip_adjustment = TRUE}.
#'
#' @return A numeric adjustment matrix, or \code{NULL} if no adjustment terms
#' remain. When \code{skip_adjustment = TRUE}, returns \code{xadj} unchanged.
#'
#' @keywords internal
#' @noRd
mfpi_make_xadj_current <- function(var_name,
adjustment_cache,
skip_adjustment,
xadj = NULL) {
if (isTRUE(skip_adjustment)) {
return(xadj)
}
if (!is.character(var_name) || length(var_name) != 1L ||
is.na(var_name) || !nzchar(var_name)) {
stop("`var_name` must be a single non-empty character string.",
call. = FALSE)
}
if (!is.list(adjustment_cache) ||
!all(c("selected_adj_vars", "adj_blocks") %in% names(adjustment_cache))) {
stop(
"`adjustment_cache` must be returned by `mfpi_build_adjustment_block_cache()`.",
call. = FALSE
)
}
selected_adj_vars <- adjustment_cache$selected_adj_vars
adj_blocks <- adjustment_cache$adj_blocks
# Remove the current tested variable from its own adjustment set. This drops
# all derived columns for that source variable, not just columns matching a
# transformed-name pattern.
adj_vars_current <- setdiff(selected_adj_vars, var_name)
if (length(adj_vars_current) == 0L) {
return(NULL)
}
blocks <- adj_blocks[adj_vars_current]
blocks <- blocks[!vapply(blocks, is.null, logical(1L))]
if (length(blocks) == 0L) {
return(NULL)
}
out <- do.call(cbind, blocks)
if (is.null(out) || ncol(out) == 0L) {
return(NULL)
}
out <- as.matrix(out)
storage.mode(out) <- "double"
if (is.null(colnames(out)) ||
anyNA(colnames(out)) ||
any(!nzchar(colnames(out)))) {
stop(
"! Internal error: current adjustment matrix has missing column names.",
call. = FALSE
)
}
if (anyDuplicated(colnames(out))) {
stop(
"! Internal error: current adjustment matrix has duplicated columns.",
call. = FALSE
)
}
if (anyNA(out) || any(!is.finite(out))) {
stop(
paste0(
"! Internal error: current adjustment matrix for `", var_name,
"` contains non-finite values."
),
call. = FALSE
)
}
out
}
#' Add Cause-and-Fix Guidance to a Rank-Deficient MFPI Error
#'
#' Evaluates `expr`; if it signals `mfpi_rank_deficient_error`, re-signals the
#' same error with guidance appended when the failure has the typical
#' signature of an automatic shift: the variable was shifted automatically,
#' its smallest shifted value is very close to 0 relative to its range (below
#' 1%), and the selected powers include a negative or log (0) power. Otherwise
#' the error is re-signalled unchanged. No shift value is computed or
#' suggested; the guidance only names the cause and the available options.
#'
#' @param expr Expression to evaluate (the `flex_fit()` call).
#' @param var_name Interaction variable name.
#' @param interaction_spec Interaction specification for `var_name`.
#' @param interaction_form Resolved interaction form (`"fp1"`, `"fp2"`, ...).
#' @param x Internal (shifted and scaled) training matrix.
#' @param scale,shift Named scale and shift vectors used at fit time.
#' @param shift_automatic Named logical vector: `TRUE` where the shift was
#' estimated automatically rather than supplied by the user.
#' @param zero_var Logical; whether `var_name` uses zero handling.
#' @keywords internal
#' @noRd
mfpi_with_rank_hint <- function(expr, var_name, interaction_spec,
interaction_form, x, scale, shift,
shift_automatic, zero_var = FALSE) {
tryCatch(
expr,
mfpi_rank_deficient_error = function(e) {
hint <- mfpi_rank_deficient_hint(
powers = e$selected_powers,
var_name = var_name,
interaction_spec = interaction_spec,
interaction_form = interaction_form,
x = x,
scale = scale,
shift = shift,
shift_automatic = shift_automatic,
zero_var = zero_var
)
if (!is.null(hint)) e$message <- paste0(e$message, "\n", hint)
stop(e)
}
)
}
#' Build the Automatic-Shift Guidance for a Rank-Deficient MFPI Design
#'
#' @inheritParams mfpi_with_rank_hint
#' @param powers Selected FP powers attached to the error, or `NULL`.
#' @return A character scalar, or `NULL` when the failure does not match the
#' automatic-shift signature.
#' @keywords internal
#' @noRd
mfpi_rank_deficient_hint <- function(powers, var_name, interaction_spec,
interaction_form, x, scale, shift,
shift_automatic, zero_var = FALSE) {
if (is.null(interaction_spec) || !identical(interaction_spec$kind, "continuous")) {
return(NULL)
}
if (is.null(powers) || !any(powers <= 0)) return(NULL)
if (is.null(shift_automatic) || !isTRUE(shift_automatic[var_name])) return(NULL)
shift_v <- if (!is.null(shift) && var_name %in% names(shift)) unname(shift[[var_name]]) else 0
scale_v <- if (!is.null(scale) && var_name %in% names(scale)) unname(scale[[var_name]]) else 1
if (!is.finite(shift_v) || shift_v <= 0 || !var_name %in% colnames(x)) return(NULL)
x_plus <- as.numeric(x[, var_name]) * scale_v
if (isTRUE(zero_var)) x_plus <- x_plus[x_plus != 0]
x_plus <- x_plus[is.finite(x_plus)]
if (length(x_plus) < 2L) return(NULL)
value_range <- diff(range(x_plus))
smallest <- min(x_plus)
if (!(value_range > 0) || smallest >= 0.01 * value_range) return(NULL)
fmt <- function(v) format(signif(v, 3), scientific = abs(v) < 1e-3 && v != 0)
simpler <- if (identical(interaction_form, "fp2")) {
paste0("`interaction_forms = c(", var_name, " = \"fp1\")` or `\"linear\"`")
} else {
paste0("`interaction_forms = c(", var_name, " = \"linear\")`")
}
paste0(
"i Likely cause: `", var_name, "` was shifted automatically (shift = ",
fmt(shift_v), "), which places its smallest value at ", fmt(smallest),
", very close to 0 relative to its range (", fmt(value_range), "). ",
"The selected power(s) (", paste(powers, collapse = ", "), ") include a ",
"negative or log power, which gives the observations near 0 extreme values.\n",
"i Possible fixes:\n",
" * supply your own shift for `", var_name, "` so that its smallest value ",
"is not close to 0: `fp(", var_name, ", shift = ...)` in a formula, or ",
"`shift = c(", var_name, " = ...)` with the matrix interface;\n",
" * use a simpler interaction form, e.g. ", simpler, ";\n",
" * try another `flex` level."
)
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.