Nothing
#' Test Interactions with a Categorical Grouping Variable
#'
#' Test whether the association between an outcome and a continuous, binary,
#' or categorical predictor differs between groups. Fractional polynomials
#' (FPs) allow nonlinear associations for continuous predictors.
#'
#' @details
#' `mfpi()` first selects an adjustment model using [mfp2()]. It then tests
#' each variable in `interaction_vars` separately for interaction with
#' `group_var`, comparing a common association across groups with
#' group-specific associations.
#'
#' Both models include group main effects and the selected adjustment terms.
#' The adjustment terms are held fixed, except that the variable being tested
#' is modelled separately as part of the interaction comparison.
#' A separate interaction model is returned for each tested variable;
#' selected interactions are not combined into a single model.
#'
#' @param x A numeric predictor matrix or data frame for the default method,
#' without an intercept column. Include the grouping variable, all variables
#' to test for interaction, and any adjustment variables. Data frames also
#' accept logical predictors and a factor or character grouping variable.
#' Represent other categorical predictors using numeric dummy variables.
#' For categorical predictors represented by multiple columns, use
#' `term_groups` to identify which columns belong together so that each
#' predictor is assessed as a whole rather than as separate dummy variables.
#' @param y The response for the default method, with one observation per row
#' of `x`. Supply a response appropriate for `family`: a numeric response
#' for ordinary GLMs, a binary response or two-column matrix of integer
#' success and failure counts for binomial models, class labels or a
#' class-count matrix for multinomial models, ordered categories for ordinal
#' models, or a [survival::Surv()] object for survival models.
#' @param formula A model formula containing the response, grouping variable,
#' interaction variables, and adjustment variables. Supply original variables
#' in `data`; categorical predictors are encoded and assessed as complete
#' terms. Use `fp()` or `fp2()` to specify variable-specific adjustment-model
#' and preprocessing settings. These settings override the corresponding
#' global defaults but do not determine the interaction form, which is set
#' by `interaction_forms`. Include offsets using `offset(...)` and survival
#' strata using `strata(...)`. See *Formula interface*.
#' @param data A data frame containing the variables used in `formula`.
#' Formula expressions, weights, and subsetting expressions are evaluated
#' using these data.
#' @param group_var A single character string naming the categorical grouping
#' variable whose interactions with the variables in `interaction_vars`
#' are to be tested. It must be included in `x` or `formula`. This argument
#' must be supplied. The variable must have at least two observed groups
#' in the data used for fitting and cannot also appear in `interaction_vars`
#' or belong to `term_groups`. The reference is the first observed factor
#' level, the first observed character value, or the smallest observed
#' logical or numeric value. Supply a factor with the desired level order
#' to choose the reference explicitly.
#' @param interaction_vars A non-empty character vector naming variables to
#' test separately for interaction with `group_var`. This argument must be
#' supplied. Variables must be included in `x` or `formula`. For categorical
#' predictors, name the complete term rather than individual contrast
#' columns. Each analysis includes group main effects and the selected
#' adjustment terms, excluding the variable currently being tested. The
#' resulting interactions are not combined into a single model.
#' @param interaction_forms An optional named character vector specifying
#' the interaction form for each variable tested for interaction, for example
#' `c(age = "fp1", stage = "linear")`. Use `"linear"` for a linear,
#' binary, or categorical effect, `"fp1"` for a one-term fractional
#' polynomial, or `"fp2"` for a two-term fractional polynomial, allowing
#' repeated powers. `NULL` and unspecified entries default to `"fp1"` for
#' continuous variables and `"linear"` for binary and categorical variables.
#' FP requests for binary or categorical variables are changed to `"linear"`
#' with a warning.
#' @param flex A single character string controlling FP power selection.
#' `"flex1"` selects powers in the model without interaction and reuses
#' them in the interaction model. `"flex2"` selects shared powers in the
#' interaction model and reuses them in the model without interaction.
#' `"flex3"` (default) selects powers separately for the two models but
#' uses common powers across groups in the interaction model.
#' `"flex4"` works like `"flex3"` but allows different FP powers across
#' groups. All options estimate group-specific coefficients in the
#' interaction model. Ignored for `"linear"` interactions.
#' P-values for `"flex3"` and `"flex4"` are approximate because the
#' selected models can be non-nested.
#' @param p_interact The p-value threshold for selecting interactions,
#' greater than 0 and at most 1. Default: `0.05`. Used only with
#' `criterion = "pvalue"`. An interaction is selected when its p-value
#' is below this threshold. If a multiple-testing adjustment is requested
#' through `p_adjust_method`, the adjusted p-value is compared with the
#' threshold.
#' @param min_improvement A single finite positive minimum improvement required
#' to select an interaction with `criterion = "aic"` or `"bic"`.
#' `NULL` uses 2. An interaction is selected when the information criterion
#' for the model without interaction minus that for the interaction model
#' is strictly greater than this value. Unused with `criterion = "pvalue"`;
#' it does not affect adjustment-model selection.
#' @param include_group_var A logical value indicating whether to force the
#' grouping variable into the initial adjustment model. Default: `FALSE`,
#' which excludes it from that stage. Group main effects are included in
#' every subsequent interaction comparison regardless of this setting.
#' @param show_models A logical value indicating whether to print summaries
#' of selected interaction models. Default: `FALSE`. Printing requires
#' `verbose = TRUE`; this setting does not change which models are fitted
#' or returned.
#' @param weights An optional numeric vector of observation weights greater
#' than zero, with one value per observation in the original data.
#' `NULL` gives equal weights. Weights are used in both adjustment-model
#' selection and interaction fitting. In the formula method, weights can
#' refer to a column in `data`.
#' @param offset An optional numeric offset for the default method, added
#' to the linear predictor with its coefficient fixed at one in both
#' adjustment-model selection and interaction fitting. Supply one value
#' per observation in the original data. For multinomial models, supply
#' a matrix with one row per observation and either `C` or `C - 1` columns,
#' where `C` is the number of outcome classes. `NULL` specifies no offset.
#' In the formula method, include `offset(...)` in the formula.
#' @param cycles A positive integer giving the maximum number of MFP fitting
#' cycles used to select the adjustment model. Default: 10.
#' @param scale Predictor scaling factors greater than zero, or `NULL` for
#' automatic scaling. Use `1` to disable scaling. In the default method,
#' supply a single value for all predictors or a named numeric vector
#' specifying values for individual columns of `x`. Unspecified columns
#' use automatic scaling. In the formula method, supply a single value
#' or `NULL`; use `fp()` or `fp2()` for variable-specific settings.
#' Predictors with structural zeros use an automatic scale of 1 unless
#' a scale is supplied explicitly. Binary predictors, the grouping
#' variable, and categorical interaction variables are not scaled.
#' @param shift Constants added to predictors before scaling and FP
#' transformation, or `NULL` for automatic shifting. Use `0` to disable
#' shifting. In the default method, supply a single value for all predictors
#' or a named numeric vector specifying values for individual columns of `x`.
#' Unspecified columns use automatic shifting. In the formula method, supply
#' a single value or `NULL`; use `fp()` or `fp2()` for variable-specific
#' settings. Values used in nonlinear FP transformations must be positive
#' after shifting. A supplied shift is not increased automatically.
#' Predictors with structural zeros, binary predictors, the grouping
#' variable, and predictors modelled only linearly are not shifted.
#' @param df The maximum FP complexity allowed in the adjustment model:
#' `1` for linear, `2` for FP1, `4` for FP2, or a positive even integer
#' `2m` for an FP of degree `m`. Default: `4`. In the default method,
#' supply a single value for all predictors or a named numeric vector
#' specifying values for individual columns of `x`. Unspecified columns
#' use the default; categorical terms are treated as linear. In the formula
#' method, supply a single value; use `fp()` or `fp2()` for variable-specific
#' settings. Use `interaction_forms` to specify the interaction form.
#' @param center Whether to centre transformed predictors. Default: `TRUE`.
#' In the default method, supply a single logical value for all predictors
#' or a named logical vector specifying values for individual columns of `x`.
#' Unspecified columns use `TRUE`. In the formula method, supply a single
#' value; use `fp()` or `fp2()` for variable-specific settings.
#' For interaction functions, `center_type` determines the reference mean.
#' Binary and categorical interaction variables are not centred.
#' For predictors with structural zeros, the mean includes zero observations
#' and is subtracted from every observation.
#' @param subset An optional logical vector indicating which observations
#' to include, or a vector of unique positive row numbers. Logical values
#' must not be missing, and row numbers must be within the data range.
#' `NULL` uses all observations. The formula method also accepts an
#' expression using `data`. Supply responses, weights, offsets, and strata
#' for the original data; the same subset is applied to all of them.
#' At least five observations and two groups must remain, with at least
#' two observations per group, or three if any FP2 interaction is requested.
#' These minimum counts do not guarantee that the models can be fitted.
#' @param family The regression family or model. Default: `"gaussian"`.
#' Supported GLM families are `"gaussian"`, `"binomial"`, `"poisson"`,
#' `"Gamma"`, and `"inverse.gaussian"`, supplied as a name, function,
#' or family object. Use [negbin_family()] for negative-binomial
#' regression with a `"log"`, `"sqrt"`, or `"identity"` link (requires
#' `fastglm`); `"negbin"` is shorthand for `negbin_family(link = "log")`.
#' Use `"multinomial"` or [multinomial_family()]
#' for outcomes with at least three classes, supplied as class labels
#' or a matrix of class counts.
#' Use `"ordinal"` or [ordinal_family()] for ordered outcomes with at
#' least three categories (requires `rms` version 7.0-0 or later).
#' An ordered factor sets the category order; otherwise numeric categories
#' are ordered numerically and character or unordered-factor categories
#' alphabetically.
#' Use `"cox"` for right-censored survival data or [survreg_family()]
#' for parametric survival regression. Both require a [survival::Surv()]
#' response. The response must meet the selected family's requirements.
#' Quasi-likelihood, GEE, and Fine--Gray models are not supported.
#' @param fitter The GLM fitting method: `"base"` (default) or `"fastglm"`.
#' The latter requires the optional `fastglm` package. Ordinary GLMs warn
#' and retry with the base fitter if `fastglm` is unavailable or fitting
#' fails. Negative-binomial models require `fastglm` and select it
#' automatically. Survival models are unaffected by this argument.
#' @param criterion The selection criterion for the adjustment model and
#' interactions: `"pvalue"` (default), `"aic"`, or `"bic"`.
#' With `"pvalue"`, `select` and `alpha` control adjustment-model selection,
#' while `p_interact` and `p_adjust_method` control interaction selection.
#' With `"aic"` or `"bic"`, `min_improvement` sets the improvement required
#' to select an interaction.
#' @param select The p-value threshold for retaining variables in the
#' adjustment model, between 0 and 1 inclusive. Default: `0.05`.
#' Used only with `criterion = "pvalue"`; setting it to `1` retains the
#' variable. In the default method, supply a single value for all predictors
#' or a named numeric vector specifying values for individual columns of `x`.
#' Unspecified columns use `0.05`. In the formula method, supply a single
#' value; use `fp()` or `fp2()` for variable-specific settings.
#' Use `p_interact` to set the threshold for selecting interactions.
#' @param alpha The p-value threshold for selecting the FP degree in the
#' adjustment model, between 0 and 1 inclusive. Default: `0.05`.
#' Used only with `criterion = "pvalue"`. Setting `alpha = 1` forces the
#' maximum FP degree allowed by `df`, but the variable can still be removed
#' during variable selection. Use `select = 1` or `keep` to ensure that it
#' remains in the model. In the default method, supply a single value for
#' all predictors or a named numeric vector specifying values for individual
#' columns of `x`. Unspecified columns use `0.05`. In the formula method,
#' supply a single value; use `fp()` or `fp2()` for variable-specific settings.
#' Use `interaction_forms` to specify the interaction form.
#' @param keep An optional character vector naming predictors that must
#' remain in the initial adjustment model. For a categorical predictor,
#' naming the complete term or any of its dummy variables retains the
#' whole term. FP degrees and powers are still selected. The default is
#' `NULL`, which does not force any predictors to remain in the model.
#' @param term_groups An optional named list grouping dummy variables for
#' categorical predictors in the default method, for example
#' `list(stage = c("stageII", "stageIII"))`. This ensures each predictor
#' is assessed as a whole. Use the list name, such as `"stage"`, in
#' `interaction_vars` to test the complete predictor. Each column can belong
#' to only one group, and `group_var` cannot be included. Grouped predictors
#' are linear and cannot use special transformations or `force_max_fp_vars`.
#' Default: `NULL`. The formula method groups categorical predictors
#' automatically.
#' @param force_max_fp_vars An optional character vector naming adjustment
#' variables that must remain in the model at the maximum FP degree allowed
#' by `df`, regardless of the selection criterion. FP powers are still
#' selected from the data. The default is `NULL`. For spike-at-zero variables,
#' the full permitted model is retained. This option cannot be used for
#' grouped categorical predictors. In the formula method, you can also request
#' the maximum FP degree for individual variables through `fp()` or `fp2()`.
#' This argument does not change the interaction form specified by
#' `interaction_forms`.
#' @param xorder The order in which adjustment terms are assessed:
#' `"ascending"` (default) orders terms from smallest to largest p-value
#' for their contribution to the initial full linear model;
#' `"descending"` reverses that order; `"original"` preserves predictor
#' or formula term order. Each ordering p-value compares the full linear
#' model with a model omitting the complete term while retaining the others.
#' @param powers An optional named list of candidate FP powers, for example
#' `list(age = c(0, 0.5, 1))`. The default is `NULL`, which uses
#' `c(-2, -1, -0.5, 0, 0.5, 1, 2, 3)` for all variables. Unspecified
#' variables also use these powers. Power `0` represents the natural
#' logarithm, and power `1` represents a linear function. These powers
#' are used for both adjustment and interaction functions. FP2 models
#' allow repeated powers. In the formula method, powers specified in
#' `fp()` or `fp2()` override this argument for the same variable.
#' @param ties The method for handling tied event times in Cox models:
#' `"efron"` (default) or `"breslow"`. Ignored for other families.
#' @param strata Optional survival-model strata for the default method.
#' Supply a vector of group labels or a matrix or data frame of grouping
#' variables, with one row per observation in the original data and no
#' missing values. The default is `NULL`, meaning no stratification.
#' Each stratum has its own baseline hazard in Cox models or scale
#' parameter in `survreg` models. In the formula method, use
#' `strata(...)` in the formula.
#' @param nocenter A numeric vector of values used to determine which
#' predictor columns the Cox fitter leaves uncentred. A column is not
#' centred if all its values are in this vector. The default is
#' `c(-1, 0, 1)`, as in [survival::coxph()]. Use `NULL` to allow centring
#' of all columns. Applies only to Cox models and is separate from FP
#' centring controlled by `center` and `center_type`.
#' @param acd_vars An optional character vector naming adjustment variables
#' to transform using an approximate cumulative distribution (ACD).
#' The default is `NULL`, meaning no ACD transformations are requested.
#' This argument is available only in the default method; in the formula
#' method, use `fp(variable, acd = TRUE)`. For variables with structural
#' zeros, the ACD is estimated using positive values only. ACD transformations
#' cannot be used for grouped categorical predictors and are disabled with
#' a warning for variables tested for interaction.
#' @param zero_vars An optional character vector naming variables whose
#' continuous function applies only to positive values, with zero
#' contribution at zeros before centring. Values must not be negative.
#' No separate zero indicator is added. The default is `NULL`.
#' This option supports adjustment variables and variables tested for
#' interaction. For interaction testing, each group needs at least two
#' positive observations for a linear or FP1 form, or three for FP2.
#' In the formula method, you can also use `fp(variable, zero = TRUE)`.
#' Do not list the same adjustment variable in `catzero_vars`.
#' This option is ignored for binary variables and variables without zeros.
#' @param catzero_vars An optional character vector naming adjustment
#' variables to model using a continuous function for positive values
#' and a separate indicator for zeros. Values must not be negative.
#' The default is `NULL`. Do not list the same variable in `zero_vars`.
#' In the formula method, you can also use `fp(variable, catzero = TRUE)`.
#' This option cannot be used for grouped categorical predictors and is
#' disabled with a warning for variables tested for interaction; any
#' separately requested `zero_vars` handling is retained. It is ignored
#' for binary variables and variables without zeros.
#' @param spike_vars An optional character vector naming adjustment variables
#' for spike-at-zero modelling. Values must not be negative, and the zero
#' and positive components must each meet `min_saz_prop`. Default: `NULL`.
#' In the formula method, use `fp(variable, spike = TRUE)`.
#' Not supported for binary or grouped categorical predictors, or variables
#' tested for interaction.
#' @param min_saz_prop The minimum proportion of zero and positive observations
#' required for spike-at-zero modelling. Must be greater than 0 and less
#' than 0.5. Default: `0.10`, requiring at least 10% in each component.
#' Variables that do not meet this requirement skip spike-at-zero selection.
#' @param ftest Whether to use F-tests instead of likelihood-ratio chi-square
#' tests for Gaussian adjustment-model selection and interaction testing.
#' Default: `FALSE`. Other families use chi-square tests and issue a warning
#' if `TRUE` is supplied.
#' @param control Fitting controls used in both adjustment-model selection
#' and interaction fitting. Use [stats::glm.control()],
#' [survival::coxph.control()], or [survival::survreg.control()] as appropriate.
#' Default: `NULL`, which uses the fitter's defaults. For `fastglm`, use
#' `epsilon` and `maxit`; `trace = TRUE` is not supported.
#' @param winsorize A logical value indicating whether to cap continuous
#' variables tested for interaction at the quantiles specified by
#' `winsorize_probs`. Default: `FALSE`. No observations are removed,
#' and the same limits are used for prediction. Binary, categorical,
#' and structural-zero variables are excluded.
#' @param winsorize_probs Two probabilities specifying the lower and upper
#' limits when `winsorize = TRUE`, in increasing order between 0 and 1.
#' Default: `c(0.01, 0.99)`, corresponding to the first and ninety-ninth
#' percentiles.
#' @param center_type A character string specifying how interaction functions
#' are centred: `"grand"` (default) uses means across all groups, while
#' `"group"` uses means within each group. With `"flex4"`, each group's
#' function has its own centring value. The same values are used for
#' prediction. Applies only when `center = TRUE`; binary and categorical
#' variables tested for interaction are not centred.
#' @param p_adjust_method A character string specifying the multiple-testing
#' adjustment for interaction p-values, using a method from [stats::p.adjust()],
#' such as `"holm"`, `"bonferroni"`, or `"BH"`. Default: `"none"`.
#' With `criterion = "pvalue"`, adjusted p-values are compared with
#' `p_interact`. Each variable in `interaction_vars` counts as one test,
#' including those with unavailable p-values. Unused for AIC or BIC selection.
#' @param digits A positive integer giving the number of decimal places in
#' printed interaction results, excluding FP powers and degrees of freedom.
#' Default: 3. This affects printed output rather than fitting precision.
#' @param verbose A logical value indicating whether to print fitting progress
#' and selection results. Default: `TRUE`. Set to `FALSE` to suppress this
#' output, including the model summaries requested by `show_models`.
#' @param ... Not used.
#'
#' @return
#' An object of class `"mfpi"` containing the adjustment model, interaction
#' results, and fitted interaction models. Each variable is tested separately;
#' selected interactions are not combined into a single model.
#'
#' The main components are:
#'
#' - `all_model_metrics`: results for every tested interaction, including
#' p-values, test degrees of freedom, AIC and BIC comparisons between models
#' with and without interaction, and selected FP powers.
#' - `best_model_metrics`: results for interactions that meet the selection
#' rule specified by `criterion` and its associated threshold.
#' - `all_interaction_models`: fitted interaction models for all tested
#' variables, including those whose interactions were not selected.
#' - `best_interaction_model`: fitted interaction models for variables
#' whose interactions were selected.
#' - `adjustment_model`: the initial adjustment model selected using [mfp2()].
#' Its selected terms and transformations are used in the interaction
#' analyses. It accepts prediction data on the original covariate scale.
#' - `interaction_forms`: the interaction form used for each tested variable:
#' `"linear"`, `"fp1"`, or `"fp2"`.
#' - `group_level_map`: the mapping between the internal group codes used
#' for fitting and the original group labels.
#' - `winsorize_limits`: present only when `winsorize = TRUE`; the lower and
#' upper limits used for Winsorisation, calculated after shifting and scaling. These limits
#' are reused for prediction.
#' - `criterion`: the criterion used for model selection: `"pvalue"`,
#' `"aic"`, or `"bic"`.
#' - `p_adjust_method`: the multiple-testing adjustment method used for
#' interaction p-values.
#' - `call`: the matched function call, recording the supplied arguments.
#'
#' Use `summary()` to inspect interaction results, `coef()` and `vcov()`
#' to extract coefficients and covariance matrices, and `predict()` and
#' `plot()` to examine fitted associations and differences between groups.
#'
#' @references
#' Kipruto, E., Royston, P. and Sauerbrei, W.
#' Multivariable Fractional Polynomial Interaction Models in R.
#'
#' Royston, P. and Sauerbrei, W. (2004). A new approach to modelling
#' interactions between treatment and continuous covariates in clinical trials
#' by using fractional polynomials. *Statistics in Medicine*, 23, 2509–2525.
#' \doi{10.1002/sim.1815}.
#'
#' Royston, P. and Sauerbrei, W. (2009). Two techniques for investigating
#' interactions between treatment and continuous covariates in clinical trials.
#' *The Stata Journal*, 9, 230–251.
#' \doi{10.1177/1536867X0900900204}.
#'
#' Royston, P. and Sauerbrei, W. (2013). Interaction of treatment with a
#' continuous variable: simulation study of significance level for several
#' methods of analysis. *Statistics in Medicine*, 32, 3788–3803.
#' \doi{10.1002/sim.5813}.
#'
#' Royston, P. and Sauerbrei, W. (2014). Interaction of treatment with a
#' continuous variable: simulation study of power for several methods of
#' analysis. *Statistics in Medicine*, 33, 4695–4708.
#' \doi{10.1002/sim.6308}.
#'
#' @examples
#' data("prostate")
#'
#' # Test FP1 and linear interactions with a categorical grouping variable.
#' # The grouping variable, svi, must appear in the formula and be named
#' # in group_var.
#' fit <- mfpi(
#' lpsa ~ svi + fp(age) + fp(cavol) + fp(weight) + fp(bph) + fp(cp),
#' data = prostate,
#' family = gaussian(),
#' group_var = "svi",
#' p_interact = 0.9,
#' interaction_vars = c("cavol", "age"),
#' interaction_forms = c(cavol = "fp1", age = "linear"),
#' flex = "flex1",
#' verbose = FALSE
#' )
#'
#' print(fit)
#' summary(fit)
#'
#' # Examine the cavol interaction even if it was not selected.
#' pred <- predict(
#' fit,
#' terms = "cavol",
#' model = "all",
#' type = "both",
#' grid = TRUE
#' )
#' pred$functions
#' pred$differences
#'
#' \donttest{
#' # Plot the fitted cavol functions and differences between groups.
#' if (requireNamespace("patchwork", quietly = TRUE) &&
#' requireNamespace("ggplot2", quietly = TRUE)) {
#' plot(fit, terms = "cavol")
#' }
#' }
#'
#' @seealso [mfp2()], [fp()], [coef.mfpi()], [vcov.mfpi()],
#' [predict.mfpi()], [plot.mfpi()], [summary.mfpi()],
#' [multinomial_family()], [ordinal_family()], [survreg_family()]
#'
#' @export
mfpi <- function(x, ...) {
UseMethod("mfpi", x)
}
#' Check Whether a Model Family Is Supported by MFPI
#'
#' Rejects Fine--Gray and GEE models. Fine--Gray models use a weighted partial
#' pseudo-likelihood for which the standard likelihood-ratio comparisons used
#' by MFPI are not appropriate. GEE models use estimating equations rather
#' than a full likelihood. The MFPI interface also lacks the cluster arguments
#' required for GEE fitting.
#'
#' Both families are supported by [mfp2()].
#'
#' @param family_string A character string giving the canonical family name.
#'
#' @return Invisibly returns `NULL` unless the family is Fine--Gray or GEE,
#' in which case it raises an error.
#'
#' @keywords internal
#' @noRd
validate_mfpi_family <- function(family_string) {
if (identical(family_string, "finegray")) {
stop(
"! `mfpi()` does not support Fine--Gray models.",
call. = FALSE
)
}
if (identical(family_string, "gee")) {
stop(
"! `mfpi()` does not support GEE models (`gee_family()`). ",
"GEE is available in `mfp2()`, which takes the required `id` (and ",
"optional `waves`) cluster arguments.",
call. = FALSE
)
}
invisible(NULL)
}
#' Describe MFPI Interaction Terms
#'
#' Identifies continuous, binary, and categorical interaction terms and maps
#' each term to its predictor columns. Continuous and binary terms use one
#' column; categorical terms use the complete contrast block recorded in
#' `term_to_columns`.
#'
#' @param x A numeric predictor matrix.
#' @param interaction_vars Character vector naming the interaction terms.
#' @param term_to_columns A named list mapping terms to predictor column names.
#'
#' @return A named list describing each term's type, predictor columns, and
#' block width, with observed-level information for discrete terms.
#'
#' @keywords internal
#' @noRd
mfpi_interaction_specs <- function(x, interaction_vars, term_to_columns) {
specs <- stats::setNames(vector("list", length(interaction_vars)),
interaction_vars)
for (term in interaction_vars) {
columns <- term_to_columns[[term]]
if (is.null(columns) && term %in% colnames(x)) columns <- term
columns <- unique(as.character(columns))
if (length(columns) == 0L || any(!columns %in% colnames(x))) {
stop(
paste0(
"! Interaction variable `", term,
"` could not be resolved to fitted design columns."
),
call. = FALSE
)
}
identity_term <- length(columns) == 1L && identical(columns, term)
observed <- x[, columns, drop = FALSE]
n_unique <- if (identity_term) length(unique(observed[, 1L])) else NA_integer_
kind <- if (!identity_term || length(columns) > 1L) {
"categorical"
} else if (n_unique == 2L) {
"binary"
} else {
"continuous"
}
level_design <- NULL
level_labels <- NULL
if (kind == "binary") {
values <- sort(unique(observed[, 1L]))
level_design <- matrix(values, ncol = 1L,
dimnames = list(NULL, columns))
level_labels <- as.character(values)
} else if (kind == "categorical") {
keep <- !duplicated(as.data.frame(observed))
level_design <- observed[keep, , drop = FALSE]
level_labels <- apply(level_design, 1L, paste, collapse = ":")
}
specs[[term]] <- list(
term = term,
kind = kind,
discrete = kind != "continuous",
columns = columns,
width = length(columns),
level_labels = level_labels,
level_design = level_design
)
}
specs
}
#' @describeIn mfpi Default method accepting a numeric matrix or data frame
#' \code{x} and response vector \code{y}.
#'
#' @method mfpi default
#' @export
mfpi.default <- function(
x,
y,
group_var = NULL,
interaction_vars = NULL,
interaction_forms = NULL,
flex = c("flex3", "flex1", "flex2", "flex4"),
p_interact = 0.05,
min_improvement = NULL,
include_group_var = FALSE,
show_models = FALSE,
weights = NULL,
offset = NULL,
cycles = 10,
scale = NULL,
shift = NULL,
df = 4,
center = TRUE,
subset = NULL,
family = gaussian(),
criterion = c("pvalue", "aic", "bic"),
select = 0.05,
alpha = 0.05,
keep = NULL,
force_max_fp_vars = NULL,
xorder = c("ascending", "descending", "original"),
powers = NULL,
ties = c("efron", "breslow"),
strata = NULL,
nocenter = c(-1, 0, 1),
acd_vars = NULL,
zero_vars = NULL,
catzero_vars = NULL,
spike_vars = NULL,
min_saz_prop = 0.10,
ftest = FALSE,
control = NULL,
winsorize = FALSE,
winsorize_probs = c(0.01, 0.99),
center_type = c("grand", "group"),
p_adjust_method = "none",
verbose = TRUE,
digits = 3,
term_groups = NULL,
fitter = c("base", "fastglm"),
...
) {
# mfpi.default() validates and normalizes every argument, resolves the
# zero/catzero/spike/acd flags and shift/scale/df settings per predictor
# (mirroring mfp2.default()), then delegates to fit_mfpi() to select the
# adjustment model and test each interaction_vars interaction in turn.
cl <- match.call()
cl[[1L]] <- quote(mfpi)
dots <- match.call(expand.dots = FALSE)$...
mfpi_check_unused_dots(
dots = dots,
context = "`mfpi.default()`"
)
# Step 1: Resolve multiple-choice arguments and the model family ------------
# Match enumerated arguments -------------------------------------------------
xorder <- match.arg(xorder)
criterion <- match.arg(criterion)
flex <- match.arg(flex)
ties <- resolve_mfp_ties(ties)
center_type <- match.arg(center_type)
# Resolve family -------------------------------------------------------------
family_info <- normalize_family_argument(
family,
family_arg = deparse(substitute(family))
)
family <- family_info$family
family_string <- family_info$family_string
validate_mfpi_family(family_string)
fitter <- resolve_fitter(fitter, family_string)
# Ordinal proportional-odds models via rms::orm are supported. The k-1
# cut-point intercepts are handled transparently by fit_ordinal(), which
# returns rank = p (slopes only) and df = n_int + p. The rank validation
# in validate_mfpi_fitted_rank() accounts for this convention.
# Step 2: Prepare x and group_var, then run basic sanity checks -------------
# Formula dispatch can attach a full-row preprocessing design to the
# subset-specific fitting matrix. Preserve that private attribute while
# prepare_mfpi_default_x() normalizes x/group_var, then extract it into an
# explicit preprocess_x matrix. Direct matrix calls use x for both roles.
preprocess_attr <- attr(x, "mfp2_preprocess_x", exact = TRUE)
formula_generated_settings <- !is.null(preprocess_attr)
attr(x, "mfp2_preprocess_x") <- NULL
# Prepare x
prepared_x <- prepare_mfpi_default_x(
x = x,
group_var = group_var
)
x <- prepared_x$x
group_var <- prepared_x$group_var
group_input_levels <- prepared_x$group_input_levels
group_levels_original <- prepared_x$group_levels_original
if (!is.null(preprocess_attr)) {
attr(x, "mfp2_preprocess_x") <- preprocess_attr
}
preprocessing <- extract_preprocess_matrix(x)
x <- preprocessing$x
preprocess_x <- preprocessing$preprocess_x
x_input <- x
vnames <- colnames(x)
# Keep a complete conceptual-term lookup throughout MFPI. Unmentioned
# columns remain singleton terms; grouped entries represent one categorical
# adjustment term generated by multiple design-matrix columns.
term_to_columns <- normalize_term_groups(vnames, term_groups)
# Expand user-facing conceptual term names to their raw matrix columns.
# This lets matrix users refer either to a complete grouped term or to an
# ordinary singleton column in keep/flag arguments.
expand_term_names <- function(values) {
if (is.null(values)) return(NULL)
unique(unlist(lapply(values, function(value) {
if (value %in% names(term_to_columns)) {
term_to_columns[[value]]
} else {
value
}
}), use.names = FALSE))
}
if (anyNA(x)) {
stop(
"! `x` must not contain missing values (NA).\n",
"i Remove or impute missing data before calling `mfpi()`.",
call. = FALSE
)
}
if (!is.numeric(x) || any(!is.finite(x))) {
stop(
"! `x` must be numeric after preprocessing and contain finite values.",
call. = FALSE
)
}
# Enforce the exact-zero domain as soon as the original unshifted matrix and
# term mapping are available. This precedes group/continuous-variable
# eligibility checks as well as all option cascading and preprocessing, so a
# later validation or reset cannot mask negative requested covariates.
validate_zero_option_covariates(
x = preprocess_x,
variables = intersect(
unique(c(
expand_term_names(zero_vars),
expand_term_names(catzero_vars),
expand_term_names(spike_vars)
)),
vnames
)
)
# Basic dimension checks on x ------------------------------------------------
np <- dim(x)
if (is.null(np)) {
stop(
"! `x` must be a matrix with at least one row and one column.\n",
"i `dim(x)` returned NULL.",
call. = FALSE
)
}
nobs <- as.integer(np[1L])
nvars <- as.integer(np[2L])
# Step 3: Validate group_var, p_adjust_method, and interaction_vars ----------------
# Validate group_var ---------------------------------------------------------
if (is.null(group_var)) {
stop(
"! `group_var` is NULL.\n",
"i Provide the name of the categorical grouping variable (e.g. treatment indicator).",
call. = FALSE
)
}
if (length(group_var) != 1L) {
stop(
paste0("! `group_var` must name exactly one variable; ",
length(group_var), " were supplied."),
call. = FALSE
)
}
if (!group_var %in% vnames) {
stop(paste0("! `group_var = '", group_var, "'` is not a column of `x`."),
call. = FALSE)
}
if (group_var %in% interaction_vars) {
stop(
paste0("! `group_var = '", group_var,
"'` must not also appear in `interaction_vars`."),
call. = FALSE
)
}
nlev <- length(unique(x[, group_var]))
if (nlev < 2L) {
stop(
paste0("! `group_var` must have at least two distinct values; found ", nlev, "."),
call. = FALSE
)
}
if (!is.character(p_adjust_method) || length(p_adjust_method) != 1L) {
stop("! `p_adjust_method` must be a single character string.", call. = FALSE)
}
if (!p_adjust_method %in% stats::p.adjust.methods) {
stop(
"! Invalid `p_adjust_method`: ", p_adjust_method, ".\n",
"i Supported methods are: ",
paste(stats::p.adjust.methods, collapse = ", "),
".",
call. = FALSE
)
}
# Validate interaction_vars ---------------------------------------------------------
if (is.null(interaction_vars) || !is.character(interaction_vars) || length(interaction_vars) == 0L) {
stop(
paste0(
"! `interaction_vars` must be a non-empty character vector naming ",
"continuous, binary, or categorical variables to test for interaction ",
"with `group_var = '", group_var, "'`."
),
call. = FALSE
)
}
valid_interaction_terms <- unique(c(vnames, names(term_to_columns)))
missing_cont <- setdiff(interaction_vars, valid_interaction_terms)
if (length(missing_cont) > 0L) {
stop(
paste0("! The following variables in `interaction_vars` are not predictors in `x`: ",
paste(missing_cont, collapse = ", "), "."),
call. = FALSE
)
}
# Grouped interaction variables must be requested by their conceptual term
# name so the complete fitted design block is tested jointly. The grouping
# variable itself cannot participate in a mapped predictor term.
grouped_terms <- names(term_to_columns)[mapped_term_flags(term_to_columns)]
grouped_columns <- unlist(term_to_columns[grouped_terms], use.names = FALSE)
if (group_var %in% grouped_terms || group_var %in% grouped_columns) {
stop("! `group_var` must not be included in `term_groups`.", call. = FALSE)
}
grouped_members <- interaction_vars[
interaction_vars %in% grouped_columns & !interaction_vars %in% grouped_terms
]
if (length(grouped_members) > 0L) {
owners <- vapply(grouped_members, function(column) {
names(term_to_columns)[vapply(
term_to_columns,
function(columns) column %in% columns,
logical(1L)
)][1L]
}, character(1L))
stop(
paste0(
"! Grouped categorical interaction columns must be requested by their ",
"complete term name: ",
paste0(grouped_members, " -> ", owners, collapse = ", "), "."
),
call. = FALSE
)
}
# Resolve forms after identifying complete continuous and discrete terms.
interaction_specs <- mfpi_interaction_specs(
x = preprocess_x,
interaction_vars = interaction_vars,
term_to_columns = term_to_columns
)
interaction_forms <- resolve_mfpi_interaction_forms(
interaction_forms = interaction_forms,
interaction_specs = interaction_specs
)
for (term in names(interaction_specs)) {
interaction_specs[[term]]$form <- interaction_forms[[term]]
}
interaction_columns <- unique(unlist(
lapply(interaction_specs, `[[`, "columns"),
use.names = FALSE
))
discrete_interaction_columns <- unique(unlist(
lapply(Filter(function(spec) isTRUE(spec$discrete), interaction_specs),
`[[`, "columns"),
use.names = FALSE
))
continuous_interaction_vars <- names(Filter(
function(spec) identical(spec$kind, "continuous"),
interaction_specs
))
# Near-categorical continuous variables remain eligible, but the warning is
# relevant only to FP searches. Binary and factor terms use the discrete
# linear path and therefore do not trigger it.
n_unique_continuous <- vapply(continuous_interaction_vars, function(v) {
length(unique(preprocess_x[, interaction_specs[[v]]$columns, drop = TRUE]))
}, integer(1L))
few_unique <- continuous_interaction_vars[
n_unique_continuous > 2L & n_unique_continuous <= 5L &
interaction_forms[continuous_interaction_vars] != "linear"
]
if (length(few_unique) > 0L) {
warning(
paste0(
"! The following variable(s) in `interaction_vars` have 5 or fewer unique ",
"values: ", paste(few_unique, collapse = ", "), ".\n",
" FP transformation may be unreliable for near-categorical variables. ",
"Consider whether these variables are truly continuous."
),
call. = FALSE
)
}
# Step 4: Validate the response, survival inputs, weights, and offset --------
# Validate response y --------------------------------------------------------
validate_family_response(
y = y,
family_string = family_string,
nobs = nobs
)
# Validate survival-model stratification ------------------------------------
if (mfp2_family_is_survival(family_string) && !is.null(strata)) {
strata_len <- if (is.vector(strata) || is.factor(strata)) {
length(strata)
} else {
NROW(strata)
}
if (strata_len != nobs) {
stop(
paste0(
"! Length of `strata` (", strata_len, ") must equal the number of ",
"rows in `x` (", nobs, ")."
),
call. = FALSE
)
}
if (anyNA(strata)) {
stop(
"! `strata` must not contain missing values.",
call. = FALSE
)
}
}
# Validate offset -------------------------------------------------------------
if (!is.null(offset)) {
offset_rows <- if (is.matrix(offset)) nrow(offset) else length(offset)
if (!is.numeric(offset) || offset_rows != nobs || anyNA(offset) ||
any(!is.finite(offset))) {
stop(
"! `offset` must be finite numeric data with one row per observation.",
call. = FALSE
)
}
if (identical(family_string, "multinomial")) {
c_classes <- mfp2_multinomial_n_classes(y)
if (!is.matrix(offset) || !ncol(offset) %in% c(c_classes - 1L, c_classes)) {
stop("! Multinomial `offset` must have C or C - 1 columns.", call. = FALSE)
}
} else if (is.matrix(offset)) {
stop("! `offset` must be a vector for this family.", call. = FALSE)
}
}
# Step 5: Validate alpha/select/df, keep, and force_max_fp_vars -------------
# Matrix inputs use unnamed global scalars or named partial overrides. All
# named values are matched to columns rather than assigned positionally.
alpha_setting <- normalize_named_override_setting(
value = alpha,
column_names = vnames,
default = 0.05,
argument_name = "alpha"
)
alpha <- alpha_setting$value
select_setting <- normalize_named_override_setting(
value = select,
column_names = vnames,
default = 0.05,
argument_name = "select"
)
select <- select_setting$value
df_fallback <- expand_scalar_df_for_mapped_terms(
df = 4L,
vnames = vnames,
term_to_columns = term_to_columns
)
df_setting <- normalize_named_override_setting(
value = df,
column_names = vnames,
default = df_fallback,
argument_name = "df"
)
df <- df_setting$value
if (df_setting$global_scalar && length(df) > 0L) {
df <- expand_scalar_df_for_mapped_terms(
df = unname(df[[1L]]),
vnames = vnames,
term_to_columns = term_to_columns
)
}
validate_probability_vector(alpha, "alpha", nvars)
validate_probability_vector(select, "select", nvars)
# Validate keep. A grouped categorical term may be named directly; it is
# converted to one conceptual keep entry before adjustment-model fitting.
valid_term_names <- unique(c(vnames, names(term_to_columns)))
if (!is.null(keep) && !all(keep %in% valid_term_names)) {
warning(
"i Some entries in `keep` are not predictor columns or conceptual terms; ",
"continuing with the valid entries.",
call. = FALSE
)
keep <- intersect(keep, valid_term_names)
}
# Validate force_max_fp_vars ------------------------------------------------
# Convert character vector of variable names to named logical vector
# (the internal format expected by fit_mfpi and flex functions).
force_max_fp <- setNames(rep(FALSE, nvars), vnames)
if (!is.null(force_max_fp_vars)) {
if (!is.character(force_max_fp_vars)) {
stop("! `force_max_fp_vars` must be a character vector or NULL.",
call. = FALSE)
}
bad_names <- setdiff(force_max_fp_vars, valid_term_names)
if (length(bad_names) > 0L) {
warning("i Some variables in `force_max_fp_vars` are not columns of `x`; ",
"they will be ignored: ", paste(bad_names, collapse = ", "), ".",
call. = FALSE)
}
force_max_fp_vars <- intersect(force_max_fp_vars, valid_term_names)
force_max_fp_columns <- expand_term_names(force_max_fp_vars)
if (length(force_max_fp_columns) > 0L) {
force_max_fp[force_max_fp_columns] <- TRUE
}
}
# Step 6: Validate zero_vars / catzero_vars / spike_vars / acd_vars ---------
# Validate zero_vars / catzero_vars / spike_vars -----------------------------
if (!is.null(zero_vars) && !all(zero_vars %in% valid_term_names)) {
warning("i Some variables in `zero_vars` are not columns of `x`; they will be ignored.",
call. = FALSE)
}
if (!is.null(catzero_vars) && !all(catzero_vars %in% valid_term_names)) {
warning("i Some variables in `catzero_vars` are not columns of `x`; they will be ignored.",
call. = FALSE)
}
if (!is.null(spike_vars) && !all(spike_vars %in% valid_term_names)) {
warning("i Some variables in `spike_vars` are not columns of `x`; they will be ignored.",
call. = FALSE)
}
zero_vars_in <- intersect(expand_term_names(zero_vars), vnames)
catzero_vars_in <- intersect(expand_term_names(catzero_vars), vnames)
spike_vars_in <- intersect(expand_term_names(spike_vars), vnames)
# For interaction_vars, catzero/spike will be dropped later, so do not treat
# zero + catzero overlap on interaction_vars as fatal.
overlap <- intersect(zero_vars_in, setdiff(catzero_vars_in, interaction_columns))
if (length(overlap) > 0L) {
stop(
paste0(
"! The following variables appear in both `zero_vars` and `catzero_vars`: ",
paste(overlap, collapse = ", "),
". Use only one option per variable."
),
call. = FALSE
)
}
zero_vars <- zero_vars_in
catzero_vars <- catzero_vars_in
spike_vars <- spike_vars_in
# Validate acd_vars ----------------------------------------------------------
if (!is.null(acd_vars) && !all(acd_vars %in% valid_term_names)) {
warning("i Some variables in `acd_vars` are not columns of `x`; they will be ignored.",
call. = FALSE)
}
# Step 7: Validate shift/scale/center/df, SAZ proportion, and ftest ---------
# Validate shift and scale ---------------------------------------------------
shift <- normalize_named_numeric_setting(
value = shift,
column_names = vnames,
argument_name = "shift",
allow_null = TRUE,
scalar_recycle = TRUE,
strictly_positive = FALSE,
allow_na = formula_generated_settings,
allow_partial_named = TRUE
)
scale <- normalize_named_numeric_setting(
value = scale,
column_names = vnames,
argument_name = "scale",
allow_null = TRUE,
scalar_recycle = TRUE,
strictly_positive = TRUE,
allow_na = formula_generated_settings,
allow_partial_named = TRUE
)
scale <- expand_scale_for_mapped_terms(
scale = scale,
vnames = vnames,
term_to_columns = term_to_columns,
automatic = is.na(scale)
)
# Validate and normalize center ----------------------------------------------
# Developer note: mfpi.formula() may pass a complete named logical vector
# after reading fp()/fp2() attributes. Direct default-method calls may instead
# use an unnamed global scalar or a named partial vector. In all named cases,
# matching is by colnames(x), never by predictor position.
center <- normalize_named_logical_setting(
value = center,
column_names = vnames,
default = TRUE,
argument_name = "center"
)
# Validate df ----------------------------------------------------------------
if (any(df <= 0L)) {
stop("! All values of `df` must be positive (1 for linear, 2m for FP degree m).",
call. = FALSE)
}
invalid_df <- df != 1L & df %% 2L != 0L
if (any(invalid_df)) {
stop(
paste0(
"! Each element of `df` must be 1 (linear) or an even number 2m. ",
"Invalid variable(s): ",
paste(names(df)[invalid_df], collapse = ", "), "."
),
call. = FALSE
)
}
# Validate spike-at-zero component proportion -------------------------------
if (!is.numeric(min_saz_prop) ||
length(min_saz_prop) != 1L ||
anyNA(min_saz_prop) ||
!is.finite(min_saz_prop) ||
min_saz_prop <= 0 ||
min_saz_prop >= 0.5) {
stop(
"! `min_saz_prop` must be a single finite numeric value in the open interval (0, 0.5).",
call. = FALSE
)
}
# Warn if ftest is incompatible with family ------------------------------
if (ftest && family_string != "gaussian") {
warning(
paste0("i `ftest = TRUE` is only applicable to Gaussian models; ",
"reverting to chi-square test for family = '", family_string, "'."),
call. = FALSE
)
ftest <- FALSE
}
# Validate and build powers list ----------------------------------------------
# `powers` defines candidate base-power sets, not selected FP power vectors.
# Duplicate candidate values are removed. Repeated selected FP powers are
# generated later by replacement when fitting FP2 or higher-degree models.
# Step 8: Validate the powers list, subset, and interaction selection
# thresholds (p_interact / min_improvement) ---------------------------------
# (p_adjust_method was already fully validated in Step 3, including the
# check against stats::p.adjust.methods, so it is not re-validated here.)
power_list <- validate_fp_power_list(
powers = powers,
vnames = vnames,
arg_name = "powers"
)
# Validate subset ------------------------------------------------------------
if (!is.null(subset)) {
if (is.logical(subset)) {
if (length(subset) != nobs || anyNA(subset)) {
stop(
"! Logical `subset` must have one TRUE/FALSE value per observation and contain no NA.",
call. = FALSE
)
}
subset <- which(subset)
} else if (is.numeric(subset)) {
if (
anyNA(subset) ||
any(!is.finite(subset)) ||
any(subset != as.integer(subset)) ||
any(subset < 1L) ||
any(subset > nobs)
) {
stop(
"! Numeric `subset` must contain valid positive row indices within the range of `x`.",
call. = FALSE
)
}
subset <- as.integer(subset)
} else {
stop(
"! `subset` must be either a logical vector or a numeric/integer vector of row indices.",
call. = FALSE
)
}
if (anyDuplicated(subset)) {
stop(
"! `subset` must not contain duplicated row indices.",
call. = FALSE
)
}
if (length(subset) < 5L) {
stop(
paste0(
"! After subsetting, only ", length(subset),
" observations remain; at least 5 are required."
),
call. = FALSE
)
}
}
# Apply one strictly-positive observation-weight contract to every family.
# Zero weights are rejected even when a fitter accepts them because they can
# make likelihood-based MFP/MFPI comparisons undefined for some families.
validate_model_weights(
weights = weights,
nobs = nobs
)
# Validate interaction-selection thresholds -----------------------------------
if (!is.numeric(p_interact) ||
length(p_interact) != 1L ||
anyNA(p_interact) ||
!is.finite(p_interact) ||
p_interact <= 0 ||
p_interact > 1) {
stop(
"! `p_interact` must be a single finite numeric value in (0, 1].",
call. = FALSE
)
}
if (!is.null(min_improvement)) {
if (!is.numeric(min_improvement) ||
length(min_improvement) != 1L ||
anyNA(min_improvement) ||
!is.finite(min_improvement) ||
min_improvement <= 0) {
stop(
"! `min_improvement` must be NULL or a single finite positive numeric value.",
call. = FALSE
)
}
}
# Step 9: Apply defaults and expand scalar options to named per-variable
# vectors, then resolve the force_max_fp/alpha interaction ------------------
# Set default min_improvement -------------------------------------------------
if (is.null(min_improvement)) {
min_improvement <- switch(criterion, pvalue = p_interact, aic = 2, bic = 2)
}
# Default weights (all observations equally weighted) and offset (none);
# has_offset is recorded before defaulting so the fitted object can report
# whether the user actually supplied an offset.
if (is.null(weights)) weights <- rep.int(1, nobs)
has_offset <- !is.null(offset)
if (is.null(offset)) offset <- rep.int(0, nobs)
# select, alpha, and center were normalized above to complete named vectors
# ordered exactly like colnames(x).
# For adjustment-model variables under p-value selection, force_max_fp
# requires both retention of the variable and acceptance of its most complex
# permitted FP degree.
if (criterion == "pvalue" && any(force_max_fp)) {
select[force_max_fp] <- 1
alpha[force_max_fp] <- 1
}
# Automatic shifts are deliberately estimated later, after SAZ eligibility and
# the zero/catzero/spike cascade have reached their final retained state.
# Retained zero-handled variables need shift = 0; variables reset from SAZ to
# ordinary FP need ordinary positivity shifting.
# `shift` and `scale` were normalized above and are already aligned by name.
# Missing internal formula sentinels are resolved after the SAZ cascade and
# after shifting, respectively.
# Resolve and validate fitting controls once for both MFPI stages and every
# nested MFP candidate fit.
control <- normalize_fit_control(
control = control,
family_string = family_string,
fitter = fitter
)
# Retain valid raw-column or conceptual-term entries. preprocess_data()
# converts these to the term names expected by the grouped MFP core.
keep <- intersect(keep, valid_term_names)
# Step 10: Build zero/catzero/spike flags, suppress them for interaction_vars, and
# resolve spike-at-zero eligibility for the remaining adjustment variables -
# Process zero_vars / catzero_vars / spike_vars to named logical vectors -----
zero_flag <- setNames(rep(FALSE, nvars), vnames)
catzero_flag <- setNames(rep(FALSE, nvars), vnames)
spike_flag <- setNames(rep(FALSE, nvars), vnames)
if (length(zero_vars) > 0L) zero_flag[zero_vars] <- TRUE
if (length(catzero_vars) > 0L) catzero_flag[catzero_vars] <- TRUE
if (length(spike_vars) > 0L) spike_flag[spike_vars] <- TRUE
# interaction_vars may keep explicit zero handling, but cannot use catzero/spike.
# Developer note: this cleanup must happen BEFORE the cascade below. Otherwise
# spike_vars/catzero_vars would imply zero_vars for interaction_vars, which is not the
# intended MFPI stage-2 contract. Only explicit zero_vars should survive for
# interaction variables.
spike_in_cont <- intersect(names(spike_flag)[spike_flag], interaction_columns)
catzero_in_cont <- intersect(names(catzero_flag)[catzero_flag], interaction_columns)
if (length(spike_in_cont) > 0L) {
warning(
"The following `interaction_vars` were also marked as `spike_vars`: ",
paste(spike_in_cont, collapse = ", "),
". Spike-at-zero handling is not supported for MFPI interaction variables; ",
"`spike` and the implied `catzero` indicator are set to FALSE for these variables. ",
"Explicit `zero_vars` settings are preserved.",
call. = FALSE
)
spike_flag[spike_in_cont] <- FALSE
catzero_flag[spike_in_cont] <- FALSE
}
if (length(catzero_in_cont) > 0L) {
warning(
"The following `interaction_vars` were also marked as `catzero_vars`: ",
paste(catzero_in_cont, collapse = ", "),
". Structural-zero binary indicators are not supported for MFPI interaction variables; ",
"`catzero` is set to FALSE for these variables. ",
"Explicit `zero_vars` settings are preserved.",
call. = FALSE
)
catzero_flag[catzero_in_cont] <- FALSE
}
# Resolve spike-at-zero eligibility before the cascade and before shift/scale ---
# This must happen after unsupported cont_var spike/catzero flags have been
# removed, but before the spike -> catzero -> zero cascade is applied.
#
# resolve_saz_eligibility() needs the user's explicit zero/catzero choices.
# Therefore, do not call it after catzero_flag[spike_flag] <- TRUE or
# zero_flag[catzero_flag] <- TRUE, because that would lose the distinction
# between user-specified flags and spike-implied flags.
if (any(spike_flag)) {
saz_flags <- resolve_saz_eligibility(
x = preprocess_x,
spike = spike_flag,
catzero = catzero_flag,
zero = zero_flag,
min_saz_prop = min_saz_prop
)
spike_flag <- saz_flags$spike
catzero_flag <- saz_flags$catzero
zero_flag <- saz_flags$zero
}
# Enforce the cascade after SAZ eligibility has been resolved.
# Retained spike variables imply catzero, and retained catzero variables imply
# zero. Variables whose spike flag was reset keep only the user's explicit
# zero/catzero choices.
catzero_flag[spike_flag] <- TRUE
zero_flag[catzero_flag] <- TRUE
# Step 11: Reset zero/catzero/spike for all-positive or binary variables,
# and build the acd_vars flag (suppressed for interaction_vars) -------------------
# Reset zero/catzero/spike for variables that contain only positive values -----
if (any(zero_flag | catzero_flag | spike_flag)) {
vars_pos <- names(zero_flag)[zero_flag | catzero_flag | spike_flag]
xpos <- preprocess_x[, vars_pos, drop = FALSE]
all_positive <- vars_pos[colSums(xpos == 0) == 0L]
if (length(all_positive) > 0L) {
warning(
paste0(
"i The following variables in `zero_vars`, `catzero_vars`, or ",
"`spike_vars` contain only positive values and have been reset to ",
"standard processing: ",
paste(all_positive, collapse = ", "), "."
),
call. = FALSE
)
zero_flag[all_positive] <- FALSE
catzero_flag[all_positive] <- FALSE
spike_flag[all_positive] <- FALSE
}
}
# Reset zero/catzero for binary variables ------------------------------------
binary_vars <- apply(preprocess_x, 2L,
function(col) length(unique(col[!is.na(col)])) == 2L)
binary_names <- vnames[binary_vars]
if (length(binary_names) > 0L) {
# Binary predictors, including factor dummy columns, must remain on their
# original two-level scale. Automatic preprocessing already returns scale = 1
# for them, but an explicitly supplied scale would otherwise override that
# safeguard and rescale the columns before the MFPI adjustment fit.
scale[binary_names] <- 1
reset_vars <- intersect(
binary_names,
Reduce(
union,
list(
names(zero_flag)[zero_flag],
names(catzero_flag)[catzero_flag],
names(spike_flag)[spike_flag]
)
)
)
if (length(reset_vars) > 0L) {
warning(
paste0(
"i The following binary variables were marked in `zero_vars`, ",
"`catzero_vars`, or `spike_vars` but are binary; resetting to standard ",
"processing: ",
paste(reset_vars, collapse = ", "), "."
),
call. = FALSE
)
zero_flag[reset_vars] <- FALSE
catzero_flag[reset_vars] <- FALSE
spike_flag[reset_vars] <- FALSE
}
}
acd_flag <- setNames(rep(FALSE, nvars), vnames)
if (!is.null(acd_vars)) {
# Keep only variables that exist in `x`; unknown variables were warned about
# in the earlier validation block.
acd_vars <- unique(intersect(expand_term_names(acd_vars), vnames))
# Developer note:
# ACD transformations are disabled for MFPI interaction variables. The
# interaction variable's functional form is handled by the flex0-flex4
# search, and applying ACD upstream would change the interaction scale and
# break reconstruction of f_j(x).
acd_in_cont <- intersect(acd_vars, interaction_columns)
if (length(acd_in_cont) > 0L) {
warning(
"ACD transformation is disabled for interaction_vars: ",
paste(acd_in_cont, collapse = ", "),
".",
call. = FALSE
)
acd_vars <- setdiff(acd_vars, interaction_columns)
}
acd_flag[acd_vars] <- TRUE
}
# Step 12: Assign per-variable df, then reset shift for zero/catzero/linear
# variables (their shift is meaningless since only the positive part, or no
# nonlinear transform at all, is ever fitted) -------------------------------
# Set degrees of freedom per variable ----------------------------------------
# df was normalized above to a complete named vector. Omitted named
# entries already contain ordinary defaults, with explicitly mapped design
# blocks receiving their structural df = 1 fallback.
df_default <- df
df_list <- setNames(assign_df(x = preprocess_x, df_default = df_default), vnames)
# Discrete interaction terms are ordinary, uncentred design columns. They
# must never inherit continuous-variable preprocessing or FP settings from
# global arguments. Keeping the original indicator coding also makes their
# coefficients and predictions directly comparable with glm(), lm(), and
# nnet::multinom() treatment-contrast fits.
if (length(discrete_interaction_columns) > 0L) {
df_list[discrete_interaction_columns] <- 1L
center[discrete_interaction_columns] <- FALSE
shift[discrete_interaction_columns] <- 0
scale[discrete_interaction_columns] <- 1
power_list[discrete_interaction_columns] <- rep(
list(1), length(discrete_interaction_columns)
)
zero_flag[discrete_interaction_columns] <- FALSE
catzero_flag[discrete_interaction_columns] <- FALSE
spike_flag[discrete_interaction_columns] <- FALSE
acd_flag[discrete_interaction_columns] <- FALSE
force_max_fp[discrete_interaction_columns] <- FALSE
}
# Multi-column adjustment terms are fixed linear design blocks. They cannot
# use continuous-variable extensions or structural-zero representations.
validate_grouped_term_setting(
term_to_columns, acd_flag, "acd_vars", function(v) !v, "FALSE"
)
validate_grouped_term_setting(
term_to_columns, zero_flag, "zero_vars", function(v) !v, "FALSE"
)
validate_grouped_term_setting(
term_to_columns, catzero_flag, "catzero_vars", function(v) !v, "FALSE"
)
validate_grouped_term_setting(
term_to_columns, spike_flag, "spike_vars", function(v) !v, "FALSE"
)
validate_grouped_term_setting(
term_to_columns, force_max_fp, "force_max_fp_vars", function(v) !v, "FALSE"
)
validate_grouped_term_setting(
term_to_columns, df_list, "df", function(v) v == 1, "1 (linear-only)"
)
# Reset shift to 0 for zero/catzero variables and linear terms ---------------
# Only the positive part of these variables is FP-transformed so no shift
# is needed (matching the logic in mfp2.default()).
# Step 13: Shift and scale x (excluding group_var), then verify positivity --
shift_to_zero <- rep(FALSE, nvars)
names(shift_to_zero) <- vnames
shift_to_zero[names(zero_flag)[zero_flag]] <- TRUE
shift_to_zero[names(catzero_flag)[catzero_flag]] <- TRUE
shift_to_zero[vnames[df_list == 1L]] <- TRUE
# Continuous interaction variables with an FP interaction form are
# FP-transformed by the flex search even when their adjustment-model term is
# linear (explicit df = 1, or df = 1 assigned automatically for <= 3 distinct
# values). They therefore keep a positivity shift: an explicit user shift is
# honoured and a missing shift is estimated below. Zero-handled variables keep
# shift = 0 because only their positive part is transformed.
fp_interaction_columns <- mfpi_fp_interaction_columns(
interaction_specs = interaction_specs,
interaction_forms = interaction_forms
)
zero_handled_names <- union(
names(zero_flag)[zero_flag],
names(catzero_flag)[catzero_flag]
)
shift_to_zero[setdiff(fp_interaction_columns, zero_handled_names)] <- FALSE
shift[shift_to_zero] <- 0
# At this point the code has already handled zero_flag, catzero_flag,
# spike_flag, etc. so a good place to estimate shifting factors
# shift = 0 for retained zero/catzero variables and df = 1 variables
# automatic find_shift_factor() only for remaining NA shifts
shift_missing <- is.na(shift)
# Remember which shifts were estimated automatically, so rank-deficiency
# errors can tell automatic shifts apart from user-supplied ones.
shift_automatic <- stats::setNames(as.logical(shift_missing), vnames)
if (any(shift_missing)) {
shift[shift_missing] <- apply(
preprocess_x[, shift_missing, drop = FALSE],
2L,
find_shift_factor
)
}
# `group_var` is categorical/index metadata, not an FP predictor.
# It must remain on its input coding until preprocess_data() remaps it to
# internal 0, 1, ..., K - 1 levels.
if (group_var %in% names(shift)) {
shift[group_var] <- 0
}
# Apply shift and scale to x -------------------------------------------------
preprocess_x_shifted <- sweep(preprocess_x, 2L, shift, "+")
x <- sweep(x, 2L, shift, "+")
# `group_var` is categorical/index metadata, not an FP predictor. It must not be
# automatically scaled because preprocess_data() later remaps it to internal
# 0, 1, ..., K - 1 group codes. Keeping scale[group_var] = 1 also ensures that
# stored prediction metadata does not imply a raw continuous-variable scaling
# operation for the grouping column.
if (group_var %in% names(scale)) {
scale[group_var] <- 1
}
# Compute scale factors on shifted x, matching standalone mfp2. User-supplied
# scale values are left untouched; only missing scales are estimated.
# Zero-handled predictors keep an automatic scale of 1, as in mfp2().
scale <- fix_zero_handled_scale(scale, zero_flag, preprocess_x_shifted)
scale_missing <- is.na(scale)
if (any(scale_missing)) {
scale[scale_missing] <- apply(
preprocess_x_shifted[, scale_missing, drop = FALSE],
2L,
find_scale_factor
)
}
# Positivity check for variables that undergo nonlinear FP transformation ----
# This covers nonlinear adjustment terms and continuous interaction variables
# with an FP interaction form, whatever their adjustment-model df.
nonlinear_names <- union(vnames[df_list != 1L], fp_interaction_columns)
all_zero_names <- union(names(zero_flag)[zero_flag],
names(catzero_flag)[catzero_flag])
check_names <- setdiff(nonlinear_names, all_zero_names)
if (length(check_names) > 0L) {
xcheck <- preprocess_x_shifted[, check_names, drop = FALSE]
neg_idx <- which(colSums(xcheck <= 0, na.rm = TRUE) > 0L)
if (length(neg_idx) > 0L) {
stop(
paste0(
"! Shifting factors are insufficient to ensure positive values for FP ",
"transformation.\n",
"i Problematic variables: ",
paste(colnames(xcheck)[neg_idx], collapse = ", "),
".\ni Consider increasing the shift values for these variables."
),
call. = FALSE
)
}
}
# Scale the x based on the estimated scaling factors
x <- sweep(x, 2L, scale, "/")
# Step 14: Prepare survival stratification, apply `subset`, and re-validate
# group_var against the (possibly reduced) subsetted data -------------------
# Prepare survival stratification -------------------------------------------
# Normalize all strata to one factor before MFP/MFPI candidate fitting.
# Multiple columns are combined as in survival::coxph(), while a single
# vector is treated as categorical labels regardless of storage mode.
# Integer conversion belongs only at the survival::coxph.fit() boundary.
strata_keep <- strata
if (mfp2_family_is_survival(family_string) && !is.null(strata_keep)) {
strata_keep <- normalize_cox_strata(strata_keep, nobs = nobs)
}
# Apply subset ---------------------------------------------------------------
# This is the direct matrix path. Keep the user-supplied numeric columns, but
# reject mapped blocks that lose within-block rank because MFPI has no factor
# levels or contrast function from which to regenerate them. Singleton columns
# are checked separately for complete loss of variation.
if (!is.null(subset)) {
validate_grouped_subset_rank(
x_full = x_input,
x_fit = x_input[subset, , drop = FALSE],
term_to_columns = term_to_columns
)
x <- x[subset, , drop = FALSE]
y <- if (is.matrix(y)) {
y[subset, , drop = FALSE]
} else {
y[subset]
}
weights <- weights[subset]
offset <- if (is.matrix(offset)) offset[subset, , drop = FALSE] else offset[subset]
if (!is.null(strata_keep)) {
# Subsetting can remove complete strata, so drop unused levels after the
# row restriction while preserving row alignment.
strata_keep <- droplevels(strata_keep[subset])
}
}
# zero_vars applies the interaction function only to x > 0. Validate this
# requirement after the optional subset has been applied, because a variable
# can contain positive values in the full data yet lose all of them in the
# actual fitting population. This shared boundary gives every flexibility
# method the same variable-specific error instead of exposing flex2/flex4
# transformation assertions to users.
zero_interaction_vars <- intersect(
interaction_vars,
names(zero_flag)[zero_flag]
)
if (length(zero_interaction_vars) > 0L) {
has_positive <- vapply(
zero_interaction_vars,
function(variable) any(x[, variable] > 0),
logical(1L)
)
if (any(!has_positive)) {
stop(
"Zero-handled variables in `interaction_vars` must contain at least one ",
"positive value in the fitting data after subsetting. Problematic ",
"variables: ",
paste(zero_interaction_vars[!has_positive], collapse = ", "),
".",
call. = FALSE
)
}
}
# Run the general post-subset variation check after the zero-specific support
# check so an all-zero zero-handled continuous variable receives the more
# informative missing-positive-component error. Formula calls arrive with an
# already-subset fitting matrix and carry `formula_generated_settings = TRUE`.
if (!is.null(subset) || formula_generated_settings) {
validate_subset_predictor_variation(x, exclude = group_var)
}
# Refresh group-level metadata after subsetting. The metadata are created
# before subset is applied, so a subset can remove one or more group levels.
# Passing stale levels into preprocess_data() can create all-zero group dummies.
observed_group_levels <- sort(unique(as.numeric(x[, group_var])))
keep_group_levels <- group_input_levels %in% observed_group_levels
group_input_levels <- group_input_levels[keep_group_levels]
group_levels_original <- group_levels_original[keep_group_levels]
# A dataset with two groups can pass initial validation, then subset can
# remove all observations from one group. Later internals may fail inside
# dummy creation or interaction fitting with a less informative error.
if (length(unique(x[, group_var])) < 2L) {
stop("`group_var` must contain at least two groups after subsetting.", call. = FALSE)
}
group_counts <- table(x[, group_var])
# A singleton group cannot identify a group effect and a group-specific
# continuous effect simultaneously. With group centering, its only basis
# value is also centered to exact zero. This is a structural failure rather
# than merely a small-sample concern, irrespective of the requested form.
singleton_groups <- names(group_counts)[group_counts < 2L]
if (length(singleton_groups) > 0L) {
stop(
"Each group must contain at least two observations in the fitting data ",
"after subsetting. Singleton groups: ",
paste(singleton_groups, collapse = ", "),
".",
call. = FALSE
)
}
# FP2 contributes two group-specific basis columns. Together with the group
# effect, these require at least three observations in every group. A two-row
# group can still identify a one-column linear/FP1 interaction, so it retains
# the existing warning below when no FP2 interaction is requested.
fp2_requested <- any(interaction_forms == "fp2")
fp2_small_groups <- names(group_counts)[group_counts < 3L]
if (fp2_requested && length(fp2_small_groups) > 0L) {
stop(
"FP2 interactions require at least three observations in every group ",
"after subsetting. Problematic groups: ",
paste(fp2_small_groups, collapse = ", "),
".",
call. = FALSE
)
}
if (identical(center_type, "group") && length(zero_interaction_vars) > 0L) {
group_values <- x[, group_var]
fitted_group_levels <- sort(unique(group_values))
insufficient_positive <- character(0L)
for (variable in zero_interaction_vars) {
required_positive <- if (identical(interaction_forms[[variable]], "fp2")) {
3L
} else {
2L
}
positive_counts <- vapply(
fitted_group_levels,
function(group) {
as.integer(sum(group_values == group & x[, variable] > 0))
},
integer(1L)
)
names(positive_counts) <- as.character(fitted_group_levels)
bad_groups <- names(positive_counts)[positive_counts < required_positive]
if (length(bad_groups) > 0L) {
insufficient_positive <- c(
insufficient_positive,
paste0(
variable, " (group ", bad_groups, ": ",
positive_counts[bad_groups], " positive; need ",
required_positive, ")"
)
)
}
}
if (length(insufficient_positive) > 0L) {
stop(
"Group-centered zero-handled interactions lack enough positive ",
"observations to identify their requested basis: ",
paste(insufficient_positive, collapse = ", "),
".",
call. = FALSE
)
}
}
small_groups <- names(group_counts)[group_counts == 2L]
if (length(small_groups) > 0L) {
warning(
"Some groups have only 2 observations after subsetting: ",
paste(small_groups, collapse = ", "),
". Linear or FP1 interaction fitting may be unreliable.",
call. = FALSE
)
}
# Step 15: Winsorise interaction_vars (unless excluded by zero handling) ----------
# Winsorise interaction_vars to reduce influence of extreme values ------------------
# Variables with final zero handling are excluded from Winsorisation so that
# structural-zero values and the positive distribution are both preserved.
winsorize_limits <- NULL
if (isTRUE(winsorize) && length(continuous_interaction_vars) > 0L) {
exclude_from_win <- names(zero_flag)[zero_flag]
win <- winsorize_interaction_vars(
x = x,
interaction_vars = continuous_interaction_vars,
probs = winsorize_probs,
zero_vars = exclude_from_win
)
x <- win$x
winsorize_limits <- win$limits
if (verbose) {
message(sprintf(
"Winsorising %d cont_var(s) at percentiles (%g, %g).",
length(continuous_interaction_vars), winsorize_probs[1L], winsorize_probs[2L]
))
excluded <- intersect(exclude_from_win, continuous_interaction_vars)
if (length(excluded) > 0L) {
message(sprintf(
"Excluded from Winsorisation because of zero handling: %s.",
paste(excluded, collapse = ", ")
))
}
if (!is.null(winsorize_limits)) {
limits_text <- utils::capture.output(print(winsorize_limits))
message(
"Winsorisation limits:\n",
paste(limits_text, collapse = "\n")
)
}
}
}
# Prepare transformed survival data once before either MFPI stage. Candidate
# fits then reuse the cached survreg response and distribution metadata.
prepared_family <- prepare_family_for_fit(
family = family,
family_string = family_string,
y = y,
weights = weights,
strata = strata_keep,
offset = offset,
has_offset = has_offset
)
family <- prepared_family$family
strata_keep <- prepared_family$strata
# Step 16: Fit the MFPI model and attach return metadata --------------------
# Fit the MFPI model ---------------------------------------------------------
fit <- fit_mfpi(
x = x,
y = y,
family = family, # resolved GLM or survival family
family_string = family_string, # character string for branching
fitter = fitter,
weights = weights,
offset = offset,
cycles = cycles,
center = center,
criterion = criterion,
select = select,
alpha = alpha,
df = df_list,
keep = keep,
force_max_fp = force_max_fp,
xorder = xorder,
fp_powers = power_list,
ties = ties,
strata = strata_keep,
nocenter = nocenter,
acd_vars = acd_flag,
zero_vars = zero_flag,
catzero_vars = catzero_flag,
spike_vars = spike_flag,
min_saz_prop = min_saz_prop,
use_ftest = ftest,
control = control,
verbose = verbose,
group_var = group_var,
include_group_var = include_group_var,
flex = flex,
interaction_vars = interaction_vars,
interaction_forms = interaction_forms,
interaction_specs = interaction_specs,
p_interact = p_interact,
show_models = show_models,
min_improvement = min_improvement,
digits = digits,
center_type = center_type,
scale = scale,
shift = shift,
shift_automatic = shift_automatic,
has_offset = has_offset,
p_adjust_method = p_adjust_method,
group_input_levels = group_input_levels,
group_levels_original = group_levels_original,
term_to_columns = term_to_columns
)
# Attach Winsorisation metadata for transparency in the returned object
fit$winsorize <- isTRUE(winsorize)
fit$winsorize_probs <- if (isTRUE(winsorize)) winsorize_probs else NULL
fit$winsorize_limits <- winsorize_limits
fit$p_adjust_method <- p_adjust_method
fit$p_interact <- p_interact
fit$min_improvement <- min_improvement
fit$interaction_forms <- interaction_forms
fit$interaction_specs <- interaction_specs
# `fit_mfpi()` stores `x_train_internal`, the post-preprocessing training
# matrix used for manual prediction reconstruction. It contains shifted/scaled
# predictors and internally remapped group_var codes. Do not store or use the
# pre-remap matrix `x` for prediction.
fit$family_string <- family_string
if (identical(family_string, "multinomial")) {
# Keep the prepared class ordering on the top-level MFPI object. The
# public family component below is stripped to avoid duplicating the
# response, while retained term-specific multinom fits keep the prepared
# family needed for prediction and coefficient labelling.
fit$mfp2_family <- family
fit$class_levels <- family$prepared$levels
fit$reference_class <- family$prepared$reference
fit$n_logits <- family$prepared$n_logits
}
if (identical(family_string, "ordinal")) {
# Ordinal metadata: the response levels and link function. These are
# needed for prediction and coefficient labelling. Unlike multinomial,
# ordinal has flat (scalar) coefficients, so it uses the standard
# coefficient/prediction path with no per-logit fan-out.
fit$ordinal_levels <- family$prepared$levels
fit$ordinal_link <- family$prepared$link
fit$n_intercepts <- family$prepared$n_intercepts
}
if (!identical(family_string, "negbin")) {
fit$family <- mfp2_strip_prepared_family(family)
}
fit$zero_vars <- zero_flag
fit$center_type <- center_type
fit$interaction_vars <- interaction_vars
fit$term_to_columns <- fit$adjustment_term_to_columns
fit$call <- cl
# Compute the number of events for survival models so that
# print.mfpi() can display it alongside n.
if (identical(family_string, "cox")) {
fit$nevents <- sum(y[, NCOL(y)] > 0, na.rm = TRUE)
}
class(fit) <- "mfpi"
fit
}
#' @describeIn mfpi Formula method using a model formula and data frame.
#'
#' @method mfpi formula
#' @export
mfpi.formula <- function(formula,
data,
group_var = NULL,
interaction_vars = NULL,
interaction_forms = NULL,
flex = c("flex3", "flex1", "flex2", "flex4"),
p_interact = 0.05,
min_improvement = NULL,
include_group_var = FALSE,
show_models = FALSE,
weights = NULL,
cycles = 10,
scale = NULL,
shift = NULL,
df = 4,
center = TRUE,
subset = NULL,
family = gaussian(),
criterion = c("pvalue", "aic", "bic"),
select = 0.05,
alpha = 0.05,
keep = NULL,
force_max_fp_vars = NULL,
xorder = c("ascending", "descending", "original"),
powers = NULL,
ties = c("efron", "breslow"),
nocenter = c(-1, 0, 1),
zero_vars = NULL,
catzero_vars = NULL,
spike_vars = NULL,
min_saz_prop = 0.10,
ftest = FALSE,
control = NULL,
winsorize = FALSE,
winsorize_probs = c(0.01, 0.99),
center_type = c("grand", "group"),
p_adjust_method = "none",
verbose = TRUE,
digits = 3,
fitter = c("base", "fastglm"),
...) {
# mfpi.formula() translates a formula + data.frame specification into the
# matrix/vector inputs expected by mfpi.default(): it builds the model
# frame, expands fp()/fp2() term attributes into per-variable option lists,
# then calls mfpi.default() to perform validation, preprocessing, and fitting.
call <- match.call()
call[[1L]] <- quote(mfpi)
# Capture these promises before validation can force them. They are resolved
# exactly once in the formula data mask below, matching the standard lookup
# behavior of model-frame-based formula methods.
weights_expr <- substitute(weights)
subset_expr <- substitute(subset)
# Step 1: Resolve multiple-choice arguments, family, and reject unused `...`
dots <- match.call(expand.dots = FALSE)$...
if ("offset" %in% names(dots)) {
stop(
"`offset` is not supported as an argument to `mfpi.formula()`. ",
"Include `offset(...)` in the formula instead.",
call. = FALSE
)
}
if ("strata" %in% names(dots)) {
stop(
"`strata` is not supported as an argument to `mfpi.formula()`. ",
"Include `strata(...)` in the formula instead.",
call. = FALSE
)
}
mfpi_check_unused_dots(
dots = dots,
context = "`mfpi.formula()`"
)
xorder <- match.arg(xorder)
criterion <- match.arg(criterion)
flex <- match.arg(flex)
ties <- resolve_mfp_ties(ties)
center_type <- match.arg(center_type)
fitter <- match.arg(fitter)
# Family
family_info <- normalize_family_argument(
family,
family_arg = deparse(substitute(family))
)
family_string <- family_info$family_string
validate_mfpi_family(family_string)
# Unused or misspelled arguments are already rejected above by
# mfpi_check_unused_dots(), which reports the offending name(s) directly.
# `offset` and `strata` receive specific formula-syntax guidance above.
# Step 2: Validate the formula-specific inputs (data, formula) --------------
# ---------------------------------------------------------------------------
# Input validation (formula-specific constraints)
# ---------------------------------------------------------------------------
if (missing(data)) {
stop("! data argument is missing.\n",
"i An input data.frame is required for the formula interface.",
call. = FALSE)
}
if (is.null(colnames(data))) {
stop("! data must have column names.", call. = FALSE)
}
if (missing(formula)) {
stop("! formula is missing.", call. = FALSE)
}
if (!inherits(formula, "formula")) {
stop("! method is only for formula objects.", call. = FALSE)
}
formula_user <- formula
formula_internal <- normalize_formula_special_namespaces(formula_user)
# Step 3: Validate that df/alpha/select/scale/shift are scalar (global)
# defaults only - per-variable settings belong in fp()/fp2() terms ---------
# The formula interface only supports scalar defaults; per-variable settings
# must be supplied via fp()/fp2() terms in the formula.
# A named value such as shift = c(x = 5) would otherwise be accepted as a
# scalar and silently applied to every predictor, so reject names here.
for (setting_name in c("df", "alpha", "select", "shift", "scale", "center")) {
if (!is.null(names(get(setting_name, inherits = FALSE)))) {
stop(
sprintf(
"! In the formula interface, `%s` must be a single unnamed value that applies to all terms.\ni Use fp(..., %s = value) to set it for an individual variable.",
setting_name, setting_name
),
call. = FALSE
)
}
}
if (length(df) != 1L) {
stop(
"! `df` must be a single numeric value.\n",
"i Use `fp()` or `fp2()` in the formula to set per-variable `df` values.",
call. = FALSE
)
}
if (length(alpha) != 1L) {
stop(
"! `alpha` must be a single numeric value.\n",
"i Use `fp()` or `fp2()` in the formula to set per-variable `alpha` values.",
call. = FALSE
)
}
if (length(select) != 1L) {
stop(
"! `select` must be a single numeric value.\n",
"i Use `fp()` or `fp2()` in the formula to set per-variable `select` values.",
call. = FALSE
)
}
if (!is.null(scale) && length(scale) != 1L) {
stop(
"! `scale` must be a single numeric value, `NA`, or `NULL`.\n",
"i Use `fp()` or `fp2()` in the formula to set per-variable `scale` values.",
call. = FALSE
)
}
if (!is.null(shift) && length(shift) != 1L) {
stop(
"! `shift` must be a single numeric value, `NA`, or `NULL`.\n",
"i Use `fp()` or `fp2()` in the formula to set per-variable `shift` values.",
call. = FALSE
)
}
validate_numeric_vector(
arg = df,
name = "df",
nvars = 1L,
allow_null = FALSE,
allow_na = FALSE,
strictly_positive = TRUE
)
if (df != 1L && df %% 2L != 0L) {
stop(
"! `df` must be 1 or an even positive integer.\n",
"i Use `fp()` or `fp2()` in the formula to set per-variable `df` values.",
call. = FALSE
)
}
validate_probability_vector(
arg = alpha,
name = "alpha",
nvars = 1L
)
validate_probability_vector(
arg = select,
name = "select",
nvars = 1L
)
validate_logical_vector(
arg = center,
name = "center",
allowed_lengths = 1L
)
validate_numeric_vector(
arg = scale,
name = "scale",
nvars = 1L,
allow_null = TRUE,
allow_na = TRUE,
strictly_positive = TRUE
)
validate_numeric_vector(
arg = shift,
name = "shift",
nvars = 1L,
allow_null = TRUE,
allow_na = TRUE,
strictly_positive = FALSE
)
if (!is.null(powers) && !is.list(powers)) {
stop("! powers must be a named list or NULL.", call. = FALSE)
}
# Discrete interaction forms are resolved after model.matrix() has
# created their complete treatment-contrast blocks. At that point the
# default method can enforce the linear-only rule and compute the correct
# block width for the interaction degrees of freedom.
# Evaluate formula observation arguments once, then validate them.
n_data <- nrow(data)
# Match standard formula-method lookup rules: data columns are searched first,
# followed by the normalized formula environment (which inherits the user's
# formula environment). Rebinding each argument to its resolved value prevents
# later branches from re-evaluating expressions with side effects.
weights <- eval(
weights_expr,
envir = data,
enclos = environment(formula_internal)
)
subset <- eval(
subset_expr,
envir = data,
enclos = environment(formula_internal)
)
strata <- NULL
if (!is.null(subset)) {
if (is.logical(subset)) {
if (length(subset) != n_data || anyNA(subset)) {
stop("! Logical `subset` must have one TRUE/FALSE value per row of `data` and contain no NA.", call. = FALSE)
}
} else if (is.numeric(subset)) {
if (anyNA(subset) || any(!is.finite(subset)) ||
any(subset != as.integer(subset)) || any(subset < 1L) ||
any(subset > n_data)) {
stop("! Numeric `subset` must contain valid positive integer row indices within `data`.", call. = FALSE)
}
if (anyDuplicated(subset)) {
stop("! `subset` must not contain duplicated row indices.", call. = FALSE)
}
} else {
stop("! `subset` must be either a logical vector or a numeric/integer vector of row indices.", call. = FALSE)
}
}
# Apply the same strictly-positive weight contract as the matrix interface.
# The complete user-supplied vector is validated even when `subset` is used,
# keeping the public weight rule simple and family-independent.
validate_model_weights(
weights = weights,
nobs = n_data
)
# Keep the ordinary formula path independent of subset-specific helpers.
# A genuine subset is resolved once; otherwise all data rows are retained in
# their original order.
if (is.null(subset)) {
fit_rows <- seq_len(n_data)
} else {
fit_rows <- formula_subset_rows(subset, n_data)
}
if (length(fit_rows) < 5L) {
stop(
paste0("! After subsetting, only ", length(fit_rows),
" observations remain; at least 5 are required."),
call. = FALSE
)
}
# Step 5: Build full-data and fitted model frames ----------------------------
# mf_full preserves the complete continuous values needed by automatic
# preprocessing. With subset = NULL, mf reuses mf_full; otherwise it is rebuilt
# from fit_rows and is authoritative for factor levels, contrast construction,
# the response, fitting, and prediction metadata.
# This mirrors standard formula-model behavior after the preprocessing source
# has been fixed.
mf_full <- stats::model.frame(
formula_internal,
data = data,
drop.unused.levels = TRUE,
na.action = stats::na.fail
)
# Reuse the complete frame when no subset was requested. For a genuine subset,
# create a retained-row frame and drop unused factor levels before model.matrix()
# rebuilds the fitted categorical coding.
if (is.null(subset)) {
mf <- mf_full
} else {
# Do not pass the local `fit_rows` symbol through model.frame(subset = ...):
# model.frame() would re-evaluate it in the formula/data environment.
mf <- subset_formula_model_frame(mf_full, fit_rows)
}
labels <- attr(terms(mf), "term.labels")
if (length(labels) == 0L)
stop("! No predictors found in formula. At least one predictor is required.",
call. = FALSE)
# Step 6: Extract strata() terms for survival models ------------------------
# ---------------------------------------------------------------------------
# Handle strata terms for survival models
# ---------------------------------------------------------------------------
specials <- "strata"
terms_formula <- stats::terms(
formula_internal,
specials = specials,
data = data
)
terms_drop <- NULL
formula_strata_terms <- NULL
formula_strata_xlevels <- NULL
formula_offset_terms <- NULL
formula_offset_xlevels <- NULL
if (!is.null(attr(terms_formula, "specials")$strata)) {
if (mfp2_family_is_survival(family_string)) {
stemp <- survival::untangle.specials(
terms_formula,
special = "strata",
order = 1
)
strata_formula <- stats::reformulate(stemp$vars)
environment(strata_formula) <- environment(formula_internal)
formula_strata_terms <- stats::terms(
strata_formula,
data = data
)
formula_strata_xlevels <- .getXlevels(formula_strata_terms, mf)
strata <- if (length(stemp$vars) == 1L) {
mf[[stemp$vars]]
} else {
do.call(
survival::strata,
c(as.list(mf[, stemp$vars, drop = FALSE]), list(shortlabel = TRUE))
)
}
terms_drop <- stemp$terms
} else {
stop("! strata are only allowed for survival models.\n",
"i Please remove strata terms from the formula.", call. = FALSE)
}
}
terms_model <- if (!is.null(terms_drop)) terms_formula[-terms_drop]
else terms_formula
validate_formula_factor_levels(terms_model, mf)
# Step 7: Identify categorical formula terms before model.matrix() expands
# them. Both unordered and ordered factors are retained using their configured
# contrasts and are grouped for joint adjustment-model selection.
factor_term_labels <- identify_formula_factor_terms(terms_model, mf)
conceptual_term_names <- formula_conceptual_term_names(terms_model, mf)
# Retain the original formula-label -> conceptual-term relationship for
# prediction. This map is updated below when fp()/fp2() expressions are
# renamed to their source-variable names.
formula_prediction_term_names <- conceptual_term_names
factor_terms <- unname(conceptual_term_names[factor_term_labels])
# Step 8: Extract an offset() term from the formula, if present ------------
# ---------------------------------------------------------------------------
# Handle offset
# ---------------------------------------------------------------------------
offset <- NULL
term_offset <- attr(terms_formula, "offset")
if (!is.null(term_offset) && length(term_offset) > 1L)
stop("! Only one offset term is allowed in the formula.", call. = FALSE)
if (!is.null(term_offset)) {
# Always extract offset from model frame when formula contains offset().
# Also keep the offset expression itself so predict.mfpi() can rebuild
# expressions such as offset(log(exposure)) from raw newdata.
offset <- stats::model.offset(mf)
if (!identical(family_string, "multinomial")) offset <- as.vector(offset)
offset_call <- attr(terms_formula, "variables")[[term_offset + 1L]]
offset_formula <- stats::as.formula(
call("~", offset_call),
env = environment(formula_internal)
)
formula_offset_terms <- stats::terms(
offset_formula,
data = data
)
formula_offset_xlevels <- .getXlevels(formula_offset_terms, mf)
}
# Step 9: Extract y, build the model matrix, and drop the intercept --------
# ---------------------------------------------------------------------------
# Extract y and x
# ---------------------------------------------------------------------------
y <- stats::model.extract(mf, "response")
if (!mfp2_family_is_survival(family_string) && survival::is.Surv(y))
stop(sprintf(
paste0(
"! Response is a Surv object but family = '%s'. Use family = 'cox' ",
"or survreg_family() as appropriate."
),
family_string
), call. = FALSE)
# Build the two designs independently. x is the actual fitted design and may
# have fewer or differently coded factor columns after unused levels are
# dropped. x_full is used only to recover full-data preprocessing values for
# stable, same-named continuous columns.
x_full <- stats::model.matrix(terms_model, mf_full)
x <- stats::model.matrix(terms_model, mf)
# Developer note: save formula reconstruction metadata before modifying the
# model matrix. The subsequent intercept removal, factor-group handling, and
# fp()/fp2() renaming can otherwise drop or obscure these attributes. These
# fields allow predict.mfpi() to rebuild the same design from
# ordinary formula-style newdata.
x_contrasts <- attr(x, "contrasts")
x_xlevels <- .getXlevels(terms_model, mf)
# Save the assign attribute before subsetting (matrix subsetting drops it)
x_assign <- attr(x, "assign")
# Remove intercept column (entry 0 in model.matrix "assign" attribute)
if (0L %in% x_assign) {
intercept_col <- which(x_assign == 0L)
x <- x[, -intercept_col, drop = FALSE]
x_assign <- x_assign[-intercept_col]
}
full_assign <- attr(x_full, "assign")
if (0L %in% full_assign) {
x_full <- x_full[, full_assign != 0L, drop = FALSE]
}
# Map conceptual terms to the exact raw design columns they generated.
# Simple factor wrappers use the source variable name, while model.matrix()
# column names such as factor(stage)II remain unchanged.
term_labels <- attr(terms_model, "term.labels")
term_to_columns <- build_formula_term_to_columns(
x_columns = colnames(x),
assign = x_assign,
term_labels = term_labels,
conceptual_names = conceptual_term_names
)
# Step 10: Convert a categorical group_var into a numeric column ----------
# ---------------------------------------------------------------------------
# Handle categorical group_var from the original data.
# model.matrix() expands factor/character predictors into dummy columns, so
# the original column name may disappear. mfpi.default() expects group_var as
# a single numeric column. We therefore remove any dummy columns for group_var
# and add back numeric codes, while preserving the original labels as a matrix
# attribute for downstream reporting.
# ---------------------------------------------------------------------------
group_levels_original <- NULL
if (!is.null(group_var)) {
gv_raw <- mf[[group_var]]
if (is.null(gv_raw)) {
stop(
"! `group_var` must be included in the model formula.\n",
sprintf("i Add `%s` to the right-hand side of the formula.", group_var),
call. = FALSE
)
}
if (is.factor(gv_raw)) {
gv_factor <- droplevels(gv_raw)
group_levels_original <- levels(gv_factor)
gv_numeric <- as.integer(gv_factor)
} else if (is.character(gv_raw)) {
group_levels_original <- unique(gv_raw)
gv_factor <- factor(gv_raw, levels = group_levels_original)
gv_numeric <- as.integer(gv_factor)
} else if (is.logical(gv_raw)) {
group_levels_original <- as.character(sort(unique(gv_raw)))
gv_numeric <- as.numeric(gv_raw)
} else {
gv_numeric <- as.numeric(gv_raw)
group_levels_original <- as.character(sort(unique(gv_numeric)))
}
if (!group_var %in% colnames(x)) {
# group_var was expanded by model.matrix. Identify and remove its dummies
# using the saved assign attribute.
gv_term_idx <- which(term_labels == group_var)
if (length(gv_term_idx) == 1L) {
gv_cols <- which(x_assign == gv_term_idx)
if (length(gv_cols) > 0L) {
x <- x[, -gv_cols, drop = FALSE]
x_assign <- x_assign[-gv_cols]
}
}
x <- cbind(x, gv_numeric)
colnames(x)[ncol(x)] <- group_var
}
# group_var is handled by MFPI's dedicated categorical-group machinery, not
# as a grouped adjustment term. Keep it as one singleton conceptual term.
term_to_columns[[group_var]] <- group_var
attr(x, "mfpi_group_levels_original") <- group_levels_original
}
nx <- ncol(x)
names_x <- colnames(x)
# Step 11: Detect fp()/fp2() terms and rename their columns to plain
# variable names, then initialize per-variable option lists from the
# global scalar defaults ----------------------------------------------------
# ---------------------------------------------------------------------------
# Detect fp()/fp2() terms in the model frame and extract their attributes
# ---------------------------------------------------------------------------
fp_pos <- which(is_fp_term(colnames(mf)))
# ---------------------------------------------------------------------------
# Resolve final variable names: fp()/fp2() terms rename to raw variable names in x.
# We do the rename now so all parameter lists use the correct final names.
# ---------------------------------------------------------------------------
if (length(fp_pos) > 0L) {
# Term settings are read from the full-data frame so that a formula
# `subset` can never affect them.
fp_data_pre <- formula_fp_settings_frame(mf, mf_full, fp_pos)
fp_vars_pre <- unname(vapply(fp_data_pre, function(v) attr(v, "name"), character(1L)))
fp_x_pos <- which(is_fp_term(names_x))
if (length(fp_x_pos) != length(fp_vars_pre)) {
stop(
"! Internal formula parsing error: the number of fp()/fp2() terms in the model matrix does not match the model frame.",
call. = FALSE
)
}
old_fp_names <- names_x[fp_x_pos]
names_x <- replace(names_x, fp_x_pos, fp_vars_pre)
colnames(x) <- names_x
full_fp_pos <- which(is_fp_term(colnames(x_full)))
if (length(full_fp_pos) != length(fp_vars_pre)) {
stop(
"! Internal formula parsing error: full-data and fitted fp()/fp2() columns do not align.",
call. = FALSE
)
}
colnames(x_full)[full_fp_pos] <- fp_vars_pre
# Keep the conceptual lookup aligned with the renamed fp()/fp2() columns.
# formula_conceptual_term_names() already maps each original fp() formula
# label to its source-variable name for prediction metadata.
for (i in seq_along(old_fp_names)) {
fp_column <- old_fp_names[[i]]
fp_var <- fp_vars_pre[[i]]
if (fp_var %in% names(term_to_columns)) {
term_to_columns[[fp_var]] <- ifelse(
term_to_columns[[fp_var]] == fp_column,
fp_var,
term_to_columns[[fp_var]]
)
}
}
}
# Initialise per-variable parameter lists from global defaults.
df_list <- setNames(rep(list(df), nx), names_x)
shift_list <- if (is.null(shift)) {
setNames(rep(list(NA_real_), nx), names_x)
} else {
setNames(rep(list(shift), nx), names_x)
}
scale_list <- if (is.null(scale)) {
setNames(rep(list(NA_real_), nx), names_x)
} else {
setNames(rep(list(scale), nx), names_x)
}
center_list <- setNames(rep(list(center), nx), names_x)
alpha_list <- setNames(rep(list(alpha), nx), names_x)
select_list <- setNames(rep(list(select), nx), names_x)
# acdx, zero, catzero, spike: initialise to FALSE for all variables.
# Overridden below only for variables wrapped in fp(). Argument-level
# zero_vars / catzero_vars / spike_vars are merged separately after.
acdx_list <- setNames(rep(list(FALSE), nx), names_x)
zero_list <- setNames(rep(list(FALSE), nx), names_x)
catzero_list <- setNames(rep(list(FALSE), nx), names_x)
spike_list <- setNames(rep(list(FALSE), nx), names_x)
force_max_fp_list <- setNames(rep(list(FALSE), nx), names_x)
# Default FP candidate powers (Royston and Altman, 1994)
powx <- c(-2, -1, -0.5, 0, 0.5, 1, 2, 3)
power_list <- setNames(replicate(nx, powx, simplify = FALSE), names_x)
# Override with user-supplied powers argument (before fp() overrides)
if (!is.null(powers)) {
if (is.null(names(powers)) ||
length(powers) != sum(nchar(names(powers)) > 0L, na.rm = TRUE))
stop("! All elements of powers must have names.", call. = FALSE)
bad <- setdiff(names(powers), names_x)
if (length(bad) > 0L)
stop(paste0("! powers names not found in x: ",
paste(bad, collapse = ", "), "."), call. = FALSE)
fp_powers <- lapply(powers, sort)
power_list <- modifyList(power_list, Filter(Negate(is.null), fp_powers))
}
# Step 12: Apply fp()/fp2() attribute overrides onto the default lists -----
# ---------------------------------------------------------------------------
# Apply fp() term overrides
# ---------------------------------------------------------------------------
if (length(fp_pos) > 0L) {
fp_data <- fp_data_pre
# fp_vars already computed as fp_vars_pre in the rename block above;
# reuse here under the canonical name fp_vars.
fp_vars <- fp_vars_pre
# Guard against duplicated fp()/fp2() usage
dups <- fp_vars[duplicated(fp_vars)]
if (length(dups) > 0L)
stop(paste0("! Variables used more than once in fp()/fp2(): ",
paste(dups, collapse = ", "), "."), call. = FALSE)
# Guard against variables appearing both inside fp()/fp2() and as plain terms.
# colnames(mf) contains "fp(age)"/"fp2(age)" for FP terms and the response variable.
# Exclude the response (first column when LHS is present) and FP columns;
# check remaining predictor names against fp_vars.
response_pos <- attr(stats::terms(formula), "response")
response_col <- if (response_pos > 0L) names(mf)[response_pos] else character(0L)
pred_cols <- setdiff(colnames(mf), response_col)
plain_cols <- pred_cols[!is_fp_term(pred_cols)]
also_plain <- intersect(plain_cols, fp_vars)
if (length(also_plain) > 0L)
stop(paste0("! Variables in fp()/fp2() must not appear elsewhere in the formula: ",
paste(also_plain, collapse = ", "), "."), call. = FALSE)
# Note: fp()/fp2() column names were already renamed above (before list init)
# so names_x and colnames(x) already use the real variable names.
# Helper: apply fp() attribute overrides to a named default list.
# attr_name: the fp() attribute to extract.
# drop_null: if TRUE, entries where fp() returned NULL are dropped so
# the estimated default (e.g. auto shift/scale) is not overwritten.
apply_fp_override <- function(base_list, attr_name, drop_null = FALSE) {
overrides <- setNames(lapply(fp_data, attr, attr_name), fp_vars)
if (drop_null)
overrides <- Filter(Negate(is.null), overrides)
modifyList(base_list, overrides)
}
df_list <- apply_fp_override(df_list, "df")
scale_list <- apply_fp_override(scale_list, "scale", drop_null = TRUE)
shift_list <- apply_fp_override(shift_list, "shift", drop_null = TRUE)
center_list <- apply_fp_override(center_list, "center")
alpha_list <- apply_fp_override(alpha_list, "alpha")
select_list <- apply_fp_override(select_list, "select")
acdx_list <- apply_fp_override(acdx_list, "acd")
zero_list <- apply_fp_override(zero_list, "zero")
catzero_list <- apply_fp_override(catzero_list, "catzero")
spike_list <- apply_fp_override(spike_list, "spike")
force_max_fp_list <- apply_fp_override(force_max_fp_list, "force_max_fp")
# fp()/fp2() powers take precedence over the powers argument
fp_pow_override <- Filter(Negate(is.null),
setNames(lapply(fp_data, attr, "powers"), fp_vars))
conflict <- if (!is.null(powers)) {
intersect(names(fp_pow_override), names(powers))
} else {
character(0L)
}
if (length(conflict) > 0L)
warning(paste0("i Powers specified in both fp()/fp2() and powers argument; ",
"fp()/fp2() values take precedence for: ",
paste(conflict, collapse = ", "), "."), call. = FALSE)
power_list <- modifyList(power_list, fp_pow_override)
}
# Factor-generated contrast columns are one fixed linear adjustment term.
# Preserve their fitted contrast coding but disable FP preprocessing.
factor_columns <- unique(unlist(
term_to_columns[intersect(factor_terms, names(term_to_columns))],
use.names = FALSE
))
factor_columns <- intersect(factor_columns, names_x)
if (length(factor_columns) > 0L) {
df_list[factor_columns] <- rep(list(1L), length(factor_columns))
shift_list[factor_columns] <- rep(list(0), length(factor_columns))
scale_list[factor_columns] <- rep(list(1), length(factor_columns))
acdx_list[factor_columns] <- rep(list(FALSE), length(factor_columns))
zero_list[factor_columns] <- rep(list(FALSE), length(factor_columns))
catzero_list[factor_columns] <- rep(list(FALSE), length(factor_columns))
spike_list[factor_columns] <- rep(list(FALSE), length(factor_columns))
force_max_fp_list[factor_columns] <- rep(list(FALSE), length(factor_columns))
power_list[factor_columns] <- rep(list(1), length(factor_columns))
}
# Step 13: Convert list-form per-variable parameters to plain vectors,
# and merge fp()-derived zero/catzero/spike/acd variable names with the
# corresponding *_vars arguments ---------------------------------------------
# ---------------------------------------------------------------------------
# Convert list-form parameters to vectors / character vectors for mfpi.default
# ---------------------------------------------------------------------------
# Per-variable numeric vectors. vapply extracts the first (and only) element
# of each list slot, producing a clean named numeric vector regardless of
# whether the slot holds an auto-estimated scalar or a user override.
scale_vec <- vapply(scale_list, function(v) as.numeric(v[[1L]]), numeric(1L))
shift_vec <- vapply(shift_list, function(v) as.numeric(v[[1L]]), numeric(1L))
# df: unlist gives a named numeric vector. mfpi.default() will apply
# assign_df() cardinality overrides on top of these values.
df_vec <- unlist(df_list)
# center: unlist gives a named logical vector.
center_vec <- unlist(center_list)
# select and alpha: unlist gives named numeric vectors.
select_vec <- unlist(select_list)
alpha_vec <- unlist(alpha_list)
# acd_vars: character vector of variable names with acd = TRUE, or NULL
acdx_vec <- unlist(acdx_list)
acd_vars <- if (any(acdx_vec)) names(acdx_vec[acdx_vec]) else NULL
# zero_vars from fp(): merge with argument zero_vars
zero_fp <- unlist(zero_list)
zero_from_fp <- if (any(zero_fp)) names(zero_fp[zero_fp]) else character(0L)
zero_vars_final <- union(zero_from_fp, zero_vars)
zero_vars_final <- if (length(zero_vars_final) == 0L) NULL else zero_vars_final
# catzero_vars from fp(): merge with argument catzero_vars
catzero_fp <- unlist(catzero_list)
catzero_from_fp <- if (any(catzero_fp)) names(catzero_fp[catzero_fp]) else character(0L)
catzero_vars_final <- union(catzero_from_fp, catzero_vars)
catzero_vars_final <- if (length(catzero_vars_final) == 0L) NULL else catzero_vars_final
# spike_vars from fp(): merge with argument spike_vars
spike_fp <- unlist(spike_list)
spike_from_fp <- if (any(spike_fp)) names(spike_fp[spike_fp]) else character(0L)
spike_vars_final <- union(spike_from_fp, spike_vars)
spike_vars_final <- if (length(spike_vars_final) == 0L) NULL else spike_vars_final
# force_max_fp_vars from fp(): merge with argument force_max_fp_vars
fmfp_fp <- unlist(force_max_fp_list)
fmfp_from_fp <- if (any(fmfp_fp)) names(fmfp_fp[fmfp_fp]) else character(0L)
force_max_fp_vars_final <- union(fmfp_from_fp, force_max_fp_vars)
force_max_fp_vars_final <- if (length(force_max_fp_vars_final) == 0L) NULL else force_max_fp_vars_final
# Expand formula-term keep entries using exact term-to-column mapping. This
# keeps all contrast columns of a categorical term together.
if (!is.null(keep)) {
valid_keep <- unique(c(
colnames(x),
names(term_to_columns),
names(formula_prediction_term_names)
))
bad_keep <- setdiff(keep, valid_keep)
if (length(bad_keep) > 0L) {
stop(
paste0("! Unknown variable(s) in keep: ", paste(bad_keep, collapse = ", "), "."),
call. = FALSE
)
}
keep <- unique(unlist(lapply(keep, function(value) {
if (value %in% colnames(x)) {
return(value)
}
conceptual_name <- if (value %in% names(formula_prediction_term_names)) {
unname(formula_prediction_term_names[[value]])
} else {
value
}
term_to_columns[[conceptual_name]]
}), use.names = FALSE))
}
# Supply all categorical mappings to the grouped MFP adjustment core,
# including binary factors that generate one non-identity dummy column.
grouped_formula_terms <- term_to_columns[
intersect(factor_terms, names(term_to_columns))
]
if (length(grouped_formula_terms) > 0L) {
grouped_formula_terms <- grouped_formula_terms[
mapped_term_flags(grouped_formula_terms)
]
}
if (length(grouped_formula_terms) == 0L) grouped_formula_terms <- NULL
# Step 14: Delegate using the subset-specific fitting design ----------------
# The private attribute transports the full-data preprocessing source and
# tells mfpi.default() that the fitting matrix has already been subset. The
# default method performs zero-specific support validation before the general
# singleton-column variation check.
x <- attach_formula_preprocess_matrix(x, x_full)
if (!is.null(subset)) {
if (!is.null(weights)) weights <- weights[fit_rows]
}
# ---------------------------------------------------------------------------
# Delegate to mfpi.default
# ---------------------------------------------------------------------------
fit <- mfpi.default(
x = x,
y = y,
group_var = group_var,
interaction_vars = interaction_vars,
interaction_forms = interaction_forms,
flex = flex,
p_interact = p_interact,
min_improvement = min_improvement,
include_group_var = include_group_var,
show_models = show_models,
weights = weights,
offset = offset,
cycles = cycles,
scale = scale_vec,
shift = shift_vec,
df = df_vec,
center = center_vec,
subset = NULL,
family = family,
fitter = fitter,
criterion = criterion,
select = select_vec,
alpha = alpha_vec,
keep = keep,
force_max_fp_vars = force_max_fp_vars_final,
xorder = xorder,
powers = power_list,
ties = ties,
strata = strata,
nocenter = nocenter,
acd_vars = acd_vars,
zero_vars = zero_vars_final,
catzero_vars = catzero_vars_final,
spike_vars = spike_vars_final,
min_saz_prop = min_saz_prop,
ftest = ftest,
control = control,
winsorize = winsorize,
winsorize_probs = winsorize_probs,
center_type = center_type,
p_adjust_method = p_adjust_method,
verbose = verbose,
digits = digits,
term_groups = grouped_formula_terms
)
fit$formula_interface <- TRUE
fit$formula <- formula_user
fit$formula_terms <- stats::delete.response(terms_model)
fit$formula_contrasts <- x_contrasts
fit$formula_xlevels <- x_xlevels
# predict.mfpi() needs to know the final fit-time column names after intercept
# removal, group-variable replacement, and fp() renaming.
fit$formula_design_columns <- colnames(x)
fit$formula_term_to_columns <- term_to_columns
fit$formula_prediction_term_names <- formula_prediction_term_names
fit$formula_factor_terms <- factor_terms
fit$formula_offset_terms <- formula_offset_terms
fit$formula_offset_xlevels <- formula_offset_xlevels
fit$formula_strata_terms <- formula_strata_terms
fit$formula_strata_xlevels <- formula_strata_xlevels
# Replace design-pattern labels for formula-supplied discrete interactions
# with the original binary/factor levels. The corresponding contrast rows are
# retained so prediction and plotting can evaluate one point per level
# without recomputing or guessing the fit-time coding.
for (term in interaction_vars) {
spec <- fit$interaction_specs[[term]]
if (is.null(spec) || !isTRUE(spec$discrete) || !term %in% names(mf)) next
raw_term <- mf[[term]]
level_labels <- if (is.factor(raw_term)) {
levels(droplevels(raw_term))
} else if (is.character(raw_term)) {
unique(raw_term)
} else if (is.logical(raw_term)) {
as.character(sort(unique(raw_term)))
} else {
as.character(sort(unique(raw_term)))
}
raw_labels <- as.character(raw_term)
first_rows <- match(level_labels, raw_labels)
if (anyNA(first_rows)) next
spec$level_labels <- level_labels
spec$level_design <- x[first_rows, spec$columns, drop = FALSE]
spec$formula_discrete <- TRUE
fit$interaction_specs[[term]] <- spec
}
fit$call <- call
fit
}
#' Continuous Interaction Columns That Receive an FP Interaction Form
#'
#' Returns the design columns of continuous interaction variables whose
#' resolved interaction form is not `"linear"`. These columns are
#' FP-transformed during the interaction search, so they need strictly
#' positive values regardless of the df used for them in the adjustment model.
#'
#' @param interaction_specs Named list returned by `mfpi_interaction_specs()`.
#' @param interaction_forms Named character vector of resolved forms.
#'
#' @return Character vector of column names (possibly empty).
#' @keywords internal
#' @noRd
mfpi_fp_interaction_columns <- function(interaction_specs, interaction_forms) {
if (length(interaction_specs) == 0L) return(character(0L))
terms <- names(interaction_specs)[vapply(interaction_specs, function(spec) {
identical(spec$kind, "continuous")
}, logical(1L))]
terms <- terms[terms %in% names(interaction_forms)]
terms <- terms[unname(interaction_forms[terms]) != "linear"]
unique(unlist(lapply(interaction_specs[terms], `[[`, "columns"), use.names = FALSE))
}
#' Format unused dot arguments for error messages
#'
#' @param dots Pairlist or list of arguments captured from \code{...}.
#'
#' @return Character vector of display labels.
#'
#' @keywords internal
#' @noRd
mfpi_dot_labels <- function(dots) {
if (length(dots) == 0L) return(character(0L))
dot_names <- names(dots)
if (is.null(dot_names)) {
dot_names <- rep("", length(dots))
}
named <- !is.na(dot_names) & nzchar(dot_names)
labels <- character(length(dots))
# Named arguments are labeled by name (e.g. `foo`); unnamed ones are
# labeled by a truncated deparse of their value, since there is no name to
# show for them.
labels[named] <- paste0("`", dot_names[named], "`")
if (any(!named)) {
labels[!named] <- vapply(
dots[!named],
function(z) paste(deparse(z, width.cutoff = 60L), collapse = " "),
character(1L)
)
}
labels
}
#' Reject unused dot arguments
#'
#' @param dots Pairlist or list of arguments captured from \code{...}.
#' @param context Character scalar naming the interface being validated.
#'
#' @return Invisibly returns \code{TRUE} when no arguments are supplied.
#'
#' @keywords internal
#' @noRd
mfpi_check_unused_dots <- function(dots, context) {
if (length(dots) == 0L) return(invisible(TRUE))
stop(
paste0(
"Unused argument(s) supplied to ", context, ": ",
paste(mfpi_dot_labels(dots), collapse = ", "),
"."
),
call. = FALSE
)
}
#' Prepare Predictors for the Default MFPI Method
#'
#' Converts a numeric matrix or data frame to a numeric predictor matrix while
#' preserving the grouping variable's original labels.
#'
#' In a data frame, the grouping variable may be factor, character, logical,
#' or numeric. Other predictors must be numeric or logical; logical predictors
#' are converted to numeric values.
#'
#' Group order follows factor levels, first appearance for character values,
#' or increasing order for logical and numeric values.
#'
#' @param x A numeric predictor matrix or data frame.
#' @param group_var A character string naming the grouping variable.
#' Numeric column indices are not supported.
#'
#' @return A list containing:
#' \describe{
#' \item{\code{x}}{The numeric predictor matrix.}
#' \item{\code{group_var}}{The validated grouping-variable name.}
#' \item{\code{group_input_levels}}{Numeric group values in the returned
#' matrix, in group order.}
#' \item{\code{group_levels_original}}{Original group labels corresponding
#' to \code{group_input_levels}.}
#' }
#'
#' @keywords internal
#' @noRd
prepare_mfpi_default_x <- function(x, group_var) {
# The public API requires group_var to be a column name. Do not support
# numeric column indices here, because allowing both names and positions makes
# data-frame input ambiguous and harder to document.
if (!is.character(group_var) ||
length(group_var) != 1L ||
is.na(group_var) ||
!nzchar(group_var)) {
stop("`group_var` must be a single character variable name.", call. = FALSE)
}
# Step 1: Data-frame input ---------------------------------------------------
# ---------------------------------------------------------------------------
# Data-frame input
# ---------------------------------------------------------------------------
# Data frames can preserve factor and character labels. We allow categorical
# input only for group_var, convert it to numeric codes for fitting, and keep
# the original labels separately for display.
if (is.data.frame(x)) {
# Validate names before resolving group_var. This prevents duplicate or
# malformed names from making x[[group_var]] ambiguous. The check is
# performed once per public call and is outside all MFPI fitting loops.
validate_predictor_names(names(x), object = "`x`")
# group_var must be present as a named column.
if (!group_var %in% names(x)) {
stop("`group_var` was not found in `x`.", call. = FALSE)
}
# Extract the user-supplied grouping variable before any conversion.
group_raw <- x[[group_var]]
# Missing group labels cannot be mapped reliably to internal group levels.
if (anyNA(group_raw)) {
stop("`group_var` must not contain missing values.", call. = FALSE)
}
# Convert the grouping variable to numeric input codes and preserve
# user-facing labels. The numeric input codes are not the final internal
# levels; preprocess_data() later remaps them to 0, 1, ..., K - 1.
if (is.factor(group_raw)) {
# Factor input respects the user's factor-level order. The first retained
# factor level is the reference label.
group_factor <- droplevels(group_raw)
group_levels_original <- levels(group_factor)
group_numeric <- as.integer(group_factor)
group_input_levels <- seq_along(group_levels_original)
} else if (is.character(group_raw)) {
# Character input has no explicit level order, so preserve first-seen
# order. The first distinct value encountered is the reference label.
group_levels_original <- unique(group_raw)
group_factor <- factor(group_raw, levels = group_levels_original)
group_numeric <- as.integer(group_factor)
group_input_levels <- seq_along(group_levels_original)
} else if (is.logical(group_raw)) {
# Logical input is treated as a two-level categorical variable when both
# values are observed. Sorting puts FALSE before TRUE.
group_input_levels <- sort(unique(as.numeric(group_raw)))
group_levels_original <- as.character(as.logical(group_input_levels))
group_numeric <- as.numeric(group_raw)
} else if (is.numeric(group_raw) || is.integer(group_raw)) {
# Numeric/integer input is already usable for modelling. Sorting makes the
# smallest observed value the reference level.
group_input_levels <- sort(unique(as.numeric(group_raw)))
group_levels_original <- as.character(group_input_levels)
group_numeric <- as.numeric(group_raw)
} else {
stop(
"`group_var` must be factor, character, logical, integer, or numeric.",
call. = FALSE
)
}
# Only group_var may be categorical. Other columns are not dummy-coded by
# mfpi.default(); users should either supply numeric encodings explicitly or
# use the formula method where appropriate.
non_group <- setdiff(names(x), group_var)
bad <- non_group[!vapply(x[non_group], function(z) {
is.numeric(z) || is.integer(z) || is.logical(z)
}, logical(1L))]
if (length(bad) > 0L) {
stop(
"Only `group_var` may be categorical in `mfpi.default()`. ",
"Non-group variables must be numeric, integer, or logical. ",
"Problem variable(s): ",
paste(bad, collapse = ", "),
call. = FALSE
)
}
# Work on a copy so the caller's data frame is not modified.
x_work <- x
# Replace the original grouping variable with numeric input codes.
x_work[[group_var]] <- group_numeric
# Convert logical non-group variables to numeric values so as.matrix()
# produces a numeric matrix rather than a mixed-type matrix.
for (nm in non_group) {
if (is.logical(x_work[[nm]])) {
x_work[[nm]] <- as.numeric(x_work[[nm]])
}
}
# Convert the validated data frame to the numeric matrix expected by the
# fitting internals.
x_mat <- as.matrix(x_work)
storage.mode(x_mat) <- "double"
return(list(
x = x_mat,
group_var = group_var,
group_input_levels = group_input_levels,
group_levels_original = group_levels_original
))
}
# Step 2: Matrix input --------------------------------------------------------
# ---------------------------------------------------------------------------
# Matrix input
# ---------------------------------------------------------------------------
# Matrix input preserves the historical default-method contract: the predictor
# matrix must already be numeric, and group_var must name one of its columns.
if (!is.matrix(x)) {
stop("`x` must be a matrix or data frame.", call. = FALSE)
}
# The matrix interface uses the same predictor-name contract as data-frame
# input. Validate before group_var lookup so all downstream name matching is
# unambiguous.
validate_predictor_names(colnames(x), object = "`x`")
if (!is.numeric(x)) {
stop(
"`x` must be a numeric matrix, or a data frame with only `group_var` categorical.",
call. = FALSE
)
}
if (!group_var %in% colnames(x)) {
stop("`group_var` was not found in `x`.", call. = FALSE)
}
# For numeric matrix input, the observed group values are both the input
# levels and, unless overridden by an internal formula-method attribute, the
# user-facing labels.
group_input_levels <- sort(unique(as.numeric(x[, group_var])))
# Formula input may arrive here as a numeric matrix with this attribute set.
# When present, it carries the original factor/character labels from the model
# frame. Ordinary matrix input will not have this attribute.
group_levels_original <- attr(
x,
"mfpi_group_levels_original",
exact = TRUE
)
if (is.null(group_levels_original)) {
group_levels_original <- as.character(group_input_levels)
}
list(
x = x,
group_var = group_var,
group_input_levels = group_input_levels,
group_levels_original = as.character(group_levels_original)
)
}
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.