R/mfpi_interaction_test.R

Defines functions test_interaction mfpi_stop_rank_deficient print.best_model_metrics test_interaction_impl validate_mfpi_fitted_rank validate_mfpi_design_estimability mfpi_design_rank make_best_model_metrics

#' Construct a best-model metrics row
#'
#' Creates a one-row base data frame containing the model comparison metrics
#' for a selected MFPI interaction candidate. Fractional polynomial powers are
#' stored as list-columns to preserve their numeric representation for later
#' printing, summarising, and prediction-related use.
#'
#' @param variable Character scalar. Name of the continuous variable tested for
#'   interaction.
#' @param type Character scalar. Functional form tested for `variable`, such as
#'   `"linear"`, `"fp1"`, or `"fp2"`.
#' @param fp_powers_main Numeric vector. Fractional polynomial powers selected
#'   for the main-effect function of `variable`.
#' @param fp_powers_int Numeric vector. Fractional polynomial powers selected
#'   for the interaction function of `variable`.
#' @param deviance_int Numeric scalar. Deviance of the interaction model.
#' @param deviance_diff Numeric scalar. Difference in deviance between the
#'   main-effects model and the interaction model.
#' @param df_int Numeric scalar. Degrees of freedom associated with the
#'   interaction test.
#' @param pvalue Numeric scalar. P-value for the interaction test.
#' @param df_total Numeric scalar. Total degrees of freedom used by the selected
#'   interaction model.
#' @param AIC_main Numeric scalar. Akaike information criterion of the
#'   main-effects model.
#' @param AIC_interaction Numeric scalar. Akaike information criterion of the
#'   interaction model.
#' @param BIC_main Numeric scalar. Bayesian information criterion of the
#'   main-effects model.
#' @param BIC_interaction Numeric scalar. Bayesian information criterion of the
#'   interaction model.
#'
#' @return A one-row data frame of class `"best_model_metrics"` with columns:
#'   `type`, `variable`, `fp_powers_main`, `fp_powers_int`, `deviance_int`,
#'   `deviance_diff`, `df_int`, `pvalue`, `df_total`, `AIC_main`,
#'   `AIC_interaction`, `AIC_main_minus_int`, `BIC_main`, `BIC_interaction`,
#'   and `BIC_main_minus_int`. The `fp_powers_main` and `fp_powers_int`
#'   columns are list-columns.
#'
#' @keywords internal
#' @noRd
make_best_model_metrics <- function(variable,
                                    type = NA_character_,
                                    fp_powers_main,
                                    fp_powers_int,
                                    deviance_int,
                                    deviance_diff,
                                    df_int,
                                    pvalue,
                                    df_total,
                                    AIC_main,
                                    AIC_interaction,
                                    BIC_main,
                                    BIC_interaction) {
  out <- data.frame(
    type               = type,
    variable           = variable,
    deviance_int       = deviance_int,
    deviance_diff      = deviance_diff,
    df_int             = df_int,
    pvalue             = pvalue,
    df_total           = df_total,
    AIC_main           = AIC_main,
    AIC_interaction    = AIC_interaction,
    AIC_main_minus_int = AIC_main - AIC_interaction,
    BIC_main           = BIC_main,
    BIC_interaction    = BIC_interaction,
    BIC_main_minus_int = BIC_main - BIC_interaction,
    stringsAsFactors   = FALSE,
    check.names        = FALSE
  )

  out$fp_powers_main <- I(list(fp_powers_main))
  out$fp_powers_int  <- I(list(fp_powers_int))

  out <- out[
    c(
      "type",
      "variable",
      "fp_powers_main",
      "fp_powers_int",
      "deviance_int",
      "deviance_diff",
      "df_int",
      "pvalue",
      "df_total",
      "AIC_main",
      "AIC_interaction",
      "AIC_main_minus_int",
      "BIC_main",
      "BIC_interaction",
      "BIC_main_minus_int"
    )
  ]

  class(out) <- c("best_model_metrics", "data.frame")
  out
}


# Interaction test for MFPI
#
# test_interaction() fits the main-effects and interaction models, computes
# the likelihood-ratio statistic, and assembles the full table of evaluation
# metrics (deviance, df, p-value, AIC, BIC).  It is called by every flex
# function (flex0-flex4) after the design matrices have been built.
#
# print.best_model_metrics() provides a readable console representation
# of the tibble returned inside the list.
#
# Naming conventions match the rest of the package:
#   cont_var            - continuous variable matrix (was `contvar`)
#   group_var           - grouping variable matrix   (was `catvar`)
#   ties                - Cox tie-handling            (was `method`)
#   use_ftest           - F-test flag                 (was `ftest`)
#   bestfp_main         - FP powers for main model
#   bestfp_interaction  - per-group FP powers for interaction model


# -----------------------------------------------------------------------------
# MFPI design-estimability checks ---------------------------------------------
# -----------------------------------------------------------------------------

#' Check the Numerical Rank of an MFPI Design Matrix
#'
#' MFPI designs are supplied without an intercept. The augmented intercept is
#' included here for every family: ordinary regression models estimate it,
#' while proportional-hazards likelihoods are invariant to a constant shift of
#' the linear predictor. A design column combination equal to a constant is
#' therefore non-identifiable in either case.
#'
#' @param design Numeric design matrix without an intercept.
#' @param tolerance Numerical tolerance passed to [base::qr()].
#'
#' @return A list containing the augmented rank, expected rank, and names of
#'   columns identified as aliased by the QR decomposition.
#' @keywords internal
#' @noRd
mfpi_design_rank <- function(design, tolerance = 1e-7) {
  design <- as.matrix(design)
  # Rank should not depend on the physical units of a covariate. Project each
  # design column off the intercept and normalize its Euclidean norm before QR.
  # Constant columns remain exact zeros and therefore remain detectable.
  centered <- sweep(
    design,
    2L,
    colMeans(design),
    "-",
    check.margin = FALSE
  )
  column_norms <- sqrt(colSums(centered^2))
  safe_norms <- column_norms
  safe_norms[safe_norms == 0] <- 1
  standardized <- sweep(
    centered,
    2L,
    safe_norms,
    "/",
    check.margin = FALSE
  )

  augmented <- cbind("(Intercept)" = 1, standardized)
  colnames(augmented) <- make.unique(colnames(augmented), sep = "__")

  decomposition <- qr(augmented, tol = tolerance, LAPACK = FALSE)
  expected <- ncol(augmented)
  aliased <- if (decomposition$rank < expected) {
    colnames(augmented)[
      decomposition$pivot[seq.int(decomposition$rank + 1L, expected)]
    ]
  } else {
    character(0L)
  }

  list(
    rank = decomposition$rank,
    expected = expected,
    aliased = aliased
  )
}


#' Validate Selected MFPI Main and Interaction Designs
#'
#' Nominal MFPI degrees of freedom include the regression coefficients and,
#' for FP terms, the method's explicit power-search allowance. Those formulas
#' are valid only when every selected regression column is estimable. This
#' helper rejects a selected design before outcome-model fitting when a group
#' lacks enough transformed within-group variation or either complete design
#' is rank deficient.
#'
#' @param cont_var One-column continuous-variable matrix.
#' @param group_var One-column grouping-variable matrix.
#' @param xmain,xinteraction Selected main-effects and interaction designs.
#' @param degree Non-negative FP degree; zero denotes the linear form.
#' @param flex MFPI flexibility label used in diagnostics.
#' @param tolerance Numerical tolerance passed to [base::qr()].
#'
#' @return Invisibly `TRUE`.
#' @keywords internal
#' @noRd
validate_mfpi_design_estimability <- function(cont_var,
                                               group_var,
                                               xmain,
                                               xinteraction,
                                               degree,
                                               flex,
                                               linear_width = 1L,
                                               tolerance = 1e-7) {
  cont_name <- colnames(cont_var)
  if (is.null(cont_name) || length(cont_name) == 0L || any(!nzchar(cont_name))) {
    cont_name <- "<unnamed>"
  } else {
    cont_name <- paste(cont_name, collapse = ", ")
  }

  designs <- list(`main-effects` = xmain, interaction = xinteraction)
  n <- NROW(group_var)
  for (design_name in names(designs)) {
    design <- designs[[design_name]]
    if (!is.matrix(design) || !is.numeric(design) || NROW(design) != n) {
      stop(
        sprintf(
          "Internal MFPI error: the %s design for '%s' must be a numeric matrix with %d rows.",
          design_name, cont_name, n
        ),
        call. = FALSE
      )
    }
    if (is.null(colnames(design)) || any(!nzchar(colnames(design)))) {
      stop(
        sprintf(
          "Internal MFPI error: the %s design for '%s' must have non-empty column names.",
          design_name, cont_name
        ),
        call. = FALSE
      )
    }
    if (anyNA(design) || any(!is.finite(design))) {
      stop(
        sprintf(
          "MFPI cannot test '%s': the selected %s design contains non-finite values.",
          cont_name, design_name
        ),
        call. = FALSE
      )
    }
  }

  group_values <- as.vector(group_var)
  if (length(group_values) != n || anyNA(group_values)) {
    stop("Internal MFPI error: the grouping variable is incomplete.", call. = FALSE)
  }
  group_levels <- sort(unique(group_values))
  n_groups <- length(group_levels)
  if (n_groups < 2L) {
    stop("MFPI interaction testing requires at least two groups.", call. = FALSE)
  }

  if (!is.numeric(degree) || length(degree) != 1L || anyNA(degree) ||
      !is.finite(degree) || degree < 0 || degree != floor(degree)) {
    stop("Internal MFPI error: `degree` must be a non-negative integer.", call. = FALSE)
  }
  terms_per_group <- if (degree == 0L) as.integer(linear_width) else as.integer(degree)
  group_dummy_width <- n_groups - 1L
  focal_width <- n_groups * terms_per_group
  focal_start <- group_dummy_width + 1L
  focal_end <- group_dummy_width + focal_width

  if (ncol(xinteraction) < focal_end) {
    stop(
      sprintf(
        "Internal MFPI error: the %s interaction design for '%s' does not contain the expected %d group-specific focal columns.",
        flex, cont_name, focal_width
      ),
      call. = FALSE
    )
  }

  focal <- xinteraction[, seq.int(focal_start, focal_end), drop = FALSE]
  for (group_index in seq_len(n_groups)) {
    in_group <- group_values == group_levels[[group_index]]
    block_columns <- seq.int(
      (group_index - 1L) * terms_per_group + 1L,
      group_index * terms_per_group
    )
    group_block <- focal[in_group, block_columns, drop = FALSE]
    group_rank <- mfpi_design_rank(group_block, tolerance = tolerance)

    if (group_rank$rank < group_rank$expected) {
      alias_note <- if (length(group_rank$aliased)) {
        paste0(" Aliased column(s): ", paste(group_rank$aliased, collapse = ", "), ".")
      } else {
        ""
      }
      mfpi_stop_rank_deficient(
        paste0(
          "MFPI cannot test continuous variable '", cont_name,
          "' in group '", as.character(group_levels[[group_index]]),
          "': the selected ", flex, " focal block has rank ",
          group_rank$rank, " of ", group_rank$expected,
          " (including its within-group intercept). More within-group variation ",
          "after transformation, or a simpler functional form, is required.",
          alias_note
        ),
        call. = FALSE
      )
    }
  }

  for (design_name in names(designs)) {
    design_rank <- mfpi_design_rank(designs[[design_name]], tolerance = tolerance)
    if (design_rank$rank < design_rank$expected) {
      alias_note <- if (length(design_rank$aliased)) {
        paste0(" Aliased column(s): ", paste(design_rank$aliased, collapse = ", "), ".")
      } else {
        ""
      }
      mfpi_stop_rank_deficient(
        paste0(
          "MFPI cannot test continuous variable '", cont_name, "': the selected ",
          design_name, " design is rank deficient (rank ", design_rank$rank,
          " of ", design_rank$expected, " including the intercept).",
          alias_note,
          " Remove collinear adjustment terms or choose a simpler functional form."
        ),
        call. = FALSE
      )
    }
  }

  invisible(TRUE)
}


#' Validate Rank Reported by an MFPI Outcome-Model Fit
#'
#' The matrix check above catches structural aliasing before fitting. This
#' second boundary ensures that family-specific fitting did not nevertheless
#' lose regression rank through its own numerical or information-matrix rules.
#'
#' @param fit Result returned by `fit_model()`.
#' @param design Design matrix supplied to that fit, without an intercept.
#' @param model_name Diagnostic label (`"main-effects"` or `"interaction"`).
#' @param cont_name Name of the continuous variable under test.
#' @param family_string Normalized model-family name.
#'
#' @return Invisibly `TRUE`.
#' @keywords internal
#' @noRd
validate_mfpi_fitted_rank <- function(fit,
                                      design,
                                      model_name,
                                      cont_name,
                                      family_string) {
  # Ordinal models (rms::orm) report rank = number of slope coefficients only,

  # excluding the k-1 cut-point intercepts. The expected rank must therefore
  # count only design columns (no intercept) for ordinal. For all other
  # intercept-bearing families (GLMs, survreg), fit$rank includes the
  # intercept, so we add 1.
  if (identical(family_string, "ordinal")) {
    expected_design_rank <- ncol(design)
  } else {
    expected_design_rank <- ncol(design) + as.integer(
      mfp2_family_has_intercept(family_string)
    )
  }
  expected_rank <- expected_design_rank * if (
    identical(family_string, "multinomial")
  ) {
    if (is.null(fit$n_logits)) 1L else as.integer(fit$n_logits)
  } else {
    1L
  }
  fitted_rank <- fit$rank

  if (!is.numeric(fitted_rank) || length(fitted_rank) != 1L ||
      anyNA(fitted_rank) || !is.finite(fitted_rank)) {
    stop(
      sprintf(
        "Internal MFPI error: the fitted %s model for '%s' did not report a valid rank.",
        model_name, cont_name
      ),
      call. = FALSE
    )
  }

  if (fitted_rank < expected_rank) {
    mfpi_stop_rank_deficient(
      paste0(
        "MFPI cannot test continuous variable '", cont_name, "': the fitted ",
        model_name, " model is rank deficient (fitted rank ", fitted_rank,
        " of ", expected_rank, "). The nominal MFPI degrees of freedom are ",
        "valid only for an estimable selected design."
      ),
      call. = FALSE
    )
  }

  invisible(TRUE)
}


# -----------------------------------------------------------------------------
# test_interaction() ----------------------------------------------------------
# -----------------------------------------------------------------------------

#' Test for an Interaction Effect Between a Continuous and a Grouping Variable
#'
#' Fits the main-effects model and the interaction model using pre-built design
#' matrices, then compares them via a likelihood-ratio test. AIC and BIC for
#' both models are also computed. The function is called by every flex
#' implementation (flex0-flex4) and is not exported.
#'
#' @section Model specification:
#' Both models share the same adjustment terms (included as columns of `xmain`
#' and `xinteraction`). Let \eqn{n} be the number of observations,
#' \eqn{K} the number of groups, and \eqn{m} the FP degree (`degree`).
#'
#' **Main-effects model** (no interaction):
#' \deqn{
#'   \eta_{\text{main}}
#'   = \alpha
#'   + \boldsymbol{\beta}^{\top} \phi(x)
#'   + \sum_{k=1}^{K-1} \gamma_k \, \mathbf{1}[g = k]
#'   + \boldsymbol{\delta}^{\top} \mathbf{z}_{\text{adj}},
#' }
#' where \eqn{\phi(x)} collects the \eqn{m} FP basis functions, \eqn{\gamma_k}
#' are group main effects, and \eqn{\mathbf{z}_{\text{adj}}} are the
#' pre-transformed adjustment covariates.
#'
#' **Interaction model** (group-specific FP slopes):
#' \deqn{
#'   \eta_{\text{int}}
#'   = \alpha
#'   + \sum_{k=0}^{K-1} \boldsymbol{\beta}_k^{\top} \phi_k(x)
#'   + \sum_{k=1}^{K-1} \gamma_k \, \mathbf{1}[g = k]
#'   + \boldsymbol{\delta}^{\top} \mathbf{z}_{\text{adj}},
#' }
#' where \eqn{\phi_k(x)} uses the FP powers specific to group \eqn{k} (which
#' may or may not differ across groups depending on `flex`).
#'
#' @section Degrees of freedom:
#' The nominal degrees of freedom are determined by
#' `interaction_model_df(n_groups, degree, flex)`. They count regression
#' coefficients plus the FP power-search allowance used by the MFPI method,
#' while excluding the intercept and common adjustment terms. For an FP of
#' degree \eqn{m}, the main-effects contribution is \eqn{2m}: \eqn{m}
#' regression coefficients and \eqn{m} searched powers (a linear term is the
#' special case with one slope and no power search). For `flex1`--`flex3`,
#' \eqn{df_{\text{int}}=(K-1)m}; for `flex4`, independently searched powers
#' add a second \eqn{(K-1)m}, giving
#' \eqn{df_{\text{int}}=2(K-1)m}. `flex0` uses \eqn{K-1} df.
#'
#' These nominal formulas assume that all selected regression columns are
#' estimable. Before fitting, the complete main and interaction designs and
#' every group-specific transformed focal block are checked for full rank.
#' The ranks reported by the fitted models are checked again afterward. A
#' deficient design is rejected with a variable/group diagnostic rather than
#' being assigned nominal test or information-criterion degrees of freedom.
#' Under `flex3` and `flex4`, different selected FP families can additionally
#' make the comparison non-nested; see `interaction_model_df()` for details.
#'
#' @section Likelihood-ratio and F-test statistics:
#' Let \eqn{\ell_{\text{main}}} and \eqn{\ell_{\text{int}}} denote the
#' maximised log-likelihoods of the two models. The deviance difference is
#' \deqn{
#'   T = -2\ell_{\text{main}} - \bigl(-2\ell_{\text{int}}\bigr)
#'     = -2\bigl(\ell_{\text{main}} - \ell_{\text{int}}\bigr) \;\geq\; 0.
#' }
#' When \code{use_ftest = FALSE} (default, or for non-Gaussian families),
#' the p-value uses the chi-square approximation:
#' \deqn{p = \Pr\!\bigl[\chi^2(df_{\text{int}}) > T\bigr].}
#' When \code{use_ftest = TRUE} and \code{family = "gaussian"}, the F-test
#' of Royston and Sauerbrei (see \code{calculate_f_test()}) is used
#' instead:
#' \deqn{F = \frac{d_2}{d_1}
#'   \left(\exp\!\left(\frac{T}{n}\right) - 1\right),}
#' where \eqn{d_1=df_{\text{int}}} is the nominal MFPI interaction df,
#' including its applicable power-search allowance. The denominator df
#' \eqn{d_2} is the fitted interaction-model residual df minus the
#' interaction model's power-search allowance. The fitted residual df already
#' accounts for the intercept and adjustment variables. The p-value is
#' \eqn{\Pr[F(d_1, d_2) > F_{\text{obs}}]}.
#'
#' @section Information criteria:
#' AIC and BIC penalise model complexity differently:
#' \deqn{
#'   \mathrm{AIC} = -2\ell + 2p, \qquad
#'   \mathrm{BIC} = -2\ell + p\log(n^*),
#' }
#' where \eqn{p} is the number of model parameters (excluding intercepts and
#' adjustment terms, as these are common across models and do not affect
#' comparisons), and \eqn{n^*} is the effective sample size
#' (\eqn{n^* =} number of events for Cox models;
#' \eqn{n^* = n} otherwise).
#' Positive values of
#' \eqn{\mathrm{AIC}_{\text{main}} - \mathrm{AIC}_{\text{int}}} and
#' \eqn{\mathrm{BIC}_{\text{main}} - \mathrm{BIC}_{\text{int}}} indicate
#' that the interaction model fits better.
#'
#' @param y Response accepted by the resolved fitting family, including
#'   [survival::Surv()] responses for survival models.
#' @param cont_var A one-column numeric matrix of the continuous variable.
#'   Must have a column name.
#' @param group_var A one-column numeric matrix of the grouping variable.
#'   Must have a column name. Values must not be expanded into dummies before
#'   being passed here (that is done internally).
#' @param xmain Numeric design matrix for the main-effects model. Columns
#'   contain the FP-transformed continuous variable, group dummy variables,
#'   and pre-transformed adjustment covariates.
#' @param xinteraction Numeric design matrix for the interaction model.
#'   Columns contain the group-specific FP-transformed variables, group dummy
#'   variables, and adjustment covariates.
#' @param degree Non-negative integer. FP degree: `0` for linear, `1` for
#'   FP1, `2` for FP2.
#' @param bestfp_main Numeric vector of the FP powers used in the main-effects
#'   model for `cont_var`.
#' @param bestfp_interaction Named list of FP power vectors, one per group,
#'   used in the interaction model.
#' @param flex Character string; `"flex0"`, `"flex1"`, `"flex2"`, `"flex3"`,
#'   or `"flex4"`. Passed to `interaction_model_df()`.
#' @param use_ftest Logical. If \code{TRUE} and \code{family = "gaussian"},
#'   use an F-test rather than a chi-square likelihood-ratio test for the
#'   interaction p-value. The F-statistic uses the formula from the Stata FP
#'   manual (Royston and Sauerbrei), with residual df taken directly from the
#'   fitted interaction model to correctly account for adjustment variables.
#'   Ignored (chi-square used) for non-Gaussian families. Default \code{FALSE}.
#' @param family Resolved likelihood-GLM, negative-binomial, Cox, or `survreg`
#'   family specification.
#' @param weights Numeric vector of observation weights, length \eqn{n}.
#' @param offset Numeric vector of linear-predictor offsets, length \eqn{n}.
#' @param ties Character string; Cox tie-handling method - `"breslow"` or
#'   `"efron"`. `"exact"` is rejected by the public MFP/MFPI interfaces before
#'   selection. Ignored for other families.
#' @param strata Optional normalized Cox or `survreg` stratum.
#' @param control Fitting control list for the resolved model family.
#' @param nocenter Numeric vector for Cox centring suppression; see
#'   [survival::coxph()].
#'
#' @return A list with five components:
#' \describe{
#'   \item{`evaluation_metrics`}{A data frame of class
#'     `"best_model_metrics"` with one row per call, containing:
#'     `variable`, `fp_powers_main`, `fp_powers_int`,
#'     `deviance_int` (\eqn{-2\ell_{\text{int}}}),
#'     `deviance_diff` (\eqn{T}),
#'     `df_int` (\eqn{df_{\text{int}}}),
#'     `pvalue`,
#'     `df_total` (total df of the interaction model),
#'     `AIC_main`, `AIC_interaction`,
#'     `AIC_main_minus_int` (\eqn{\mathrm{AIC}_{\text{main}} - \mathrm{AIC}_{\text{int}}}),
#'     `BIC_main`, `BIC_interaction`,
#'     `BIC_main_minus_int` (\eqn{\mathrm{BIC}_{\text{main}} - \mathrm{BIC}_{\text{int}}}).}
#'   \item{`interaction_model`}{The fitted interaction model object returned by
#'     `fit_model()`, with `fast = FALSE` so that the full coefficient
#'     vector and covariance matrix are available.}
#'   \item{`main_model`}{The fitted main-effects (no-interaction) model object
#'     returned by `fit_model()`. Preserved so that `plot.mfpi()` can draw the
#'     constant contrast \eqn{\hat\alpha^{(M)}} implied by the no-interaction
#'     model as a horizontal reference line on difference plots.}
#'   \item{`deviance_models`}{Named list with elements `main`
#'     (\eqn{-2\ell_{\text{main}}}) and `interaction`
#'     (\eqn{-2\ell_{\text{int}}}).}
#'   \item{`df`}{Named list with elements `main` (\eqn{p_{\text{main}}}),
#'     `interaction` (\eqn{p_{\text{interaction}}}), and `interaction_only`
#'     (\eqn{df_{\text{int}}}).}
#' }
#'
#' @keywords internal
#' @noRd
test_interaction_impl <- function(y, cont_var, group_var, xmain, xinteraction,
                             degree, bestfp_main, bestfp_interaction,
                             flex, use_ftest, family, family_string,
                             weights, offset, ties, strata, control,
                             nocenter, has_offset, fitter = "base",
                             linear_width = 1L) {

  cont_name  <- paste(colnames(cont_var), collapse = ", ")
  n_groups   <- length(unique(as.vector(group_var)))

  validate_mfpi_design_estimability(
    cont_var = cont_var,
    group_var = group_var,
    xmain = xmain,
    xinteraction = xinteraction,
    degree = degree,
    flex = flex,
    linear_width = linear_width
  )

  # ---------------------------------------------------------------------------
  # Fit main-effects and interaction models
  # ---------------------------------------------------------------------------
  fit_main <- fit_model(
    x        = xmain,
    y        = y,
    family   = family,
    family_string = family_string,
    fitter   = fitter,
    weights  = weights,
    offset   = offset,
    method   = ties,
    strata   = strata,
    control  = control,
    rownames = NULL,
    nocenter = nocenter,
    has_offset = has_offset,
    fast     = TRUE,
    calculate_gaussian_deviance = isTRUE(
      use_ftest && identical(family_string, "gaussian")
    ),
    keep_fit = TRUE    # retained for downstream coefficient/vcov extraction
  )

  validate_mfpi_fitted_rank(
    fit = fit_main,
    design = xmain,
    model_name = "main-effects",
    cont_name = cont_name,
    family_string = family_string
  )
  fit_interaction <- fit_model(
    x        = xinteraction,
    y        = y,
    family   = family,
    family_string = family_string,
    fitter   = fitter,
    weights  = weights,
    offset   = offset,
    method   = ties,
    strata   = strata,
    control  = control,
    rownames = NULL,
    nocenter = nocenter,
    has_offset = has_offset,
    calculate_gaussian_deviance = isTRUE(
      use_ftest && identical(family_string, "gaussian")
    ),
    fast     = FALSE   # full fit: coefficients and vcov required downstream
  )

  validate_mfpi_fitted_rank(
    fit = fit_interaction,
    design = xinteraction,
    model_name = "interaction",
    cont_name = cont_name,
    family_string = family_string
  )

  # ---------------------------------------------------------------------------
  # Deviance: -2 * log-likelihood
  # ---------------------------------------------------------------------------
  dev_main        <- -2 * fit_main$logl
  dev_interaction <- -2 * fit_interaction$logl
  deviance_diff   <- dev_main - dev_interaction   # T = -2(l_main - l_int) >= 0

  # ---------------------------------------------------------------------------
  # Degrees of freedom
  # df_int  = (K-1)*m  for flex1/flex2 (nested models)
  # differs for flex3/flex4; delegated to interaction_model_df()
  # ---------------------------------------------------------------------------
  n_logits <- if (identical(family_string, "multinomial")) {
    family$prepared$n_logits
  } else {
    1L
  }
  deg_freedom <- interaction_model_df(
    n_groups, degree, n_logits = n_logits, flex = flex,
    linear_width = linear_width
  )
  df_main     <- deg_freedom$dfmain       # p_main (excl. intercept & adj.)
  df_total    <- deg_freedom$total_df     # p_interaction (excl. intercept & adj.)
  df_int      <- deg_freedom$dfint        # df_total - df_main = (K-1)*m

  # ---------------------------------------------------------------------------
  # P-value: F-test (Gaussian only) or chi-square LRT
  # ---------------------------------------------------------------------------
  if (deviance_diff < -sqrt(.Machine$double.eps)) {

    warning(
      sprintf(
        paste0(
          "Interaction test for variable '%s' using %s was not assigned a p-value: ",
          "the fitted interaction model has a larger deviance than the main-effects model ",
          "(main deviance = %.6g, interaction deviance = %.6g, difference = %.6g). ",
          "This can occur with non-nested selected FP transformations or numerical ",
          "convergence issues. For non-nested MFPI comparisons, especially ",
          "when using flex3 or flex4, AIC or BIC can be more appropriate than a ",
          "likelihood-ratio or F-test p-value. The interaction p-value is set to NA; ",
          "AIC/BIC values are still reported."
        ),
        cont_name,
        flex,
        dev_main,
        dev_interaction,
        deviance_diff
      ),
      call. = FALSE
    )

    pvalue <- NA_real_

  } else {

    deviance_diff <- max(deviance_diff, 0)

    if (use_ftest && family_string == "gaussian") {

      # MFP2-style Gaussian deviance, not -2 * logLik. fit_model() computes
      # and stores only the scalar when F-test support is requested.
      dev_main_f <- fit_main$deviance_gaussian
      dev_int_f <- fit_interaction$deviance_gaussian

      if (!is.finite(dev_main_f) || !is.finite(dev_int_f)) {
        stop(
          "Internal error: Gaussian deviance is unavailable for MFPI F-test.",
          call. = FALSE
        )
      }

      power_df_interaction <- switch(
        flex,
        flex0 = 0L,
        flex1 = degree,
        flex2 = degree,
        flex3 = degree,
        flex4 = n_groups * degree,
        stop("Internal error: unknown flexibility level.", call. = FALSE)
      )

      df_resid_int <- fit_interaction$fit$df.residual - power_df_interaction

      ftest_result <- calculate_f_test(
        deviances = c(dev_main_f, dev_int_f),
        dfs_resid = df_resid_int,
        n_obs     = nrow(xinteraction),
        d1        = df_int
      )

      pvalue <- ftest_result$pvalue

    } else {

      pvalue <- stats::pchisq(
        deviance_diff,
        df = df_int,
        lower.tail = FALSE
      )
    }
  }

  # ---------------------------------------------------------------------------
  # AIC and BIC
  # AIC = -2l + 2p;  BIC = -2l + p * log(n*)
  # n* = number of events for Cox; n otherwise
  # ---------------------------------------------------------------------------
  if (family_string == "cox") {
    # `mfpi.default()` validates that Cox responses are right-censored Surv
    # objects before interaction testing is reached. For those objects, the
    # event/status indicator is stored in the final matrix column, but that
    # column is not guaranteed to be named "status". Use the final column
    # positionally rather than y[, "status"].
    status <- y[, ncol(y)]
    n_eff <- sum(!is.na(status) & status > 0)

    if (!is.finite(n_eff) || n_eff <= 0L) {
      stop(
        "Cox BIC requires at least one observed event.",
        call. = FALSE
      )
    }
  } else if (family_string == "multinomial") {
    n_eff <- family$prepared$effective_n
  } else {
    n_eff <- NROW(y)
  }

  AIC_main           <- dev_main        + 2          * df_main
  AIC_interaction    <- dev_interaction + 2          * df_total
  BIC_main           <- dev_main        + log(n_eff) * df_main
  BIC_interaction    <- dev_interaction + log(n_eff) * df_total

  # ---------------------------------------------------------------------------
  # Assemble evaluation metrics tibble
  # ---------------------------------------------------------------------------
  #fp_powers_main <- setNames(list(bestfp_main), cont_name)
  #fp_powers_int  <- bestfp_interaction

  metric_type <- switch(
    as.character(degree),
    `0` = "linear",
    `1` = "fp1",
    `2` = "fp2",
    paste0("fp", degree)
  )

  metrics <- make_best_model_metrics(
    variable        = cont_name,
    type            = metric_type,
    fp_powers_main  = bestfp_main,
    fp_powers_int   = bestfp_interaction,
    deviance_int    = dev_interaction,
    deviance_diff   = deviance_diff,
    df_int          = df_int,
    pvalue          = pvalue,
    df_total        = df_total,
    AIC_main        = AIC_main,
    AIC_interaction = AIC_interaction,
    BIC_main        = BIC_main,
    BIC_interaction = BIC_interaction
  )

  list(
    evaluation_metrics = metrics,
    interaction_model  = fit_interaction,
    main_model         = fit_main,
    deviance_models    = list(main = dev_main, interaction = dev_interaction),
    df                 = list(
      main               = df_main,
      interaction        = df_total,
      interaction_only   = df_int
    )
  )
}

#' Print MFPI model-evaluation metrics
#'
#' Internal S3 method used to format model-evaluation results displayed by
#' [mfpi()] and its print methods.
#'
#' @param x An object of class `"best_model_metrics"`.
#' @param ... Additional arguments passed to [print.data.frame()].
#'
#' @return Invisibly returns `x`.
#'
#' @method print best_model_metrics
#' @export
#' @noRd
print.best_model_metrics <- function(x, ...) {
  # Guard: power columns may be absent if the user subset the data frame
  # (e.g. `x[, c("type", "pvalue")]` drops fp_powers_main / fp_powers_int).
  # Only format columns that exist and are non-empty.
  if (!is.null(x$fp_powers_main) && length(x$fp_powers_main) > 0L) {
    x$fp_powers_main <- vapply(x$fp_powers_main, function(p) {
      if (is.null(p) || length(p) == 0L) "()"
      else paste0("(", paste(p, collapse = ", "), ")")
    }, character(1L))
  }

  if (!is.null(x$fp_powers_int) && length(x$fp_powers_int) > 0L) {
    x$fp_powers_int <- vapply(x$fp_powers_int, function(p_list) {
      if (is.null(p_list) || length(p_list) == 0L) return("()")
      # Flex1-3: p_list is an atomic vector; flex4: list of per-group vectors
      if (is.list(p_list)) {
        paste(
          vapply(p_list, function(p) {
            if (is.null(p) || length(p) == 0L) "()"
            else paste0("(", paste(p, collapse = ", "), ")")
          }, character(1L)),
          collapse = ", "
        )
      } else {
        paste0("(", paste(p_list, collapse = ", "), ")")
      }
    }, character(1L))
  }

  print.data.frame(as.data.frame(x), row.names = FALSE, ...)
  invisible(x)
}


#' Signal a Rank-Deficient MFPI Design
#'
#' Raises an error of class `mfpi_rank_deficient_error` so callers can add
#' context (for example selected powers and shift diagnostics) without
#' matching on message text.
#'
#' @param ... Message parts, pasted together.
#' @param call. Ignored; kept so call sites read like `stop()`.
#' @keywords internal
#' @noRd
mfpi_stop_rank_deficient <- function(..., call. = FALSE) {
  stop(structure(
    class = c("mfpi_rank_deficient_error", "error", "condition"),
    list(message = paste0(...), call = NULL)
  ))
}


#' Test One MFPI Interaction, Recording Selected Powers on Rank Failures
#'
#' Thin wrapper around `test_interaction_impl()`. If the selected design is
#' rank deficient, the selected FP powers are attached to the classed error
#' (`selected_powers`) so `evaluate_interaction_for_variable()` can explain the
#' likely cause.
#'
#' @inheritParams test_interaction_impl
#' @keywords internal
#' @noRd
test_interaction <- function(y, cont_var, group_var, xmain, xinteraction,
                             degree, bestfp_main, bestfp_interaction,
                             flex, use_ftest, family, family_string,
                             weights, offset, ties, strata, control,
                             nocenter, has_offset, fitter = "base",
                             linear_width = 1L) {
  impl_args <- mget(names(formals(test_interaction_impl)))
  # Report the selected FP vector as is when every group uses the same powers
  # (flex1-flex3); otherwise (flex4) report the distinct powers across groups.
  power_sets <- lapply(
    c(list(bestfp_main), unname(as.list(bestfp_interaction))),
    function(p) as.numeric(unlist(p, use.names = FALSE))
  )
  selected_powers <- if (all(vapply(power_sets, identical, logical(1L),
                                    power_sets[[1L]]))) {
    power_sets[[1L]]
  } else {
    sort(unique(unlist(power_sets)))
  }
  tryCatch(
    do.call(test_interaction_impl, impl_args),
    mfpi_rank_deficient_error = function(e) {
      e$selected_powers <- selected_powers
      stop(e)
    }
  )
}

Try the mfp2 package in your browser

Any scripts or data that you put into this service are public.

mfp2 documentation built on Nov. 14, 2026, 1:06 a.m.