R/mfp2_summary.R

Defines functions print.summary.mfp2 mfp2_format_model_fit_block mfp2_summary_model_fit_values mfp2_summary_model_df mfp2_summary_num mfp2_summary_fit_stats mfp2_summary_acd_definition mfp2_summary_acd_definitions mfp2_summary_formula_strings mfp2_summary_shift_scale mfp2_summary_acd_inner_expr mfp2_summary_fp_inner_expr mfp2_summary_power_expr mfp2_summary_term_label mfp2_summary_basis_table mfp2_design_column_info mfp2_factor_design_column_info mfp2_fp_basis_labels mfp2_summary_lrt_drop_variable mfp2_summary_gee_wald_term mfp2_summary_nonlinear_table mfp2_summary_refit_context mfp2_summary_coef_matrix mfp2_summary_match_coef_column mfp2_summary_exponent_label mfp2_summary_exponentiates_coefficients mfp2_summary_linear_table mfp2_summary_ordinal_intercepts mfp2_ordinal_vcov_slopes mfp2_ordinal_vcov_all mfp2_summary_coef_to_display mfp2_summary_function_overview mfp2_summary_form_label mfp2_summary_saz_is_binary_only mfp2_summary_flag mfp2_summary_columns_by_variable mfp2_summary_power_columns mfp2_summary_classify_terms NextMethod_summary mfp2_summary_raw mfp2_summary_criterion_label mfp2_print_model_specific_parameters mfp2_print_model_header mfp2_summary_survreg_censoring mfp2_print_response_frequencies mfp2_summary_model_label mfp2_print_gee_parameters mfp2_summary_gee_parameter_vcov mfp2_summary_gee_parameters mfp2_summary_model_metadata mfp2_summary_nevents mfp2_summary_response_frequencies mfp2_summary_nobs summary.mfp2

Documented in print.summary.mfp2 summary.mfp2

# =============================================================================
# summary_mfp2.R
#
# The structured summary method for `mfp2` model fits, and its dedicated
# `print` method. Provides an MFP-aware alternative to the raw
# model-specific summary output that ships from the underlying fitter,
# including `summary.survreg()` for parametric survival models.
#
# The file is organised in three sections:
#
#   1. summary.mfp2()               - the exported S3 method that returns an
#                                     object of class "summary.mfp2".
#   2. print.summary.mfp2()         - the exported S3 print method that
#                                     renders that object.
#   3. Internal helpers             - the shared computation and formatting
#                                     helpers, some of which are also used by
#                                     print.mfp2()'s Model Fit block so the
#                                     two methods stay in exact agreement.
#
# =============================================================================
#' Summarize an `mfp2` Model Fit
#'
#' Produces a structured, MFP-aware summary of a fitted [mfp2()] model. Unlike
#' the raw model-specific summary output, this
#' method separates interpretable linear terms from fractional-polynomial (FP)
#' and other nonlinear terms, whose individual coefficients are curve
#' parameters rather than per-unit effect sizes.
#'
#' For multinomial models, the structured summary reports the common selected
#' functional forms and an outcome-specific coefficient table containing the
#' estimate, standard error, z statistic, and p-value for each non-reference
#' logit. Model-fit values are reported as minus twice the log likelihood.
#'
#' @details
#' The summary is organised into the following sections:
#' \itemize{
#'   \item \strong{Selection Overview}: a compact overview of the selected
#'     functional form for each variable.
#'   \item \strong{Ordinal Intercepts}: for ordinal models, the estimated
#'     threshold intercepts with standard errors, Wald statistics, p-values,
#'     and confidence intervals.
#'   \item \strong{Linear Terms}: variables entering the model as a single
#'     linear term (including binary-only spike variables and factor levels),
#'     with the coefficient, standard error, test statistic, p-value, and
#'     confidence interval. GLM coefficients are always reported on their
#'     fitted link scale; supported survival models additionally report the
#'     usual exponentiated effect when it has a standard interpretation.
#'   \item \strong{Nonlinear Terms}: one row per variable modelled by an FP1,
#'     FP2, ACD, or spike/catzero compound form. Each row reports a joint
#'     likelihood-ratio test (LRT) of all of that variable's terms, using the
#'     package's selection-adjusted degrees of freedom. The LRT compares the
#'     final MFP model with an otherwise unchanged model that omits the variable.
#'   \item \strong{Model Fit}: full-linear and final-MFP deviances for GLMs,
#'     or minus twice the fitted likelihood for survival models (partial
#'     likelihood for Cox and Fine--Gray), with model degrees of freedom.
#'     GEE models instead show selection scores for AIC/BIC, and omit this
#'     block for p-value selection.
#' }
#'
#' The joint LRT is a diagnostic: the variable was selected by the MFP
#' procedure, not by this test. The degrees of freedom follow the
#' Royston--Sauerbrei convention used throughout the package (2 df per FP1,
#' 4 df per FP2), so the reported p-values acknowledge the FP power search
#' rather than treating the powers as fixed in advance.
#'
#' Coefficients for nonlinear terms are omitted from the default output. Set
#' \code{formulas = TRUE} to append the fitted-function formulas, or
#' \code{basis = TRUE} to append the individual fitted basis coefficients. For
#' an active ACD component, either option also prints the fitted definition of
#' \eqn{A(x)}, including the scale used during fitting. Set
#' \code{raw = TRUE} to obtain the underlying model-specific summary object
#' instead.
#'
#' The structured header names the fitted model and its link where applicable.
#' It also reports interpretation-critical nuisance parameters: the
#' distribution, fixed or estimated scale, scale strata, and censoring pattern
#' for `survreg` models; estimated or fixed dispersion for Gaussian, Gamma, and
#' inverse-Gaussian GLMs; and the estimated theta for negative-binomial models.
#' Ordinal and multinomial headers additionally report unweighted frequencies
#' of the responses used for fitting.
#'
#' @section Coefficient statistics:
#' The linear-terms table reports the coefficient statistics from the applicable
#' GLM, Cox, or `survreg` summary. For a robust Cox fit, it uses the robust
#' standard error so that the estimate, test statistic, and p-value remain
#' consistent. When these statistics cannot be read directly from a compatible
#' model summary, they are calculated from the fitted coefficients and
#' [stats::vcov()] when possible.
#'
#' @param object A fitted [mfp2()] object.
#' @param formulas Logical. If \code{TRUE}, append the fitted-function formula
#'   for each nonlinear variable. Default \code{FALSE}.
#' @param basis Logical. If \code{TRUE}, append a table of the individual fitted
#'   basis coefficients for nonlinear terms. Default \code{FALSE}.
#' @param raw Logical. If \code{TRUE}, bypass the structured summary and return
#'   the raw model-specific summary object, with
#'   the fitting call replaced by the original [mfp2()] call. Default
#'   \code{FALSE}.
#' @param notes Logical. If \code{FALSE}, suppress the explanatory model-df note
#'   when the structured summary is printed. Default \code{TRUE}.
#' @param digits Number of decimal places used when printing numeric output
#'   other than fractional-polynomial powers and degrees of freedom. Defaults
#'   to 3.
#' @param ... Further arguments. When \code{raw = TRUE}, passed to the
#'   underlying summary method; otherwise ignored.
#'
#' @return
#' When \code{raw = FALSE}, an object of class \code{"summary.mfp2"}: a list
#' with components \code{call}, \code{family}, \code{criterion},
#' \code{converged}, \code{n}, \code{nevents}, model-specific components
#' \code{distribution}, \code{scale}, \code{scale_fixed}, \code{dispersion},
#' \code{dispersion_fixed},
#' \code{scale_strata}, \code{distribution_parameters}, \code{censoring},
#' \code{link}, \code{theta}, and \code{response_frequencies}, plus \code{function_table},
#' \code{linear_terms}, \code{nonlinear_terms}, \code{basis} (or \code{NULL}),
#' \code{formulas} (or \code{NULL}), \code{acd_definitions} (or
#' \code{NULL}), \code{ordinal_intercepts} (a threshold-inference data frame
#' for ordinal models, otherwise \code{NULL}), \code{fit},
#' \code{raw_summary}, and \code{notes}. For compatibility with earlier
#' versions, it also contains \code{coefficients}, \code{cov.scaled} and
#' \code{cov.unscaled} when the underlying summary provides them (for example
#' for GLM-type models); these are not printed. For multinomial models,
#' \code{linear_terms}, \code{nonlinear_terms}, \code{basis},
#' \code{formulas}, \code{acd_definitions}, \code{ordinal_intercepts}, and
#' \code{fit} are replaced by \code{coefficients} (the outcome-specific
#' coefficient table), \code{model_fit_values}, \code{multinomial},
#' \code{class_levels}, \code{reference_class}, \code{n_logits}, and
#' \code{digits}. A dedicated \code{print} method renders these. When
#' \code{raw = TRUE}, the underlying summary object.
#'
#' @examples
#' data("prostate")
#'
#' fit <- mfp2(
#'   lpsa ~ fp(age) + svi,
#'   data = prostate,
#'   select = 1,
#'   alpha = 1,
#'   verbose = FALSE
#' )
#'
#' fit_summary <- summary(fit)
#'
#' # The standardized coefficient statistics for selected linear terms.
#' fit_summary$linear_terms
#'
#' # The original model-specific coefficient table remains available.
#' fit_summary$raw_summary$coefficients
#'
#' @seealso [mfp2()], [print.mfp2()], [stats::summary.glm()],
#'   [survival::summary.coxph()], [survival::summary.survreg()]
#'
#' @export
summary.mfp2 <- function(object,
                         formulas = FALSE,
                         basis = FALSE,
                         raw = FALSE,
                         notes = TRUE,
                         digits = 3L,
                         ...) {
  if (!inherits(object, "mfp2")) {
    stop("The object is not an mfp2 object.", call. = FALSE)
  }
  mfp2_require_geepack_for_fit(object)

  validate_logical_vector(notes, "notes", allowed_lengths = 1L)

  # ---------------------------------------------------------------------------
  # raw = TRUE: fall back to the underlying model's summary method.
  # ---------------------------------------------------------------------------
  if (isTRUE(raw)) {
    result <- NextMethod_summary(object, ...)
    if (!is.null(object$call_mfp)) {
      result$call <- object$call_mfp
    }
    return(result)
  }

  if (identical(object$family_string, "multinomial")) {
    base_object <- object
    class(base_object) <- setdiff(class(base_object), "mfp2")
    raw_summary <- summary(base_object)
    coefficients <- object$mfp2_coefficient_matrix
    standard_errors <- raw_summary$standard.errors
    if (is.null(dim(standard_errors))) {
      standard_errors <- matrix(
        standard_errors,
        nrow = nrow(coefficients),
        dimnames = dimnames(coefficients)
      )
    }
    z <- coefficients / standard_errors
    p <- 2 * stats::pnorm(abs(z), lower.tail = FALSE)
    coefficient_table <- do.call(rbind, lapply(seq_len(nrow(coefficients)), function(i) {
      data.frame(
        outcome = rownames(coefficients)[[i]],
        reference = object$reference_class,
        term = colnames(coefficients),
        coefficient = unname(coefficients[i, ]),
        se = unname(standard_errors[i, ]),
        z = unname(z[i, ]),
        p = unname(p[i, ]),
        stringsAsFactors = FALSE
      )
    }))
    out <- list(
      call = object$call_mfp,
      family = object$family_string,
      criterion = mfp2_summary_criterion_label(object),
      converged = isTRUE(object$convergence_mfp),
      n = mfp2_summary_nobs(object),
      nevents = NA_integer_,
      distribution = NULL,
      scale = NULL,
      scale_fixed = NULL,
      dispersion = NULL,
      dispersion_fixed = NULL,
      scale_strata = NULL,
      distribution_parameters = NULL,
      censoring = NULL,
      link = NULL,
      theta = NULL,
      multinomial = TRUE,
      class_levels = object$class_levels,
      reference_class = object$reference_class,
      n_logits = object$n_logits,
      response_frequencies = mfp2_summary_response_frequencies(object),
      function_table = mfp2_summary_classify_terms(object)$function_table,
      coefficients = coefficient_table,
      model_fit_values = mfp2_summary_model_fit_values(object),
      raw_summary = raw_summary,
      notes = notes,
      digits = digits
    )
    class(out) <- "summary.mfp2"
    return(out)
  }

  # ---------------------------------------------------------------------------
  # Gather the pieces.
  # ---------------------------------------------------------------------------
  classified <- mfp2_summary_classify_terms(object)
  # summary.orm() prints instead of constructing a reusable coefficient table.
  # Ordinal inference is built directly from coef() and the complete covariance
  # matrix, avoiding backend output while the structured summary is assembled.
  raw_summary <- if (mfp2_family_is_ordinal(object$family_string)) {
    NULL
  } else {
    mfp2_summary_raw(object)
  }
  model_metadata <- mfp2_summary_model_metadata(
    object,
    raw_summary = raw_summary
  )

  linear_terms <- mfp2_summary_linear_table(object, classified, raw_summary)
  nonlinear_terms <- mfp2_summary_nonlinear_table(object, classified)

  ordinal_intercepts <- if (mfp2_family_is_ordinal(object$family_string)) {
    mfp2_summary_ordinal_intercepts(object)
  } else {
    NULL
  }

  basis_table <- if (isTRUE(basis)) {
    mfp2_summary_basis_table(object, classified)
  } else {
    NULL
  }

  formula_strings <- if (isTRUE(formulas)) {
    mfp2_summary_formula_strings(object, classified, digits = digits)
  } else {
    NULL
  }

  acd_definitions <- if (isTRUE(formulas) || isTRUE(basis)) {
    mfp2_summary_acd_definitions(object, classified)
  } else {
    NULL
  }

  out <- list(
    call            = object$call_mfp,
    family          = object$family_string,
    criterion       = mfp2_summary_criterion_label(object),
    converged       = isTRUE(object$convergence_mfp),
    n               = mfp2_summary_nobs(object),
    nevents         = mfp2_summary_nevents(object),
    distribution    = model_metadata$distribution,
    scale           = model_metadata$scale,
    scale_fixed     = model_metadata$scale_fixed,
    dispersion      = model_metadata$dispersion,
    dispersion_fixed = model_metadata$dispersion_fixed,
    scale_strata    = model_metadata$scale_strata,
    distribution_parameters = model_metadata$distribution_parameters,
    censoring       = model_metadata$censoring,
    link            = model_metadata$link,
    theta           = model_metadata$theta,
    gee             = model_metadata$gee,
    gee_response_family = model_metadata$gee_response_family,
    function_table  = classified$function_table,
    linear_terms    = linear_terms,
    nonlinear_terms = nonlinear_terms,
    basis           = basis_table,
    formulas        = formula_strings,
    acd_definitions = acd_definitions,
    fit                = mfp2_summary_fit_stats(object),
    raw_summary        = raw_summary,
    exp_label          = mfp2_summary_exponent_label(object),
    ordinal_intercepts = ordinal_intercepts,
    response_frequencies = mfp2_summary_response_frequencies(object),
    notes              = notes,
    digits             = digits
  )

  # Backward compatibility with mfp2 1.0.x, where summary() dispatched to the
  # underlying summary method (for example summary.glm()). Code written for
  # that version reads components such as `summary(fit)$coefficients` or
  # `summary(fit)$cov.scaled`, so copy them from the raw summary when present.
  # They are not printed.
  out <- c(out, mfp2_summary_compat_components(raw_summary))
  class(out) <- "summary.mfp2"
  out
}


# =============================================================================
# Internal helpers
# =============================================================================

#' Number of Fitted Observations for an `mfp2` Object
#'
#' Returns the number of observations used to fit the model, robust to a
#' missing `nobs` field on the fitted object.
#'
#' @param object An `"mfp2"` model object.
#'
#' @return Integer scalar with the number of fitted observations, or
#'   `NA_integer_` if it cannot be determined.
#'
#' @keywords internal
#' @noRd
mfp2_summary_nobs <- function(object) {
  if (!is.null(object$nobs)) return(as.integer(object$nobs))
  n <- tryCatch(NROW(object$y), error = function(e) NA_integer_)
  as.integer(n)
}

#' Unweighted Response Frequencies for Categorical `mfp2` Models
#'
#' Computes the unweighted class-frequency counts displayed for a fitted
#' ordinal or multinomial `"mfp2"` model. The display follows the original
#' response order, not the reference-first reordering used internally by the
#' multinomial fitting engine. For a grouped multinomial count response, the
#' reported frequencies are column totals of the count matrix.
#'
#' @param object An `"mfp2"` model object.
#'
#' @return A named numeric vector of class frequencies, in original response
#'   order, or `NULL` when the family is not ordinal or multinomial.
#'
#' @keywords internal
#' @noRd
mfp2_summary_response_frequencies <- function(object) {
  family_string <- object$family_string
  if (!isTRUE(family_string %in% c("ordinal", "multinomial"))) return(NULL)

  response <- object$y_original
  if (is.null(response) && identical(family_string, "ordinal")) {
    response <- object$y
  }
  if (is.null(response)) return(NULL)

  if (identical(family_string, "multinomial")) {
    prepared <- if (is.list(object$mfp2_family)) {
      object$mfp2_family$prepared
    } else {
      NULL
    }
    original_levels <- if (is.list(prepared)) prepared$original_levels else NULL

    if (is.matrix(response)) {
      response_names <- colnames(response)
      if (is.null(response_names)) {
        response_names <- original_levels
      }
      if (is.null(response_names) || length(response_names) != ncol(response)) {
        response_names <- paste0("class", seq_len(ncol(response)))
      }
      totals <- stats::setNames(as.numeric(colSums(response)), response_names)
      if (!is.null(original_levels) && all(original_levels %in% names(totals))) {
        totals <- totals[original_levels]
      }
      return(totals)
    }

    if (is.null(original_levels)) {
      original_levels <- if (is.factor(response)) {
        levels(droplevels(response))
      } else {
        levels(factor(response))
      }
    }
    counts <- table(factor(as.character(response), levels = original_levels))
    return(stats::setNames(as.numeric(counts), original_levels))
  }

  ordinal_levels <- object$mfp2_ordinal_levels
  if (is.null(ordinal_levels)) ordinal_levels <- object$yunique
  if (is.null(ordinal_levels)) return(NULL)
  ordinal_levels <- as.character(ordinal_levels)

  response_values <- as.character(response)
  if (!all(response_values %in% ordinal_levels)) {
    codes <- suppressWarnings(as.integer(response))
    if (!anyNA(codes) && all(codes >= 1L & codes <= length(ordinal_levels))) {
      response_values <- ordinal_levels[codes]
    }
  }
  counts <- table(factor(response_values, levels = ordinal_levels))
  stats::setNames(as.numeric(counts), ordinal_levels)
}

#' Number of Target Events for a Proportional-Hazards `mfp2` Model
#'
#' Returns the number of target events for Cox and Fine--Gray models. Uses
#' the stored `nevents` field when present, otherwise counts `status == 1`
#' rows of a `Surv` response.
#'
#' @param object An `"mfp2"` model object.
#'
#' @return Integer scalar with the number of events, or `NA_integer_` for
#'   families that do not report event counts.
#'
#' @keywords internal
#' @noRd
mfp2_summary_nevents <- function(object) {
  if (!mfp2_family_uses_event_count(object$family_string)) return(NA_integer_)
  if (!is.null(object$nevents)) return(as.integer(object$nevents))
  y <- object$y
  if (inherits(y, "Surv")) {
    status_col <- ncol(y)
    return(as.integer(sum(y[, status_col] == 1, na.rm = TRUE)))
  }
  NA_integer_
}

#' Extract Model-Specific Interpretation Metadata
#'
#' Collects the family-specific metadata required to interpret parametric
#' survival, GLM, negative-binomial, and ordinal fits: distribution name,
#' scale (with strata table when applicable), fixed-vs-estimated flags,
#' dispersion, link function, negative-binomial `theta`, censoring summary,
#' and any extra distribution parameters. Centralising the extraction in one
#' helper guarantees that [print.mfp2()] and [print.summary.mfp2()] report
#' exactly the same values.
#'
#' @param object An `"mfp2"` model object.
#' @param family_string Canonical family name. Defaults to
#'   `object$family_string`.
#' @param raw_summary Optional raw summary produced by `mfp2_summary_raw()`,
#'   used when dispersion has to be pulled from the underlying-class summary.
#'
#' @return A named list carrying `distribution`, `scale`, `scale_fixed`,
#'   `dispersion`, `dispersion_fixed`, `scale_strata`,
#'   `distribution_parameters`, `censoring`, `link`, and `theta`. Fields not
#'   applicable to the family remain `NULL`.
#'
#' @keywords internal
#' @noRd
mfp2_summary_model_metadata <- function(object,
                                        family_string = object$family_string,
                                        raw_summary = NULL) {
  out <- list(
    distribution = NULL,
    scale = NULL,
    scale_fixed = NULL,
    dispersion = NULL,
    dispersion_fixed = NULL,
    scale_strata = NULL,
    distribution_parameters = NULL,
    censoring = NULL,
    link = NULL,
    theta = NULL
  )

  if (identical(family_string, "survreg")) {
    requested_dist <- object$mfp2_survreg_distribution
    if (is.null(requested_dist) && is.list(object$family) &&
        !is.null(object$family$dist)) {
      requested_dist <- object$family$dist
    }
    if (is.null(requested_dist)) requested_dist <- object$dist

    if (is.character(requested_dist) && length(requested_dist) == 1L) {
      distributions <- survival::survreg.distributions
      registered <- distributions[[requested_dist]]
      out$distribution <- if (!is.null(registered$name)) {
        registered$name
      } else {
        requested_dist
      }
    } else if (is.list(requested_dist) &&
               is.character(requested_dist$name) &&
               length(requested_dist$name) == 1L) {
      out$distribution <- requested_dist$name
    }

    out$scale <- if (is.numeric(object$scale)) unname(object$scale) else NULL

    scale_fixed <- object$mfp2_survreg_scale_fixed
    if (is.null(scale_fixed)) {
      family_scale <- if (is.list(object$family)) object$family$scale else NULL
      fixed_by_argument <- is.numeric(family_scale) &&
        length(family_scale) == 1L && is.finite(family_scale) && family_scale > 0
      fixed_by_distribution <- FALSE
      family_dist <- if (is.list(object$family)) object$family$dist else NULL
      if (is.character(family_dist) && length(family_dist) == 1L) {
        registered <- survival::survreg.distributions[[family_dist]]
        fixed_by_distribution <- !is.null(registered$scale)
      } else if (is.list(family_dist)) {
        fixed_by_distribution <- !is.null(family_dist$scale)
      }
      scale_fixed <- fixed_by_argument || fixed_by_distribution
    }
    out$scale_fixed <- isTRUE(scale_fixed)

    if (length(out$scale) > 1L) {
      strata <- object$mfp2_strata_levels
      if (is.null(strata) || length(strata) != length(out$scale)) {
        strata <- names(object$scale)
      }
      if (is.null(strata) || length(strata) != length(out$scale) ||
          anyNA(strata) || any(!nzchar(as.character(strata)))) {
        strata <- as.character(seq_along(out$scale))
      }
      out$scale_strata <- data.frame(
        stratum = as.character(strata),
        scale = out$scale,
        stringsAsFactors = FALSE,
        check.names = FALSE
      )
    }

    parms <- object$mfp2_survreg_parms
    if (is.null(parms) && !is.null(object$parms)) parms <- object$parms
    if (is.numeric(parms) && length(parms) > 0L) {
      out$distribution_parameters <- parms
    }

    out$censoring <- mfp2_summary_survreg_censoring(object)
  }

  if (identical(family_string, "negbin")) {
    link <- if (is.list(object$family)) object$family$link else NULL
    if (is.function(link)) link <- NULL
    if (is.character(link) && length(link) == 1L && !is.na(link)) {
      out$link <- link
    } else {
      # Fits without stored family metadata used the original log link.
      out$link <- "log"
    }
    if (is.numeric(object$theta) && length(object$theta) == 1L &&
        is.finite(object$theta) && object$theta > 0) {
      out$theta <- unname(object$theta)
    }
  }

  if (isTRUE(mfp2_family_is_glm(family_string)) &&
      !identical(family_string, "negbin")) {
    link <- if (is.list(object$family)) object$family$link else NULL
    if (is.character(link) && length(link) == 1L && !is.na(link) &&
        nzchar(link)) {
      out$link <- link
    }
  }

  if (identical(family_string, "gee")) {
    rfs <- object$family$response_family_string
    if (is.character(rfs) && length(rfs) == 1L && nzchar(rfs)) {
      out$gee_response_family <- rfs
    }
    # The link for GEE lives in the geese model structure; extract it so the
    # model label can report e.g. "Gaussian GEE (identity link)".
    geese <- object$geese
    gee_link <- if (is.list(geese) && is.list(geese$model)) {
      geese$model$mean.link
    } else {
      NULL
    }
    if (is.character(gee_link) && length(gee_link) == 1L && nzchar(gee_link)) {
      out$link <- gee_link
    }
  }

  # Gaussian, Gamma, and inverse-Gaussian GLMs estimate (or may explicitly
  # fix) a dispersion parameter in the underlying fitting function. Preserve
  # that native value and terminology; do not derive an SD, Gamma shape, or
  # any other transformed quantity for the custom mfp2 display.
  if (isTRUE(family_string %in% c(
    "gaussian", "Gamma", "inverse.gaussian"
  ))) {
    family_dispersion <- if (is.list(object$family)) {
      object$family$dispersion
    } else {
      NULL
    }
    fixed_dispersion <- is.numeric(family_dispersion) &&
      length(family_dispersion) == 1L && is.finite(family_dispersion) &&
      family_dispersion > 0

    if (fixed_dispersion) {
      out$dispersion <- unname(family_dispersion)
      out$dispersion_fixed <- TRUE
    } else {
      if (is.null(raw_summary)) raw_summary <- mfp2_summary_raw(object)
      fitted_dispersion <- if (!is.null(raw_summary)) {
        raw_summary$dispersion
      } else {
        NULL
      }
      if (is.numeric(fitted_dispersion) &&
          length(fitted_dispersion) == 1L &&
          is.finite(fitted_dispersion) && fitted_dispersion > 0) {
        out$dispersion <- unname(fitted_dispersion)
        out$dispersion_fixed <- FALSE
      }
    }
  }

  if (mfp2_family_is_ordinal(family_string)) {
    link <- object$mfp2_ordinal_link
    if (is.character(link) && length(link) == 1L && !is.na(link)) {
      out$link <- link
    }
  }

  if (identical(family_string, "gee")) {
    gee <- mfp2_summary_gee_parameters(object)
    out$gee <- gee
    out$link <- gee$link
    rfs <- object$family$response_family_string
    if (is.character(rfs) && length(rfs) == 1L && nzchar(rfs)) {
      out$gee_response_family <- rfs
    }
    if (!is.null(gee$scale)) {
      out$dispersion <- gee$scale
      out$dispersion_fixed <- isTRUE(gee$scale_fixed)
    }
  }

  out
}


#' Collect the Key Reported Parameters of a Fitted GEE Model
#'
#' Extracts the marginal-model quantities a GEE analyst reports alongside the
#' regression coefficients: the working correlation structure and its estimated
#' parameter(s), the estimated (or fixed) scale/dispersion, the robust
#' standard-error type, the inner response link, and the cluster structure.
#'
#' @param object A fitted `mfp2` GEE object (carrying its `geeglm` `geese`
#'   component).
#'
#' @return A named list with `corstr`, `correlation`, `correlation_se`,
#'   `scale`, `scale_se`, `scale_fixed`, `std_err`, `link`, `n_clusters`, and
#'   `max_cluster_size`.
#'
#' @keywords internal
#' @noRd
mfp2_summary_gee_parameters <- function(object) {
  geese <- object$geese
  model <- if (is.list(geese)) geese$model else NULL

  std_err <- object$std.err
  if (is.null(std_err) || !nzchar(std_err)) std_err <- NA_character_

  corstr <- object$corstr
  if (is.null(corstr) && is.list(model)) corstr <- model$corstr
  if (is.null(corstr)) corstr <- NA_character_

  alpha <- if (!is.null(geese$alpha) && length(geese$alpha) > 0L) {
    unname(geese$alpha)
  } else {
    NULL
  }

  # Select the same covariance family as the regression coefficients. geepack
  # stores parallel sandwich/jackknife fields for alpha and gamma.
  alpha_vcov <- mfp2_summary_gee_parameter_vcov(
    geese, parameter = "alpha", std_err = std_err
  )
  alpha_se <- if (!is.null(alpha) && !is.null(alpha_vcov) &&
                  length(alpha_vcov) > 0L) {
    v <- suppressWarnings(sqrt(diag(as.matrix(alpha_vcov))))
    if (length(v) == length(alpha) && all(is.finite(v))) unname(v) else NULL
  } else {
    NULL
  }

  scale_est <- if (!is.null(geese$gamma) && length(geese$gamma) > 0L) {
    unname(geese$gamma[[1L]])
  } else {
    NULL
  }
  scale_fixed <- isTRUE(model$scale.fix)

  gamma_vcov <- mfp2_summary_gee_parameter_vcov(
    geese, parameter = "gamma", std_err = std_err
  )
  scale_se <- if (!is.null(scale_est) && !is.null(gamma_vcov) &&
                  length(gamma_vcov) > 0L) {
    v <- suppressWarnings(sqrt(diag(as.matrix(gamma_vcov))))
    if (length(v) >= 1L && is.finite(v[[1L]])) unname(v[[1L]]) else NULL
  } else {
    NULL
  }

  clusz <- geese$clusz
  link <- if (is.list(model)) model$mean.link else NULL

  list(
    corstr = corstr,
    correlation = alpha,
    correlation_se = alpha_se,
    scale = scale_est,
    reference_dispersion = object$reference_dispersion,
    reference_dispersion_source = object$reference_dispersion_source,
    qbic_penalty = if (identical(object$criterion_mfp, "bic"))
      object$qbic_penalty else NULL,
    scale_se = scale_se,
    scale_fixed = scale_fixed,
    std_err = std_err,
    link = link,
    n_clusters = if (!is.null(clusz)) length(clusz) else NA_integer_,
    max_cluster_size = if (!is.null(clusz)) max(clusz) else NA_integer_
  )
}

#' Select a GEE Correlation- or Scale-Parameter Covariance
#'
#' Uses exact geepack component names and mirrors the selected `std.err`
#' estimator used for beta. No coefficient or component name search is needed.
#'
#' @keywords internal
#' @noRd
mfp2_summary_gee_parameter_vcov <- function(geese, parameter, std_err) {
  parameter <- match.arg(parameter, c("alpha", "gamma"))
  if (!is.character(std_err) || length(std_err) != 1L || is.na(std_err)) {
    return(NULL)
  }

  if (identical(parameter, "alpha")) {
    switch(
      std_err,
      "san.se" = geese$valpha,
      "jack" = geese$valpha.ajs,
      "j1s" = geese$valpha.j1s,
      "fij" = geese$valpha.fij,
      NULL
    )
  } else {
    switch(
      std_err,
      "san.se" = geese$vgamma,
      "jack" = geese$vgamma.ajs,
      "j1s" = geese$vgamma.j1s,
      "fij" = geese$vgamma.fij,
      NULL
    )
  }
}


#' Render the GEE Working-Correlation Block
#'
#' Shared renderer for the GEE parameter block used by both `print.mfp2()` and
#' `print.summary.mfp2()`, so the two methods display the working correlation,
#' its estimate and standard error, the standard-error method, the scale
#' with its standard error, and the number of clusters identically. No-op for
#' non-GEE models (`gee` is `NULL`).
#'
#' @param gee A list from `mfp2_summary_gee_parameters()`, or `NULL`.
#' @param digits Integer display digits.
#' @param heading_printer Function drawing a dash-rule section heading.
#'
#' @return Invisibly `NULL`; called for its printing side effect.
#'
#' @keywords internal
#' @noRd
mfp2_print_gee_parameters <- function(gee, digits, heading_printer) {
  if (is.null(gee)) return(invisible(NULL))

  heading_printer("GEE Working Correlation")
  fmt_g <- function(v) format_print_decimal(v, digits)

  # Left-justify the labels to a common column so every value aligns.
  label_width <- 27L
  line <- function(label, value) {
    cat(format(label, width = label_width), value, "\n", sep = "")
  }

  line("Working correlation:", gee$corstr)
  line("SE method:", gee$std_err)

  if (!is.null(gee$correlation) && length(gee$correlation) > 0L) {
    labs <- names(gee$correlation)
    if (is.null(labs) || any(!nzchar(labs))) {
      labs <- if (length(gee$correlation) == 1L) {
        "alpha"
      } else {
        paste0("alpha", seq_along(gee$correlation))
      }
    }
    corr_se <- gee$correlation_se
    parts <- if (!is.null(corr_se) && length(corr_se) == length(gee$correlation)) {
      paste0(labs, " = ", fmt_g(gee$correlation),
             " (SE = ", fmt_g(corr_se), ")")
    } else {
      paste0(labs, " = ", fmt_g(gee$correlation))
    }
    line("Estimated correlation:", paste(parts, collapse = ", "))
  }

  if (!is.null(gee$scale)) {
    status <- if (isTRUE(gee$scale_fixed)) "fixed" else "estimated"
    scale_txt <- if (!is.null(gee$scale_se) && length(gee$scale_se) == 1L &&
                     is.finite(gee$scale_se)) {
      sprintf("%s (SE = %s, %s)", fmt_g(gee$scale), fmt_g(gee$scale_se), status)
    } else {
      sprintf("%s (%s)", fmt_g(gee$scale), status)
    }
    line("Scale (dispersion):", scale_txt)
  }
  if (!is.null(gee$reference_dispersion)) {
    line("Selection dispersion:", sprintf(
      "%s (%s)", fmt_g(gee$reference_dispersion),
      gee$reference_dispersion_source
    ))
  }
  if (!is.null(gee$qbic_penalty)) {
    line("QBIC penalty:", if (identical(gee$qbic_penalty, "clusters"))
      "log(clusters)" else "log(observations)")
  }

  line(
    "Number of clusters:",
    sprintf("%d (maximum size %d)", gee$n_clusters, gee$max_cluster_size)
  )
  cat("\n")
  invisible(NULL)
}


#' Human-Readable Model Label for an `mfp2` Family
#'
#' Converts the normalised internal family identifier into a printable model
#' label. Link-dependent models include their fitted link so that generic
#' identifiers such as `"ordinal"` are not presented as complete statistical
#' model specifications.
#'
#' @param family_string Canonical family name.
#' @param metadata Optional metadata list produced by
#'   `mfp2_summary_model_metadata()`. When supplied, `metadata$link` is
#'   appended to the label where the family admits multiple links.
#'
#' @return Character scalar with a human-readable model label.
#'
#' @keywords internal
#' @noRd
mfp2_summary_model_label <- function(family_string, metadata = NULL) {
  if (!is.character(family_string) || length(family_string) != 1L ||
      is.na(family_string) || !nzchar(family_string)) {
    return("Unknown Model")
  }
  link <- if (is.list(metadata)) metadata$link else NULL
  if (!is.character(link) || length(link) != 1L || is.na(link) || !nzchar(link)) {
    link <- NULL
  }

  if (mfp2_family_is_ordinal(family_string)) {
    if (is.null(link)) return("Ordinal Regression")
    return(switch(
      link,
      logistic = "Logistic Ordinal Regression (proportional odds)",
      probit = "Probit Ordinal Regression",
      loglog = "Log-log Ordinal Regression",
      cloglog = "Complementary Log-log Ordinal Regression",
      cauchit = "Cauchit Ordinal Regression",
      "Ordinal Regression"
    ))
  }

  if (identical(family_string, "multinomial")) {
    return("Multinomial Logistic Regression")
  }

  if (identical(family_string, "negbin")) {
    label <- "Negative-Binomial GLM"
    if (!is.null(link)) label <- paste0(label, " (", link, " link)")
    return(label)
  }

  glm_names <- c(
    gaussian = "Gaussian",
    binomial = "Binomial",
    poisson = "Poisson",
    Gamma = "Gamma",
    inverse.gaussian = "Inverse-Gaussian"
  )
  if (isTRUE(family_string %in% names(glm_names))) {
    label <- paste0(unname(glm_names[[family_string]]), " GLM")
    if (!is.null(link)) label <- paste0(label, " (", link, " link)")
    return(label)
  }

  if (identical(family_string, "gee")) {
    gee_names <- c(
      gaussian = "Gaussian",
      binomial = "Binomial",
      poisson = "Poisson",
      Gamma = "Gamma",
      inverse.gaussian = "Inverse-Gaussian"
    )
    rfs <- if (is.list(metadata)) metadata$gee_response_family else NULL
    fam_label <- if (!is.null(rfs) && rfs %in% names(gee_names)) {
      gee_names[[rfs]]
    } else {
      NULL
    }
    label <- if (!is.null(fam_label)) paste0(fam_label, " GEE") else "GEE"
    if (!is.null(link)) label <- paste0(label, " (", link, " link)")
    return(label)
  }

  switch(
    family_string,
    cox = "Cox Proportional Hazards",
    finegray = "Fine--Gray Subdistribution Hazards",
    survreg = "Parametric Survival Regression",
    family_string
  )
}


#' Print the Response-Frequency Block for Categorical Outcomes
#'
#' Prints the native-style response-frequency block used for categorical
#' multinomial and ordinal outcomes. Counts are deliberately unweighted so
#' the printed frequencies match the raw response data.
#'
#' @param response_frequencies A named numeric vector of class frequencies,
#'   typically produced by `mfp2_summary_response_frequencies()`, or `NULL`.
#'
#' @return Invisibly returns `NULL`. Called for its side effect of printing.
#'
#' @keywords internal
#' @noRd
mfp2_print_response_frequencies <- function(response_frequencies) {
  if (is.null(response_frequencies) || length(response_frequencies) == 0L) {
    return(invisible(NULL))
  }
  cat("\nFrequencies of Responses\n\n")
  print(response_frequencies)
  invisible(NULL)
}


#' Count Exact and Censored Observations for a `survreg` Model
#'
#' Counts exact events and censoring events for a fitted parametric survival
#' model according to the response's `Surv` type. Status value `0` has
#' different meanings for right- and left-censored responses, so a generic
#' `status == 1` event count is not sufficient.
#'
#' @param object An `"mfp2"` model object with a `Surv` response.
#'
#' @return A named list with `type`, `exact`, `right_censored`,
#'   `left_censored`, and `interval_censored`, or `NULL` if the response
#'   type is not supported by the reporting block.
#'
#' @keywords internal
#' @noRd
mfp2_summary_survreg_censoring <- function(object) {
  y <- object$y
  if (!inherits(y, "Surv")) return(NULL)

  type <- attr(y, "type", exact = TRUE)
  status <- y[, NCOL(y)]
  result <- list(
    type = type,
    exact = as.integer(sum(status == 1, na.rm = TRUE)),
    right_censored = 0L,
    left_censored = 0L,
    interval_censored = 0L
  )

  if (identical(type, "right")) {
    result$right_censored <- as.integer(sum(status == 0, na.rm = TRUE))
  } else if (identical(type, "left")) {
    result$left_censored <- as.integer(sum(status == 0, na.rm = TRUE))
  } else if (type %in% c("interval", "interval2")) {
    result$right_censored <- as.integer(sum(status == 0, na.rm = TRUE))
    result$left_censored <- as.integer(sum(status == 2, na.rm = TRUE))
    result$interval_censored <- as.integer(sum(status == 3, na.rm = TRUE))
  } else {
    return(NULL)
  }

  result
}


#' Print the Shared Model-Header Block
#'
#' Prints the common top-level metadata used by both the `mfp2` and
#' `summary.mfp2` print methods: model label, criterion, convergence status,
#' observation count with censoring/event breakdown, family-specific
#' parameters, and, for categorical outcomes, response frequencies.
#'
#' @param family_string Canonical family name.
#' @param criterion Character scalar identifying the selection criterion.
#' @param converged Logical indicating whether MFP selection converged, or
#'   `NA` when unknown.
#' @param n Integer number of fitted observations.
#' @param nevents Integer number of events for proportional-hazards models,
#'   or `NA_integer_`.
#' @param metadata Metadata list from `mfp2_summary_model_metadata()`.
#' @param digits Integer scalar controlling the number of digits used for
#'   numeric parameters.
#' @param response_frequencies Optional named numeric vector of response
#'   frequencies from `mfp2_summary_response_frequencies()`.
#'
#' @return Invisibly returns `NULL`. Called for its side effect of printing.
#'
#' @keywords internal
#' @noRd
mfp2_print_model_header <- function(family_string, criterion, converged, n,
                                    nevents = NA_integer_, metadata = NULL,
                                    digits = 3L,
                                    response_frequencies = NULL) {
  model_label <- mfp2_summary_model_label(family_string, metadata)
  fields <- c(paste0("Model: ", model_label))
  if (identical(family_string, "survreg") &&
      !is.null(metadata$distribution)) {
    fields <- c(fields, paste0("Distribution: ", metadata$distribution))
  }
  fields <- c(
    fields,
    paste0("Criterion: ", criterion),
    paste0(
      "Converged: ",
      if (isTRUE(converged)) "yes" else if (identical(converged, FALSE)) "no" else "unknown"
    )
  )
  cat(paste(fields, collapse = " | "), "\n", sep = "")

  censoring <- metadata$censoring
  if (identical(family_string, "survreg") && !is.null(censoring)) {
    if (identical(censoring$type, "right")) {
      cat(sprintf(
        "Observations: %s | Events: %s | Censored: %s\n",
        n, censoring$exact, censoring$right_censored
      ))
    } else if (identical(censoring$type, "left")) {
      cat(sprintf(
        "Observations: %s | Exact: %s | Left-censored: %s\n",
        n, censoring$exact, censoring$left_censored
      ))
    } else {
      cat(sprintf(
        paste0(
          "Observations: %s | Exact: %s | Right-censored: %s | ",
          "Left-censored: %s | Interval-censored: %s\n"
        ),
        n, censoring$exact, censoring$right_censored,
        censoring$left_censored, censoring$interval_censored
      ))
    }
  } else if (!is.na(nevents)) {
    cat(sprintf("Observations: %s | Events: %s\n", n, nevents))
  } else {
    cat(sprintf("Observations: %s\n", n))
  }

  mfp2_print_model_specific_parameters(
    family_string = family_string,
    metadata = metadata,
    digits = digits
  )
  mfp2_print_response_frequencies(response_frequencies)
  invisible(NULL)
}


#' Print Family-Specific Nuisance and Model Parameters
#'
#' Prints the nuisance and model parameters (scale, distribution parameters,
#' negative-binomial `theta`, GLM dispersion) that are needed to interpret a
#' fit but do not belong in the regression coefficient table. Parameter
#' formatting follows the same fixed-decimal convention used for the
#' coefficient and fit-statistic tables.
#'
#' @param family_string Canonical family name.
#' @param metadata Metadata list from `mfp2_summary_model_metadata()`.
#' @param digits Integer scalar controlling the number of digits used when
#'   formatting numeric parameters.
#'
#' @return Invisibly returns `NULL`. Called for its side effect of printing.
#'
#' @keywords internal
#' @noRd
mfp2_print_model_specific_parameters <- function(family_string, metadata,
                                                  digits = 3L) {
  # Model-specific numeric parameters follow the same fixed-decimal convention
  # as the coefficient and fit-statistic tables.
  fmt <- function(value) {
    format_print_decimal(value, digits)
  }

  if (identical(family_string, "survreg") && length(metadata$scale) > 0L) {
    status <- if (isTRUE(metadata$scale_fixed)) "fixed" else "estimated"
    if (length(metadata$scale) == 1L) {
      cat(sprintf("Scale: %s (%s)\n", fmt(metadata$scale), status))
    } else {
      cat(sprintf("Scale parameters (%s):\n", status))
      scale_table <- metadata$scale_strata
      names(scale_table) <- c("Stratum", "Scale")
      scale_table <- format_model_print_table(scale_table, digits)
      print.data.frame(
        scale_table,
        row.names = FALSE,
        right = FALSE
      )
    }

    parms <- metadata$distribution_parameters
    if (length(parms) > 0L) {
      parm_names <- names(parms)
      if (is.null(parm_names) || any(!nzchar(parm_names))) {
        parm_names <- paste0("parameter", seq_along(parms))
      }
      values <- paste0(parm_names, "=", vapply(parms, fmt, character(1L)))
      cat("Distribution parameters: ", paste(values, collapse = ", "), "\n", sep = "")
    }
  }

  if (identical(family_string, "negbin") && length(metadata$theta) == 1L) {
    cat(sprintf("Theta: %s (estimated)\n", fmt(metadata$theta)))
  }

  if (isTRUE(family_string %in% c(
        "gaussian", "Gamma", "inverse.gaussian"
      )) &&
      length(metadata$dispersion) == 1L) {
    status <- if (isTRUE(metadata$dispersion_fixed)) "fixed" else "estimated"
    cat(sprintf("Dispersion: %s (%s)\n", fmt(metadata$dispersion), status))
  }

  invisible(NULL)
}

#' Human-Readable Selection-Criterion Label
#'
#' Returns a printable label for the MFP selection criterion recorded on a
#' fitted model. Falls back to `"p-value"` when the criterion field is
#' absent, matching the `fp_terms` select/alpha convention.
#'
#' @param object An `"mfp2"` model object.
#'
#' @return Character scalar such as `"p-value"`, `"AIC"`, or `"BIC"`.
#'
#' @keywords internal
#' @noRd
mfp2_summary_criterion_label <- function(object) {
  crit <- object$criterion_mfp
  if (is.null(crit) || length(crit) != 1L || is.na(crit)) {
    # Fall back to fp_terms select/alpha convention.
    return("p-value")
  }
  key <- tolower(gsub("[^[:alnum:]]", "", as.character(crit)))
  switch(key,
         "pvalue" = "p-value",
         "aic"    = "AIC",
         "bic"    = "BIC",
         as.character(crit)
  )
}

#' Underlying-Class Summary With `mfp2()` Call Restored
#'
#' Computes the underlying model-specific summary (for example
#' [stats::summary.glm()] or [survival::summary.coxph()]) with the fitted
#' `call` field replaced by the original [mfp2()] call. Storing this on the
#' summary result lets users access the underlying-class summary without
#' having to refit the model.
#'
#' @param object An `"mfp2"` model object.
#'
#' @return The underlying-class summary object, or `NULL` when the
#'   dispatched summary throws an error.
#'
#' @keywords internal
#' @noRd
mfp2_summary_raw <- function(object) {
  result <- tryCatch(
    NextMethod_summary(object),
    error = function(e) NULL
  )
  if (!is.null(result) && !is.null(object$call_mfp)) {
    result$call <- object$call_mfp
  }
  result
}

#' Manual `NextMethod()` Dispatcher for `summary()`
#'
#' `NextMethod()` only works inside a method definition; this helper
#' dispatches manually to the next class after `"mfp2"` so that
#' `mfp2_summary_raw()` can build the underlying-class summary from an
#' ordinary function. For negative-binomial models fitted through `fastglm`,
#' the GLM dispersion is forced to `1` so that `summary()` uses normal/z
#' inference, matching [MASS::summary.negbin()], rather than estimating a
#' second dispersion and reporting t statistics.
#'
#' @param object An `"mfp2"` model object.
#' @param ... Additional arguments forwarded to the dispatched summary
#'   method.
#'
#' @return The result of the underlying-class `summary()` call, or `NULL`
#'   if no method exists for the remaining classes.
#'
#' @keywords internal
#' @noRd
NextMethod_summary <- function(object, ...) {
  cls <- class(object)
  next_classes <- cls[which(cls == "mfp2")[1L] + 1L]
  next_classes <- next_classes[!is.na(next_classes)]
  if (length(next_classes) == 0L) {
    return(NULL)
  }
  # Temporarily strip "mfp2" so summary() dispatches to the underlying class.
  obj2 <- object
  class(obj2) <- cls[cls != "mfp2"]

  # A negative-binomial GLM has fixed unit GLM dispersion after theta
  # has been estimated. Force dispersion = 1 so summary.fastglm() uses
  # normal/z inference, matching MASS::summary.negbin(), rather than
  # estimating a second dispersion and reporting t statistics.
  dots <- list(...)
  if (identical(object$family_string, "negbin") &&
      inherits(obj2, "fastglm")) {
    dots$dispersion <- 1
  }

  # A GEE fit carries the mfp2 GEE family wrapper in `$family`, which has no
  # dev.resids()/aic() members. summary.geeglm() delegates to summary.glm(),
  # which calls residuals.glm() and therefore needs those family functions.
  # Swap in the underlying response family (for example gaussian()) so the
  # native geepack summary -- and its Estimate/Std.err/Wald/Pr(>|W|)
  # coefficient table with robust standard errors -- can be produced.
  if (identical(object$family_string, "gee") && is.list(object$family) &&
      inherits(object$family$response_family, "family")) {
    obj2$family <- object$family$response_family
  }

  do.call(summary, c(list(object = obj2), dots))
}

# ---------------------------------------------------------------------------
# Term classification
# ---------------------------------------------------------------------------

#' Classify Selected Variables Into Linear and Nonlinear Terms
#'
#' Splits the selected variables of an `"mfp2"` model into linear and
#' nonlinear terms, records which are spike-at-zero binary-only outcomes,
#' and maps each variable to its transformed coefficient columns through the
#' exact fit-time metadata. Also returns the selection overview table used in
#' the printed header.
#'
#' @param object An `"mfp2"` model object.
#'
#' @return A named list with the classification vectors (`selected`,
#'   `is_linear`, `is_nonlinear`, `binary_only`, `acd`, `zero`, `catzero`,
#'   `spike`, `spike_dec`, `searched_fp`), per-variable power vectors preserving positions
#'   (`power_slots_by_var`) and with `NA` removed (`powers_by_var`), the
#'   design-column-to-variable mapping (`cols_by_var`), final degrees of
#'   freedom (`df_final`), and the printable `function_table` overview.
#'
#' @keywords internal
#' @noRd
mfp2_summary_classify_terms <- function(object) {
  fp_terms <- object$fp_terms
  variable_names <- rownames(fp_terms)

  selected <- if ("selected" %in% names(fp_terms)) {
    as.logical(fp_terms[["selected"]])
  } else {
    rep(TRUE, nrow(fp_terms))
  }
  selected[is.na(selected)] <- FALSE

  acd     <- mfp2_summary_flag(fp_terms, "acd")
  zero    <- mfp2_summary_flag(fp_terms, "zero")
  catzero <- mfp2_summary_flag(fp_terms, "catzero")
  spike   <- mfp2_summary_flag(fp_terms, "spike")
  searched_fp <- mfp2_summary_flag(fp_terms, "searched_fp")

  df_final <- if ("df_final" %in% names(fp_terms)) {
    as.numeric(fp_terms[["df_final"]])
  } else {
    rep(NA_real_, nrow(fp_terms))
  }

  power_cols <- mfp2_summary_power_columns(fp_terms)

  # Keep both representations of the selected powers:
  #
  # * power_slots_by_var preserves the original positions, including NA. This
  #   is required for ACD terms because slot 1 applies to x and slot 2 applies
  #   to A(x); c(NA, 1) is therefore different from c(1, NA).
  # * powers_by_var removes NA values for the existing selection summaries and
  #   ordinary FP classification.
  power_slots_by_var <- lapply(seq_len(nrow(fp_terms)), function(i) {
    suppressWarnings(as.numeric(unlist(
      fp_terms[i, power_cols, drop = FALSE],
      use.names = FALSE
    )))
  })
  names(power_slots_by_var) <- variable_names

  powers_by_var <- lapply(power_slots_by_var, function(p) p[!is.na(p)])

  # Map conceptual variables to fitted coefficient columns by composing the
  # exact source/design metadata retained by fit_mfp(). Do not infer ownership
  # from coefficient-name patterns: non-syntactic names, factors, and ACD
  # columns are all resolved through the stored maps.
  cols_by_var <- mfp2_summary_columns_by_variable(object, variable_names)

  # SAZ decision code -> is this a "binary only" outcome?
  spike_dec <- if ("spike_dec" %in% names(fp_terms)) {
    suppressWarnings(as.integer(fp_terms[["spike_dec"]]))
  } else {
    rep(NA_integer_, nrow(fp_terms))
  }

  # Classify each selected variable.
  is_linear <- logical(length(variable_names))
  is_nonlinear <- logical(length(variable_names))
  binary_only <- logical(length(variable_names))

  for (i in seq_along(variable_names)) {
    if (!selected[i]) next

    p <- powers_by_var[[i]]
    plain_linear <- (length(p) == 1L && isTRUE(p == 1)) &&
      !searched_fp[i] &&
      !acd[i] && !zero[i] && !catzero[i] && !spike[i]

    # Binary-only spike: no continuous component survived.
    saz_binary_only <- spike[i] &&
      mfp2_summary_saz_is_binary_only(spike_dec[i])

    if (plain_linear) {
      is_linear[i] <- TRUE
    } else if (saz_binary_only) {
      is_linear[i] <- TRUE
      binary_only[i] <- TRUE
    } else {
      is_nonlinear[i] <- TRUE
    }
  }

  function_table <- mfp2_summary_function_overview(
    variable_names, selected, df_final, powers_by_var,
    acd, zero, catzero, spike, spike_dec, searched_fp
  )

  list(
    variable_names = variable_names,
    selected       = selected,
    is_linear      = is_linear,
    is_nonlinear   = is_nonlinear,
    binary_only    = binary_only,
    acd            = acd,
    zero           = zero,
    catzero        = catzero,
    spike          = spike,
    spike_dec      = spike_dec,
    searched_fp    = searched_fp,
    df_final          = df_final,
    powers_by_var     = powers_by_var,
    power_slots_by_var = power_slots_by_var,
    cols_by_var       = cols_by_var,
    function_table = function_table
  )
}

#' Find FP Power Columns by Their Exact Generated Names
#'
#' Power fields are generated consecutively as `power1`, `power2`, and so on.
#' Enumerating those known names avoids regex searches and preserves numeric
#' order even when a data frame contains unrelated columns.
#'
#' @keywords internal
#' @noRd
mfp2_summary_power_columns <- function(fp_terms) {
  if (is.null(fp_terms) || NCOL(fp_terms) == 0L) return(character(0L))
  candidates <- paste0("power", seq_len(NCOL(fp_terms)))
  candidates[candidates %in% names(fp_terms)]
}

#' Map Conceptual Terms to Fitted Coefficient Columns
#'
#' Composes `term_to_columns`, `transformed_column_to_source`, and
#' `transformed_to_model_columns`. All joins are exact; generated coefficient
#' names are never parsed or searched by pattern.
#'
#' @keywords internal
#' @noRd
mfp2_summary_columns_by_variable <- function(object, variable_names) {
  out <- stats::setNames(vector("list", length(variable_names)), variable_names)
  out[] <- list(character(0L))

  term_to_columns <- object$term_to_columns
  transformed_to_source <- object$transformed_column_to_source
  transformed_to_model <- object$transformed_to_model_columns

  maps_are_named <- !is.null(term_to_columns) &&
    !is.null(names(term_to_columns)) &&
    !is.null(transformed_to_source) &&
    !is.null(names(transformed_to_source)) &&
    !is.null(transformed_to_model) &&
    !is.null(names(transformed_to_model))

  if (!maps_are_named) {
    # Compatibility for incomplete legacy objects and small hand-built test
    # fixtures: enumerate the package's exact generated column names. This is
    # bounded by the known design width and never performs an open-ended name
    # or regex search.
    design_columns <- colnames(object$x)
    if (is.null(design_columns) && !is.null(object$mfp2_design)) {
      design_columns <- setdiff(colnames(object$mfp2_design), "(Intercept)")
    }
    if (is.null(design_columns)) design_columns <- names(object$coefficients)
    if (is.null(design_columns)) return(out)

    indices <- seq_len(max(1L, length(design_columns)))
    for (variable in variable_names) {
      candidates <- c(
        variable,
        paste0(variable, ".", indices),
        paste0("A_", variable, ".", indices)
      )
      out[[variable]] <- design_columns[design_columns %in% candidates]
    }
    return(out)
  }

  transformed_columns <- intersect(
    names(transformed_to_model),
    names(transformed_to_source)
  )
  for (variable in variable_names) {
    source_columns <- as.character(term_to_columns[[variable]])
    if (length(source_columns) == 0L) next

    owned <- transformed_columns[
      unname(transformed_to_source[transformed_columns]) %in% source_columns
    ]
    model_columns <- unname(transformed_to_model[owned])
    model_columns <- model_columns[
      !is.na(model_columns) & nzchar(model_columns)
    ]
    out[[variable]] <- unique(model_columns)
  }
  out
}

#' Coerce an `fp_terms` Flag Column to a Logical Vector
#'
#' Reads one boolean-valued column of the `fp_terms` data frame and coerces
#' it to a proper logical vector, tolerating logical, character, and
#' numeric encodings. Missing values are treated as `FALSE` so downstream
#' classification never has to test for `NA`.
#'
#' @param fp_terms A data frame with one row per model term (see the
#'   `fp_terms` component of an `"mfp2"` object).
#' @param name Character scalar naming the column to coerce.
#'
#' @return Logical vector of length `nrow(fp_terms)`.
#'
#' @keywords internal
#' @noRd
mfp2_summary_flag <- function(fp_terms, name) {
  if (!name %in% names(fp_terms)) return(rep(FALSE, nrow(fp_terms)))
  v <- fp_terms[[name]]
  if (is.logical(v)) return(ifelse(is.na(v), FALSE, v))
  tolower(as.character(v)) %in% c("true", "t", "yes", "y", "1")
}

#' Is a Spike-at-Zero Decision Code the Binary-Only Outcome?
#'
#' Package spike-at-zero decisions use integer codes; `3L` means that the
#' continuous positive-component function was dropped and only the binary
#' zero indicator was retained. Matches `saz_decision_label()`.
#'
#' @param code Integer decision code, possibly `NA`.
#'
#' @return `TRUE` when `code == 3L`, `FALSE` otherwise.
#'
#' @keywords internal
#' @noRd
mfp2_summary_saz_is_binary_only <- function(code) {
  if (is.na(code)) return(FALSE)
  # In mfp2, spike_dec == 3 corresponds to "binary only".
  identical(as.integer(code), 3L)
}

#' Human-Readable Functional-Form Label for One Variable
#'
#' Builds the printable functional-form label for one MFP term, combining
#' the selected FP powers with ACD, `zero`, `catzero`, and spike-at-zero
#' modifiers. Returns `"out"` when the variable was not selected and
#' `"binary indicator only"` when a `catzero`- or `spike`-handled term
#' retains no continuous component.
#'
#' @param powers Numeric vector of selected FP powers, possibly empty.
#' @param acd Logical: was the term fitted with the ACD extension?
#' @param zero Logical: does the term use exact-zero handling?
#' @param catzero Logical: does the term use `catzero` handling?
#' @param spike Logical: was the term assessed with spike-at-zero?
#' @param spike_dec Integer spike-at-zero decision code (see
#'   `mfp2_summary_saz_is_binary_only()`).
#' @param selected Logical: was the term retained in the final model?
#' @param searched_fp Logical: was the form selected from a searched FP class?
#'
#' @return Character scalar with the functional-form label.
#'
#' @keywords internal
#' @noRd
mfp2_summary_form_label <- function(powers, acd, zero, catzero, spike,
                                    spike_dec, selected,
                                    searched_fp = FALSE) {
  if (!isTRUE(selected)) return("out")

  has_cont <- length(powers) > 0L

  if (!has_cont) {
    if (catzero || spike) return("binary indicator only")
    return("out")
  }

  base <- if (length(powers) == 1L && isTRUE(powers == 1) &&
              !isTRUE(searched_fp)) {
    "linear"
  } else {
    sprintf("FP(%s)", paste(powers, collapse = ", "))
  }
  if (acd) base <- paste0("ACD ", base)
  if (zero) base <- paste0(base, " (x > 0)")
  if (catzero) base <- paste0(base, " + binary")
  base
}

#' Build the Selection-Overview Table
#'
#' Assembles the printable variable-selection overview shown in the header
#' of `print.summary.mfp2()`. Each row reports the variable name, whether
#' it was retained, its final degrees of freedom, and its functional-form
#' label from `mfp2_summary_form_label()`.
#'
#' @param variable_names Character vector of term names.
#' @param selected Logical vector: which terms were retained.
#' @param df_final Numeric vector of final degrees of freedom per term.
#' @param powers_by_var Named list of selected FP power vectors.
#' @param acd Logical vector: ACD flags.
#' @param zero Logical vector: `zero` flags.
#' @param catzero Logical vector: `catzero` flags.
#' @param spike Logical vector: spike-at-zero flags.
#' @param spike_dec Integer vector of spike-at-zero decision codes.
#' @param searched_fp Logical vector: searched-FP identity flags.
#'
#' @return A data frame with columns `Variable`, `Selected`, `df`, and
#'   `Function`.
#'
#' @keywords internal
#' @noRd
mfp2_summary_function_overview <- function(variable_names, selected, df_final,
                                           powers_by_var, acd, zero, catzero,
                                           spike, spike_dec, searched_fp) {
  form <- vapply(seq_along(variable_names), function(i) {
    mfp2_summary_form_label(
      powers_by_var[[i]], acd[i], zero[i], catzero[i],
      spike[i], spike_dec[i], selected[i], searched_fp[i]
    )
  }, character(1L))

  df <- ifelse(is.na(df_final), ".", format(df_final, trim = TRUE))

  data.frame(
    Variable = variable_names,
    Selected = ifelse(selected, "yes", "no"),
    df       = df,
    Function = form,
    row.names = NULL,
    stringsAsFactors = FALSE
  )
}

# ---------------------------------------------------------------------------
# Coefficient -> display-name lookup
# ---------------------------------------------------------------------------

#' Build a Fitted-Coefficient to Display-Name Lookup
#'
#' Builds a named character vector mapping every fitted coefficient name to
#' the user-facing display name shown in the printed summary. The mapping is
#' composed from the two authoritative lookups populated by `fit_mfp()` at
#' fit time:
#'
#' - `term_to_columns`: user variable name to raw source columns.
#' - `transformed_to_model_columns`: raw source column to fitted coefficient
#'   name.
#'
#' Composing them yields an exact `coef_name -> display_name` map for every
#' selected variable, so the fitter's suffix convention is treated as an
#' implementation detail rather than something the summary depends on. The
#' caller falls back to a regex strip when either lookup is missing.
#'
#' @param object An `"mfp2"` model object.
#'
#' @return A named character vector: names are fitted coefficient names,
#'   values are display names. Empty when either authoritative lookup is
#'   missing.
#'
#' @keywords internal
#' @noRd
mfp2_summary_coef_to_display <- function(object) {
  t2c <- object$term_to_columns
  tmc <- object$transformed_to_model_columns

  if (is.null(t2c) || is.null(tmc)) {
    return(stats::setNames(character(0L), character(0L)))
  }

  out_names  <- character(0L)
  out_values <- character(0L)

  for (v in names(t2c)) {
    raw_cols <- as.character(t2c[[v]])
    if (length(raw_cols) == 0L) next

    # Rule: single raw column whose name equals v -> display is v.
    # Otherwise display is the raw column name (preserves factor levels
    # and any renaming the fitter did between user and raw column).
    display_for_raw <- if (length(raw_cols) == 1L && identical(raw_cols[[1L]], v)) {
      stats::setNames(v, raw_cols)
    } else {
      stats::setNames(raw_cols, raw_cols)
    }

    for (raw_col in raw_cols) {
      # transformed_to_model_columns is keyed by raw column; its value is the
      # final fitted coefficient name. Names and values can be identical for
      # scalar predictors, but for FP terms with multiple basis columns the
      # same raw column may map to multiple fitted names.
      hits <- which(names(tmc) == raw_col)
      if (length(hits) == 0L) next
      fitted_names <- as.character(tmc[hits])
      out_names  <- c(out_names, fitted_names)
      out_values <- c(out_values, rep(display_for_raw[[raw_col]], length(fitted_names)))
    }
  }

  stats::setNames(out_values, out_names)
}


# ---------------------------------------------------------------------------
# Linear terms table
# ---------------------------------------------------------------------------

#' Complete Ordinal Covariance Matrix in Coefficient Order
#'
#' Returns the full ordinal covariance matrix (thresholds and slopes) for a
#' fitted MFP ordinal model, ordered to match `names(object$coefficients)`.
#' New MFP ordinal fits always retain the native `orm` information matrix,
#' including for intercept-only models, so missing or misaligned covariance
#' is treated as an internal error rather than silently masked with
#' fallback `NA` values.
#'
#' @param object An `"mfp2"` ordinal model object.
#'
#' @return A numeric covariance matrix with row and column names equal to
#'   `names(object$coefficients)`.
#'
#' @keywords internal
#' @noRd
mfp2_ordinal_vcov_all <- function(object) {
  coefficient_names <- names(object$coefficients)
  if (is.null(coefficient_names) || anyNA(coefficient_names) ||
      any(!nzchar(coefficient_names))) {
    stop("Ordinal model coefficients must have non-empty names.", call. = FALSE)
  }

  covariance <- stats::vcov(object, intercepts = "all")
  if (!is.matrix(covariance) || is.null(rownames(covariance)) ||
      is.null(colnames(covariance)) ||
      !all(coefficient_names %in% rownames(covariance)) ||
      !all(coefficient_names %in% colnames(covariance))) {
    stop(
      "Ordinal covariance matrix is not aligned with model coefficients.",
      call. = FALSE
    )
  }

  covariance[coefficient_names, coefficient_names, drop = FALSE]
}


#' Ordinal Slope Covariance Matrix in Fitted-Coefficient Order
#'
#' Returns only the slope-slope block of the ordinal covariance matrix, in
#' fitted-coefficient order. [rms::vcov.orm()] has separate code paths for
#' threshold intercepts and regression slopes; requesting
#' `intercepts = "none"` avoids making slope inference depend on inversion
#' and retention of the full threshold covariance block.
#'
#' @param object An `"mfp2"` ordinal model object.
#'
#' @return A numeric covariance matrix with row and column names equal to
#'   the slope coefficient names. Returns an empty matrix when the model has
#'   no slope coefficients (intercept-only fit).
#'
#' @keywords internal
#' @noRd
mfp2_ordinal_vcov_slopes <- function(object) {
  coefficient_names <- names(object$coefficients)
  if (is.null(coefficient_names) || anyNA(coefficient_names) ||
      any(!nzchar(coefficient_names))) {
    stop("Ordinal model coefficients must have non-empty names.", call. = FALSE)
  }
  n_intercepts <- length(object$mfp2_ordinal_intercepts)
  slope_names <- if (length(coefficient_names) > n_intercepts) {
    coefficient_names[seq.int(n_intercepts + 1L, length(coefficient_names))]
  } else {
    character(0L)
  }
  if (length(slope_names) == 0L) {
    return(matrix(numeric(0L), nrow = 0L, ncol = 0L,
                  dimnames = list(character(0L), character(0L))))
  }

  covariance <- stats::vcov(object, intercepts = "none")
  if (!is.matrix(covariance) || is.null(rownames(covariance)) ||
      is.null(colnames(covariance)) ||
      !all(slope_names %in% rownames(covariance)) ||
      !all(slope_names %in% colnames(covariance))) {
    stop(
      "Ordinal slope covariance matrix is not aligned with model coefficients.",
      call. = FALSE
    )
  }

  covariance[slope_names, slope_names, drop = FALSE]
}


#' Ordinal Threshold-Intercept Summary Data Frame
#'
#' Builds a data frame of ordinal threshold intercepts with estimate,
#' standard error, z statistic, two-sided p value, and 95 % Wald confidence
#' interval, for display in [print.summary.mfp2()]. All thresholds are
#' returned, not just the middle one that [rms::vcov.orm()] defaults to.
#'
#' @param object An `"mfp2"` ordinal model object.
#'
#' @return A data frame with columns `threshold`, `estimate`, `se`, `z`,
#'   `p`, `ci_lower`, and `ci_upper`, or `NULL` when no thresholds are
#'   present.
#'
#' @keywords internal
#' @noRd
mfp2_summary_ordinal_intercepts <- function(object) {
  ord_int <- object$mfp2_ordinal_intercepts
  if (is.null(ord_int) || length(ord_int) == 0L) {
    return(NULL)
  }

  if (is.null(names(ord_int)) || anyNA(names(ord_int)) ||
      any(!nzchar(names(ord_int)))) {
    stop("Ordinal threshold intercepts must have non-empty names.", call. = FALSE)
  }

  # rms::orm's vcov() defaults to intercepts = "mid" (middle intercept only).
  # Request all intercepts explicitly so every threshold gets an SE.
  # The mfp2 object IS the orm object (class c("mfp2", "orm")), so vcov()
  # dispatches directly on it, not on a $fit slot.
  covariance_full <- mfp2_ordinal_vcov_all(object)
  variances <- diag(
    covariance_full[names(ord_int), names(ord_int), drop = FALSE]
  )
  se <- sqrt(variances)

  z    <- ord_int / se
  pval <- 2 * stats::pnorm(abs(z), lower.tail = FALSE)

  data.frame(
    threshold = names(ord_int),
    estimate  = unname(ord_int),
    se        = unname(se),
    z         = unname(z),
    p         = unname(pval),
    ci_lower  = unname(ord_int - 1.96 * se),
    ci_upper  = unname(ord_int + 1.96 * se),
    row.names = NULL,
    stringsAsFactors = FALSE
  )
}

#' Build the Linear-Terms Table for `print.summary.mfp2()`
#'
#' Assembles the data frame of linear-term rows (plus spike-at-zero
#' binary-only rows) shown in the printed summary. Coefficients, standard
#' errors, test statistics, and p values are pulled from the raw summary
#' where possible; when the raw summary does not carry a usable coefficient
#' table the values are recomputed from `stats::vcov(object)`. Display
#' names come from `mfp2_summary_coef_to_display()` rather than a regex
#' strip so that factor levels are preserved and future fitter renaming
#' does not break the display.
#'
#' @param object An `"mfp2"` model object.
#' @param classified Classification result from
#'   `mfp2_summary_classify_terms()`.
#' @param raw_summary Raw underlying-class summary from
#'   `mfp2_summary_raw()`.
#'
#' @return A data frame with one row per linear-term coefficient and columns
#'   `term`, `variable`, `coef`, `se`, `statistic`, `p`, plus `exp_coef`,
#'   `ci_lower`, and `ci_upper` (on the exponentiated scale for
#'   proportional-hazards and comparable models). Returns an empty data
#'   frame when there are no linear terms.
#'
#' @keywords internal
#' @noRd
mfp2_summary_linear_table <- function(object, classified, raw_summary) {
  coefs <- object$coefficients
  if (is.null(coefs) || length(coefs) == 0L) {
    return(data.frame())
  }

  # Column names of the fitted design.
  design_cols <- names(coefs)

  # Which fitted columns belong to linear-classified variables?
  linear_vars <- classified$variable_names[classified$is_linear]

  keep_cols <- unlist(
    classified$cols_by_var[linear_vars],
    use.names = FALSE
  )
  keep_cols <- intersect(design_cols, keep_cols)

  # Report the fitted intercept as the first row, consistently across every
  # family that estimates one. Cox and Fine--Gray have no intercept (partial
  # likelihood); ordinal threshold intercepts and multinomial per-logit
  # intercepts are reported through their own dedicated paths, so they are
  # excluded here to avoid double reporting.
  include_intercept <- "(Intercept)" %in% design_cols &&
    !mfp2_family_is_ordinal(object$family_string) &&
    !identical(object$family_string, "multinomial")
  if (include_intercept) {
    keep_cols <- c("(Intercept)", setdiff(keep_cols, "(Intercept)"))
  }

  if (length(keep_cols) == 0L) {
    return(data.frame())
  }

  # Extract coef / se / stat / p from the raw summary coefficient matrix.
  cmat <- mfp2_summary_coef_matrix(object, raw_summary)
  rows <- match(keep_cols, rownames(cmat))
  valid <- !is.na(rows)
  keep_cols <- keep_cols[valid]
  rows <- rows[valid]

  est <- cmat[rows, "estimate"]
  se  <- cmat[rows, "se"]
  stat <- cmat[rows, "statistic"]
  pval <- cmat[rows, "pvalue"]

  exponentiate <- mfp2_summary_exponentiates_coefficients(object)

  # -------------------------------------------------------------------------
  # Build a display name for each fitted coefficient.
  #
  # Rather than syntactically stripping ".N" suffixes off coefficient names,
  # we walk the two authoritative lookups populated by fit_mfp() at fit time:
  #
  #   term_to_columns             user variable name  -> raw source columns
  #   transformed_to_model_columns raw source column  -> fitted coef name
  #
  # Composing them gives an exact `fitted_coef_name -> display_name` map,
  # independent of any naming convention the internal fitter happens to use.
  # If future changes rename or renumber transformed columns, the summary
  # tracks those changes automatically because it consults the map, not the
  # regex.
  #
  # Display-name rule per user variable v:
  #
  #   - If v maps to a single raw column whose name equals v exactly, the
  #     display for every fitted coefficient descending from v is v itself.
  #     Covers plain scalar predictors, e.g. "hx" -> "hx.1" -> "hx".
  #
  #   - Otherwise (multi-level factor, or a raw column whose name differs
  #     from the user's variable name, e.g. "ekg_fb"), the display is the
  #     RAW source column name. This preserves the factor level in the
  #     printed table (e.g. "ekg_fb" rather than a bare "ekg_f" that would
  #     appear on multiple rows).
  #
  # The fallback for older or unusual fit objects that lack either lookup is
  # the previous regex strip; this preserves user-visible behaviour rather
  # than emitting cryptic internal names.
  coef_to_display <- mfp2_summary_coef_to_display(object)

  display_variable <- vapply(
    keep_cols,
    function(nm) {
      if (nm %in% names(coef_to_display)) {
        return(coef_to_display[[nm]])
      }
      # Fallback to the regex-based strip only when the lookup does not
      # cover this coefficient (e.g. a partial or corrupted fitted object).
      sub("\\.[0-9]+$", "", nm)
    },
    character(1L),
    USE.NAMES = FALSE
  )

  df <- data.frame(
    term = keep_cols,
    variable = display_variable,
    coef = est,
    se   = se,
    statistic = stat,
    p = pval,
    row.names = NULL,
    stringsAsFactors = FALSE
  )

  if (exponentiate) {
    df$exp_coef <- exp(est)
    # Coef-scale CIs (log scale for PH / survreg)
    df$ci_lower_coef <- est - 1.96 * se
    df$ci_upper_coef <- est + 1.96 * se
    # Exponentiated CIs
    df$ci_lower <- exp(est - 1.96 * se)
    df$ci_upper <- exp(est + 1.96 * se)
  } else {
    df$ci_lower <- est - 1.96 * se
    df$ci_upper <- est + 1.96 * se
  }

  attr(df, "statistic_label") <- attr(cmat, "statistic_label", exact = TRUE)

  df
}


#' Does the Summary Report Exponentiated Coefficients for This Family?
#'
#' Reports whether the printed summary should append an exponentiated
#' coefficient column (hazard ratio, subdistribution hazard ratio, time
#' ratio, or generic multiplicative effect). Exponentiation is retained for
#' Cox and Fine--Gray, and for `survreg` distributions that use log time.
#' GLM coefficients remain on their fitted link scale, matching the
#' parameter estimates returned by their fitting functions.
#'
#' @param object An `"mfp2"` model object.
#'
#' @return `TRUE` when the summary should display exponentiated
#'   coefficients, `FALSE` otherwise.
#'
#' @keywords internal
#' @noRd
mfp2_summary_exponentiates_coefficients <- function(object) {
  if (mfp2_family_is_ph(object$family_string)) return(TRUE)

  if (identical(object$family_string, "survreg")) {
    dist <- object$family$dist
    if (!is.character(dist) || length(dist) != 1L) return(FALSE)
    return(tolower(dist) %in% c(
      "weibull", "exponential", "rayleigh", "lognormal", "log normal",
      "loggaussian", "log gaussian", "loglogistic", "log logistic"
    ))
  }

  # GLM summaries report the coefficients fitted by glm()/fastglm() on their
  # native link scale. Do not add derived odds, rate, risk, or mean ratios.
  if (mfp2_family_is_glm(object$family_string)) return(FALSE)

  family <- object$family
  is.list(family) && is.character(family$link) && length(family$link) == 1L &&
    family$link %in% c("log", "logit")
}


#' Label for the Exponentiated-Coefficient Column
#'
#' Returns the printable column label used for the exponentiated-coefficient
#' column in the printed summary. Distinguishes hazard ratio (Cox),
#' subdistribution hazard ratio (Fine--Gray), time ratio (`survreg`), and
#' a generic multiplicative-effect label for other exponentiated families.
#'
#' @param object An `"mfp2"` model object.
#'
#' @return Character scalar with the column label, or `NULL` when the
#'   family does not exponentiate.
#'
#' @keywords internal
#' @noRd
mfp2_summary_exponent_label <- function(object) {
  if (!mfp2_summary_exponentiates_coefficients(object)) return(NULL)

  if (identical(object$family_string, "cox")) return("hazard ratio")
  if (identical(object$family_string, "finegray")) {
    return("subdistribution hazard ratio")
  }
  if (identical(object$family_string, "survreg")) return("time ratio")

  "multiplicative effect"
}

#' Match One Column of a Coefficient Table by Exact Name
#'
#' Returns the position of the first candidate column label found in
#' `column_names`. Candidate order defines precedence: this matters for
#' robust Cox summaries, which can contain both `"robust se"` and
#' `"se(coef)"`. A duplicated candidate is ambiguous and deliberately
#' returns `NA` so the caller can fall back to computing the column from
#' first principles rather than pick an unspecified one.
#'
#' @param column_names Character vector of column names from a raw
#'   coefficient table.
#' @param candidates Character vector of candidate exact-match labels, in
#'   precedence order.
#'
#' @return Integer scalar column position, or `NA_integer_` when no
#'   unambiguous match exists.
#'
#' @keywords internal
#' @noRd
mfp2_summary_match_coef_column <- function(column_names, candidates) {
  if (is.null(column_names)) {
    return(NA_integer_)
  }

  for (candidate in candidates) {
    positions <- which(column_names == candidate)

    if (length(positions) > 1L) {
      return(NA_integer_)
    }
    if (length(positions) == 1L) {
      return(as.integer(positions))
    }
  }

  NA_integer_
}


#' Standardised Coefficient Matrix for the Summary Table
#'
#' Returns a standardised numeric matrix with columns `estimate`, `se`,
#' `statistic`, and `pvalue` and rows named by coefficient. Sourced from
#' the raw summary's coefficient table where possible (survreg calls it
#' `table`), falling back to `stats::vcov(object)` and Wald z or t inference
#' when a raw table is missing or in an unfamiliar layout. Also carries a
#' `"statistic_label"` attribute (`"z"`, `"t"`, `"Wald"` for GEE, or
#' `"Statistic"`).
#'
#' @param object An `"mfp2"` model object.
#' @param raw_summary Raw underlying-class summary from
#'   `mfp2_summary_raw()`, possibly `NULL`.
#'
#' @return A numeric matrix with columns `estimate`, `se`, `statistic`, and
#'   `pvalue`, plus a `"statistic_label"` attribute.
#'
#' @keywords internal
#' @noRd
mfp2_summary_coef_matrix <- function(object, raw_summary) {
  # Try the raw summary's coefficient table first.
  cmat <- NULL
  if (!is.null(raw_summary) && !is.null(raw_summary$coefficients)) {
    cmat <- raw_summary$coefficients
  } else if (!is.null(raw_summary) && !is.null(raw_summary$table)) {
    # summary.survreg() calls this component `table` and appends one or more
    # scale rows after the regression coefficients.
    cmat <- raw_summary$table
  }

  # summary.geeglm() returns its coefficient table (with an "Estimate",
  # "Std.err", "Wald", "Pr(>|W|)" layout) as a data frame rather than a
  # numeric matrix. Coerce so the shared matrix column-matching path below
  # applies uniformly; the subsequent is.numeric() guard still protects
  # against a non-numeric table.
  if (is.data.frame(cmat)) {
    cmat <- tryCatch(as.matrix(cmat), error = function(e) NULL)
  }

  est <- object$coefficients
  nm <- names(est)

  if (is.matrix(cmat) && !is.null(rownames(cmat)) &&
      !is.null(nm) && all(nm %in% rownames(cmat))) {
    cmat <- cmat[nm, , drop = FALSE]
  }

  if (is.matrix(cmat) && is.numeric(cmat) && nrow(cmat) == length(est)) {
    # Use exact known labels rather than pattern/partial matching. If any label
    # is absent or ambiguous, `columns` contains NA and execution continues to
    # the covariance fallback below instead of indexing cmat with NA.
    cn <- colnames(cmat)
    columns <- c(
      estimate = mfp2_summary_match_coef_column(
        cn,
        c("Estimate", "Value", "coef")
      ),
      se = mfp2_summary_match_coef_column(
        cn,
        c("robust se", "Std. Error", "Std.err", "se(coef)")
      ),
      statistic = mfp2_summary_match_coef_column(
        cn,
        c("z value", "t value", "Wald", "z", "t")
      ),
      pvalue = mfp2_summary_match_coef_column(
        cn,
        c("Pr(>|z|)", "Pr(>|t|)", "Pr(>|W|)", "p", "p-value", "pvalue")
      )
    )

    if (!anyNA(columns) && !anyDuplicated(columns)) {
      out <- cbind(
        estimate  = cmat[, columns[["estimate"]]],
        se        = cmat[, columns[["se"]]],
        statistic = cmat[, columns[["statistic"]]],
        pvalue    = cmat[, columns[["pvalue"]]]
      )
      rownames(out) <- rownames(cmat)
      statistic_column <- cn[columns[["statistic"]]]
      attr(out, "statistic_label") <- if (identical(statistic_column, "Wald")) {
        # summary.geeglm() reports the Wald chi-square statistic (z^2) with a
        # Pr(>|W|) column; keep geepack's own convention for GEE models.
        "Wald"
      } else if (startsWith(statistic_column, "t")) {
        "t"
      } else if (startsWith(statistic_column, "z")) {
        "z"
      } else {
        "Statistic"
      }
      return(out)
    }
  }

  # Fallback for an absent, malformed, or unfamiliar raw coefficient table.
  # This is intentionally reached for unresolved headers rather than allowing
  # an NA column index to manufacture an all-NA result.
  is_ordinal <- mfp2_family_is_ordinal(object$family_string)
  V <- if (is_ordinal) {
    mfp2_ordinal_vcov_slopes(object)
  } else {
    tryCatch(stats::vcov(object), error = function(e) NULL)
  }
  se <- stats::setNames(rep(NA_real_, length(est)), nm)
  if (is_ordinal && is.matrix(V) && !is.null(nm) &&
      !is.null(rownames(V)) && !is.null(colnames(V))) {
    covariance_names <- intersect(
      nm,
      intersect(rownames(V), colnames(V))
    )
    if (length(covariance_names) > 0L) {
      variances <- diag(V[covariance_names, covariance_names, drop = FALSE])
      valid <- !is.na(variances) & is.finite(variances) & variances >= 0
      se[covariance_names[valid]] <- sqrt(variances[valid])
    }
  } else {
    if (is.matrix(V) && !is.null(nm) &&
        !is.null(rownames(V)) && !is.null(colnames(V)) &&
        all(nm %in% rownames(V)) && all(nm %in% colnames(V))) {
      V <- V[nm, nm, drop = FALSE]
    }
    if (is.matrix(V) && all(dim(V) == length(est))) {
      se <- sqrt(diag(V))
    }
  }
  stat <- est / se
  uses_t <- inherits(object, "glm") &&
    mfp2_glm_estimates_dispersion(object$family, object$family_string) &&
    is.numeric(object$df.residual) && length(object$df.residual) == 1L &&
    is.finite(object$df.residual)
  pval <- if (uses_t) {
    2 * stats::pt(abs(stat), df = object$df.residual, lower.tail = FALSE)
  } else {
    2 * stats::pnorm(abs(stat), lower.tail = FALSE)
  }

  out <- cbind(
    estimate  = est,
    se        = se,
    statistic = stat,
    pvalue    = pval
  )
  rownames(out) <- nm
  attr(out, "statistic_label") <- if (uses_t) {
    "t"
  } else {
    "z"
  }
  out
}

# ---------------------------------------------------------------------------
# Nonlinear terms table (LRT, one row per variable)
# ---------------------------------------------------------------------------

#' Cache the Metadata Needed to Refit Reduced Models
#'
#' Assembles the family-specific response, weights, offset, strata, control,
#' and full-model log-likelihood needed to refit reduced models when
#' computing likelihood-ratio tests for nonlinear terms. Doing this once at
#' the top of the summary avoids repeating expensive setup (in particular
#' `prepare_family_for_fit()` for `survreg` and unpacking the Fine--Gray
#' counting-process representation) for every nonlinear variable.
#'
#' @param object An `"mfp2"` model object.
#'
#' @return A named list with `valid` (flag), `full_logl`, `family`,
#'   `family_string`, `y`, `weights`, `offset`, `strata`, `method`,
#'   `fitter`, `control`, `nocenter`, and `is_finegray`. When `valid` is
#'   `FALSE`, downstream code should skip reduced-model refits and report
#'   `NA` test statistics.
#'
#' @keywords internal
#' @noRd
mfp2_summary_refit_context <- function(object) {
  family_string <- object$family_string
  is_cox <- identical(family_string, "cox")
  is_finegray <- identical(family_string, "finegray")
  is_survreg <- identical(family_string, "survreg")
  is_prepared_categorical <- family_string %in% c("ordinal", "multinomial")

  full_logl <- object$mfp_logl
  if (!is.numeric(full_logl) || length(full_logl) != 1L ||
      is.na(full_logl) || !is.finite(full_logl)) {
    full_logl <- tryCatch({
      if (is_cox || is_finegray || is_survreg) {
        unname(object$loglik[length(object$loglik)])
      } else {
        as.numeric(stats::logLik(object))
      }
    }, error = function(e) NA_real_)
  }

  fitter <- if (is.null(object$fitter)) "base" else object$fitter
  control <- object$mfp2_control
  if (is.null(control)) {
    control <- tryCatch(
      normalize_fit_control(
        control = NULL,
        family_string = family_string,
        fitter = fitter
      ),
      error = function(e) NULL
    )
  }

  nocenter_meta <- object$mfp2_nocenter
  nocenter <- if (is.list(nocenter_meta) &&
                  "value" %in% names(nocenter_meta)) {
    nocenter_meta[["value"]]
  } else if (is.numeric(nocenter_meta)) {
    nocenter_meta
  } else {
    c(-1, 0, 1)
  }

  context <- list(
    valid = is.numeric(full_logl) && length(full_logl) == 1L &&
      !is.na(full_logl) && is.finite(full_logl) && !is.null(control),
    full_logl = full_logl,
    family = if (is_prepared_categorical && !is.null(object$mfp2_family)) {
      object$mfp2_family
    } else {
      object$family
    },
    family_string = family_string,
    y = object$y,
    weights = if (is_cox || is_finegray || is_survreg) {
      object$weights
    } else {
      object$prior.weights
    },
    offset = object$offset,
    strata = if (is_cox || is_finegray) object$strata else NULL,
    method = if (is_cox || is_finegray) object$method else NULL,
    fitter = fitter,
    control = control,
    nocenter = nocenter,
    is_finegray = is_finegray
  )

  if (is_finegray) {
    # The retained final model already contains the expanded counting-process
    # response, design and weights. Reuse them without another finegray() call.
    row_map <- object$mfp2_finegray_row_map
    original_offset <- object$mfp2_original_offset
    has_baseline_strata <- !is.null(object$mfp2_internal_names$strata) &&
      length(object$mfp2_internal_names$strata) > 0L
    if (is.null(row_map) || is.null(original_offset) ||
        (has_baseline_strata && is.null(context$strata)) ||
        (!is.null(context$strata) &&
         (length(context$strata) != NROW(context$y) ||
          anyNA(context$strata)))) {
      context$valid <- FALSE
      return(context)
    }
    context$family <- "cox"
    context$family_string <- "cox"
    context$offset <- original_offset[row_map]
  } else if (is_survreg) {
    # Prepare the transformed response and resolved distribution once for all
    # nonlinear-term reduced refits in this summary call.
    prepared <- tryCatch(
      prepare_family_for_fit(
        family = object$family,
        family_string = "survreg",
        y = object$y_original,
        weights = object$weights,
        strata = object$mfp2_survreg_strata
      ),
      error = function(e) NULL
    )
    if (is.null(prepared)) {
      context$valid <- FALSE
      return(context)
    }
    context$family <- prepared$family
    context$y <- object$y_original
  }

  context
}


#' Build the Nonlinear-Terms Table for `print.summary.mfp2()`
#'
#' Assembles the data frame of one row per nonlinear term shown in the
#' printed summary, carrying the functional-form label, selection-adjusted
#' degrees of freedom, joint chi-square statistic, and p value. Likelihood
#' families use a drop-variable likelihood-ratio test; GEE uses a robust block
#' Wald test with the selected covariance estimator.
#'
#' @param object An `"mfp2"` model object.
#' @param classified Classification result from
#'   `mfp2_summary_classify_terms()`.
#'
#' @return A data frame with columns `variable`, `form`, `df`, `lr_chisq`,
#'   and `p`. Empty when the model has no nonlinear terms.
#'
#' @keywords internal
#' @noRd
mfp2_summary_nonlinear_table <- function(object, classified) {
  nl_vars <- classified$variable_names[classified$is_nonlinear]
  if (length(nl_vars) == 0L) {
    return(data.frame())
  }

  is_gee <- identical(object$family_string, "gee")
  # Likelihood families reuse one reduced-model context per table. GEE has no
  # full likelihood and instead tests the selected coefficient block directly.
  refit_context <- if (is_gee) NULL else mfp2_summary_refit_context(object)

  rows <- lapply(nl_vars, function(v) {
    idx <- match(v, classified$variable_names)
    form <- mfp2_summary_form_label(
      classified$powers_by_var[[idx]],
      classified$acd[idx], classified$zero[idx],
      classified$catzero[idx], classified$spike[idx],
      classified$spike_dec[idx], TRUE, classified$searched_fp[idx]
    )
    test <- if (is_gee) {
      mfp2_summary_gee_wald_term(object, classified, v)
    } else {
      mfp2_summary_lrt_drop_variable(
        object, classified, v, refit_context = refit_context
      )
    }

    data.frame(
      variable = v,
      form     = form,
      df       = test$df,
      lr_chisq = test$lr,
      p        = test$p,
      row.names = NULL,
      stringsAsFactors = FALSE
    )
  })

  out <- do.call(rbind, rows)
  attr(out, "test_label") <- if (is_gee) {
    "Wald-score chi-sq"
  } else {
    "LR chi-sq"
  }
  out
}

#' Robust Joint Wald Test for One Selected GEE Term
#'
#' The statistic uses the covariance estimator stored on the retained GEE
#' object. Its reference degrees of freedom retain the MFP power-search
#' adjustment recorded in `fp_terms` (FP1 = 2, FP2 = 4), as requested for the
#' nonlinear summary rather than using the raw coefficient-block rank.
#'
#' @keywords internal
#' @noRd
mfp2_summary_gee_wald_term <- function(object, classified, v) {
  variable_index <- match(v, classified$variable_names)
  df_adjusted <- classified$df_final[variable_index]
  if (is.numeric(df_adjusted) && length(df_adjusted) == 1L &&
      is.finite(df_adjusted) && df_adjusted == round(df_adjusted)) {
    df_adjusted <- as.integer(df_adjusted)
  }
  coefficient_names <- names(object$coefficients)
  term_columns <- classified$cols_by_var[[v]]
  positions <- match(term_columns, coefficient_names)
  positions <- positions[!is.na(positions)]

  na_result <- list(lr = NA_real_, df = df_adjusted, p = NA_real_)
  if (length(positions) == 0L) return(na_result)

  covariance <- tryCatch(stats::vcov(object), error = function(e) NULL)
  if (is.null(covariance)) return(na_result)

  test <- gee_robust_wald_test(
    object$coefficients,
    covariance,
    positions
  )
  reference_df <- if (is.numeric(df_adjusted) && length(df_adjusted) == 1L &&
                      is.finite(df_adjusted) && df_adjusted > 0) {
    unname(df_adjusted)
  } else {
    test$df
  }
  if (!is.finite(test$statistic) || !is.finite(reference_df) ||
      reference_df <= 0) {
    return(list(lr = NA_real_, df = reference_df, p = NA_real_))
  }

  list(
    lr = unname(test$statistic),
    df = reference_df,
    p = stats::pchisq(
      test$statistic,
      df = reference_df,
      lower.tail = FALSE
    )
  )
}

#' Drop-Variable Likelihood-Ratio Test for One Variable
#'
#' Performs the joint likelihood-ratio test for dropping every design column
#' belonging to one variable, holding all other functional forms fixed. The
#' selected model's stored log-likelihood is already on the same
#' family-specific scale, so only the reduced model is refitted. Degrees of
#' freedom use the selection-adjusted `df_final` from `fp_terms`.
#'
#' @param object An `"mfp2"` model object.
#' @param classified Classification result from
#'   `mfp2_summary_classify_terms()`.
#' @param v Character scalar naming the variable to drop.
#' @param refit_context Cached refit context from
#'   `mfp2_summary_refit_context()`. When `NULL`, it is recomputed.
#'
#' @return A named list `list(lr, df, p)` with the likelihood-ratio
#'   statistic, degrees of freedom, and p value. Any component may be `NA`
#'   when the reduced model cannot be fitted.
#'
#' @keywords internal
#' @noRd
mfp2_summary_lrt_drop_variable <- function(object, classified, v,
                                            refit_context = NULL) {
  cols_v <- intersect(colnames(object$x), classified$cols_by_var[[v]])
  idx <- match(v, classified$variable_names)
  df_v <- classified$df_final[idx]
  if (is.na(df_v)) df_v <- length(cols_v)

  na_result <- list(lr = NA_real_, df = df_v, p = NA_real_)
  x_full <- object$x
  if (is.null(x_full) || length(cols_v) == 0L) {
    return(na_result)
  }

  if (is.null(refit_context)) {
    refit_context <- mfp2_summary_refit_context(object)
  }
  if (!isTRUE(refit_context$valid)) return(na_result)

  keep <- setdiff(colnames(x_full), cols_v)
  x_reduced <- x_full[, keep, drop = FALSE]

  reduced_fit <- if (isTRUE(refit_context$is_finegray)) {
    # agreg.fit() is the counting-process matrix fitter. With resid = FALSE it
    # does not use row names, so avoid allocating them for summary refits too.
    tryCatch({
      fg_fit <- mfp2_with_cox_convergence_guard(
        survival::agreg.fit(
          x = x_reduced,
          y = refit_context$y,
          strata = if (is.null(refit_context$strata)) NULL else
            as.integer(refit_context$strata),
          offset = refit_context$offset,
          init = NULL,
          control = refit_context$control,
          weights = refit_context$weights,
          method = if (is.null(refit_context$method)) {
            "breslow"
          } else {
            refit_context$method
          },
          rownames = NULL,
          resid = FALSE,
          nocenter = refit_context$nocenter
        ),
        fast = TRUE
      )
      list(logl = unname(fg_fit$loglik[length(fg_fit$loglik)]))
    }, error = function(e) NULL)
  } else {
    x_has_intercept <- NCOL(x_reduced) > 0L &&
      !is.null(colnames(x_reduced)) &&
      identical(colnames(x_reduced)[1L], "(Intercept)")
    tryCatch(
      fit_model(
        x = x_reduced,
        y = refit_context$y,
        family = refit_context$family,
        family_string = refit_context$family_string,
        fitter = refit_context$fitter,
        weights = refit_context$weights,
        offset = refit_context$offset,
        method = refit_context$method,
        strata = refit_context$strata,
        control = refit_context$control,
        nocenter = refit_context$nocenter,
        x_has_intercept = x_has_intercept,
        keep_coefficients = FALSE,
        fast = TRUE
      ),
      error = function(e) NULL
    )
  }

  if (is.null(reduced_fit) || is.null(reduced_fit$logl) ||
      !is.finite(reduced_fit$logl)) {
    return(na_result)
  }

  lr <- 2 * (refit_context$full_logl - reduced_fit$logl)
  if (!is.finite(lr)) return(na_result)
  lr <- max(lr, 0)
  p <- stats::pchisq(lr, df = df_v, lower.tail = FALSE)

  list(lr = lr, df = df_v, p = p)
}

# ---------------------------------------------------------------------------
# Final design-column description
# ---------------------------------------------------------------------------

#' Compact Labels for a Fractional-Polynomial Basis
#'
#' Builds compact printable labels for the columns of an ordinary
#' fractional-polynomial basis, on the scale used by the final model. A
#' nonzero shift is shown explicitly (`(x + s)` or `(x - s)`), and repeated
#' powers use the standard FP `log(...)` multiplier convention.
#'
#' @param term Character scalar with the predictor name that appears in the
#'   label.
#' @param powers Finite numeric vector of FP powers.
#' @param shift Numeric scalar shift applied to `term`. Default `0`.
#'
#' @return Character vector of labels, one per element of `powers`.
#'
#' @keywords internal
#' @noRd
mfp2_fp_basis_labels <- function(term, powers, shift = 0) {
  if (!is.numeric(powers) || length(powers) == 0L || anyNA(powers) ||
      any(!is.finite(powers))) {
    stop("`powers` must be a finite non-empty numeric vector.", call. = FALSE)
  }

  if (length(shift) != 1L || is.na(shift) || !is.finite(shift)) shift <- 0

  base <- if (isTRUE(shift == 0)) {
    term
  } else if (shift > 0) {
    paste0("(", term, " + ", format(abs(shift), trim = TRUE, scientific = FALSE), ")")
  } else {
    paste0("(", term, " - ", format(abs(shift), trim = TRUE, scientific = FALSE), ")")
  }

  log_arg <- if (isTRUE(shift == 0)) {
    term
  } else if (shift > 0) {
    paste0(term, " + ", format(abs(shift), trim = TRUE, scientific = FALSE))
  } else {
    paste0(term, " - ", format(abs(shift), trim = TRUE, scientific = FALSE))
  }

  out <- character(length(powers))
  seen <- numeric(0L)

  for (i in seq_along(powers)) {
    p <- powers[[i]]
    repetition <- sum(seen == p) + 1L

    first <- if (isTRUE(p == 0)) {
      paste0("log(", log_arg, ")")
    } else if (isTRUE(p == 1)) {
      base
    } else {
      paste0(base, "^", format(p, trim = TRUE, scientific = FALSE))
    }

    if (repetition == 1L) {
      out[[i]] <- first
    } else if (isTRUE(p == 0)) {
      out[[i]] <- paste0("log(", log_arg, ")^", repetition)
    } else if (repetition == 2L) {
      out[[i]] <- paste0(first, " * log(", log_arg, ")")
    } else {
      out[[i]] <- paste0(first, " * log(", log_arg, ")^", repetition - 1L)
    }

    seen <- c(seen, p)
  }

  out
}

#' Describe One Factor Design Column
#'
#' Formats a single factor design column from its stored level-by-design
#' matrix. Treatment-coded indicator columns are shown as level indicators
#' (for example `I(x = "high")`). Other contrast columns retain their
#' model-matrix names, such as `x4.L` and `x4.Q`, because those names
#' identify the configured contrast basis directly and are the labels users
#' expect to see.
#'
#' @param object An `"mfp2"` model object with
#'   `object$formula_factor_info` populated.
#' @param term Character scalar naming the factor term.
#' @param source Character scalar naming the raw source column.
#'
#' @return A named list `list(variable, basis)`, or `NULL` when the column
#'   is not a recognised factor column.
#'
#' @keywords internal
#' @noRd
mfp2_factor_design_column_info <- function(object, term, source) {
  factor_info <- if (!is.null(object$formula_factor_info)) {
    object$formula_factor_info[[term]]
  } else {
    NULL
  }

  if (is.null(factor_info) || is.null(factor_info$design_by_level)) {
    return(NULL)
  }

  design <- as.matrix(factor_info$design_by_level)
  if (is.null(colnames(design)) || !source %in% colnames(design) ||
      is.null(rownames(design))) {
    return(NULL)
  }

  values <- suppressWarnings(as.numeric(design[, source]))
  if (length(values) != nrow(design) || anyNA(values) || any(!is.finite(values))) {
    return(NULL)
  }

  variable <- factor_info$variable
  if (is.null(variable) || length(variable) != 1L || is.na(variable) ||
      !nzchar(variable)) {
    variable <- term
  }

  tolerance <- 1e-10
  is_zero <- abs(values) <= tolerance
  is_one <- abs(values - 1) <= tolerance

  if (all(is_zero | is_one) && sum(is_one) == 1L) {
    level <- rownames(design)[which(is_one)]
    basis <- sprintf(
      "I(%s = %s)",
      variable,
      encodeString(level, quote = "\"")
    )
  } else {
    basis <- source
  }

  list(variable = variable, basis = basis)
}

#' Describe the Final Transformed Design Columns
#'
#' Builds a data frame describing every transformed design column of the
#' final fitted model, using the metadata recorded when the design matrix
#' was assembled. Source variables, component types (FP basis, ACD basis,
#' zero indicator, identity binary), zero handling, centering, and
#' model-column mappings are read directly from the fitted object; the
#' generated transformed column names are not interpreted.
#'
#' @param object An `"mfp2"` model object.
#'
#' @return A data frame with columns `variable`, `transformed_column`,
#'   `model_column`, `basis`, `center`, `centered`, `zero_handled`, and
#'   `component`, one row per transformed column. Returns an empty data
#'   frame for an intercept-only model.
#'
#' @keywords internal
#' @noRd
mfp2_design_column_info <- function(object) {
  transformed_to_model <- object$transformed_to_model_columns
  transformed_to_source <- object$transformed_column_to_source
  transformed_component <- object$transformed_column_component
  transformed_zero_handled <- object$transformed_column_zero_handled
  transformed_centered <- object$transformed_column_centered
  term_to_columns <- object$term_to_columns

  # An intercept-only final model has no transformed predictor columns. The
  # fitting backend records this as an empty named transformed-to-model map,
  # while the transformation-specific metadata are naturally NULL because no
  # design matrix was constructed. Accept that empty design only when the
  # fitted coefficient vector also contains no predictor coefficients; this
  # keeps a genuinely incomplete nonempty design from being silently hidden.
  coefficient_names <- if (is.matrix(object$coefficients)) {
    colnames(object$coefficients)
  } else {
    names(object$coefficients)
  }
  if (is.null(coefficient_names)) {
    coefficient_names <- character(0L)
  }
  predictor_coefficients <- setdiff(coefficient_names, "(Intercept)")

  if (!is.null(transformed_to_model) &&
      length(transformed_to_model) == 0L &&
      !is.null(names(transformed_to_model)) &&
      length(predictor_coefficients) == 0L) {
    return(data.frame(
      variable = character(0L),
      transformed_column = character(0L),
      model_column = character(0L),
      basis = character(0L),
      center = numeric(0L),
      centered = logical(0L),
      zero_handled = logical(0L),
      component = character(0L),
      stringsAsFactors = FALSE,
      row.names = NULL
    ))
  }

  metadata <- list(
    transformed_to_model = transformed_to_model,
    transformed_to_source = transformed_to_source,
    transformed_component = transformed_component,
    transformed_zero_handled = transformed_zero_handled,
    transformed_centered = transformed_centered
  )

  valid_named_vector <- function(value) {
    !is.null(value) && !is.null(names(value)) && !anyDuplicated(names(value))
  }

  if (!all(vapply(metadata, valid_named_vector, logical(1L))) ||
      is.null(term_to_columns) || is.null(names(term_to_columns))) {
    stop("Final design-column metadata is incomplete.", call. = FALSE)
  }

  transformed_columns <- names(transformed_to_model)
  aligned <- vapply(metadata[-1L], function(value) {
    setequal(transformed_columns, names(value))
  }, logical(1L))
  if (!all(aligned)) {
    stop("Final design-column metadata is not aligned.", call. = FALSE)
  }

  components_allowed <- c(
    "fp_basis", "acd_basis", "zero_indicator", "identity_binary"
  )
  unknown_components <- setdiff(
    unique(unname(transformed_component[transformed_columns])),
    components_allowed
  )
  if (length(unknown_components) > 0L) {
    stop(
      sprintf(
        "Unknown transformed-column component(s): %s.",
        paste(unknown_components, collapse = ", ")
      ),
      call. = FALSE
    )
  }

  # Each raw source column must belong to exactly one conceptual model term.
  source_to_term <- character(0L)
  for (term in names(term_to_columns)) {
    raw_columns <- as.character(term_to_columns[[term]])
    for (raw_column in raw_columns) {
      if (raw_column %in% names(source_to_term) &&
          !identical(unname(source_to_term[[raw_column]]), term)) {
        stop(
          sprintf("Source column '%s' belongs to more than one model term.", raw_column),
          call. = FALSE
        )
      }
      source_to_term[[raw_column]] <- term
    }
  }

  sources <- unname(transformed_to_source[transformed_columns])
  missing_sources <- is.na(sources) | !nzchar(sources)
  if (any(missing_sources)) {
    stop("Final design metadata contains an unmapped source column.", call. = FALSE)
  }

  missing_terms <- setdiff(unique(sources), names(source_to_term))
  if (length(missing_terms) > 0L) {
    stop(
      sprintf(
        "Final design metadata contains unmapped source column(s): %s.",
        paste(missing_terms, collapse = ", ")
      ),
      call. = FALSE
    )
  }

  centers <- object$centers
  if (!is.null(centers)) {
    if (is.null(names(centers)) || anyDuplicated(names(centers)) ||
        !setequal(transformed_columns, names(centers))) {
      stop("Final centering constants are not aligned with design columns.", call. = FALSE)
    }
  }

  fp_terms <- object$fp_terms
  power_columns <- mfp2_summary_power_columns(fp_terms)

  rows <- vector("list", length(transformed_columns))

  for (i in seq_along(transformed_columns)) {
    transformed_column <- transformed_columns[[i]]
    source <- transformed_to_source[[transformed_column]]
    component <- transformed_component[[transformed_column]]
    zero_handled <- isTRUE(transformed_zero_handled[[transformed_column]])
    centered <- isTRUE(transformed_centered[[transformed_column]])
    term <- source_to_term[[source]]
    raw_columns <- as.character(term_to_columns[[term]])

    mapped_block <- term_uses_column_mapping(term, raw_columns)
    display_variable <- if (mapped_block) term else source
    basis <- source

    factor_column <- if (mapped_block) {
      mfp2_factor_design_column_info(object, term, source)
    } else {
      NULL
    }

    if (!is.null(factor_column)) {
      display_variable <- factor_column$variable
      basis <- factor_column$basis
    } else if (mapped_block) {
      # Explicit grouped design blocks retain their supplied source-column
      # labels when there is no factor level-to-design mapping.
      basis <- source
    } else if (identical(component, "zero_indicator")) {
      basis <- sprintf("I(%s = 0)", term)
    } else if (identical(component, "identity_binary")) {
      basis <- term
    } else {
      if (is.null(fp_terms) || is.null(rownames(fp_terms)) ||
          !term %in% rownames(fp_terms)) {
        stop(sprintf("Missing FP metadata for term '%s'.", term), call. = FALSE)
      }

      slots <- suppressWarnings(as.numeric(unlist(
        fp_terms[term, power_columns, drop = FALSE],
        use.names = FALSE
      )))
      term_row <- fp_terms[term, , drop = FALSE]
      is_acd <- mfp2_summary_flag(term_row, "acd")[[1L]]

      shift <- 0
      transformations <- object$transformations
      if (!is.null(transformations) && term %in% rownames(transformations) &&
          "shift" %in% colnames(transformations)) {
        shift_value <- suppressWarnings(as.numeric(transformations[term, "shift"]))
        if (length(shift_value) == 1L && !is.na(shift_value) &&
            is.finite(shift_value)) {
          shift <- shift_value
        }
      }

      if (zero_handled) {
        shift <- 0
      }

      if (identical(component, "acd_basis")) {
        power <- if (length(slots) >= 2L) slots[[2L]] else NA_real_
        basis <- sprintf("A(%s)", term)
        if (!is.na(power)) {
          basis <- mfp2_fp_basis_labels(basis, power, shift = 0)[[1L]]
        }
      } else if (identical(component, "fp_basis")) {
        if (isTRUE(is_acd)) {
          powers <- if (length(slots) >= 1L) slots[[1L]] else NA_real_
          powers <- powers[!is.na(powers)]
        } else {
          powers <- slots[!is.na(slots)]
        }

        if (length(powers) == 0L) {
          stop(sprintf("Missing FP power metadata for term '%s'.", term), call. = FALSE)
        }

        fp_columns_for_source <- transformed_columns[
          unname(transformed_to_source[transformed_columns]) == source &
            unname(transformed_component[transformed_columns]) == "fp_basis"
        ]
        k <- match(transformed_column, fp_columns_for_source)
        labels <- mfp2_fp_basis_labels(term, powers, shift = shift)

        if (is.na(k) || k > length(labels)) {
          stop(
            sprintf("FP basis metadata is not aligned for term '%s'.", term),
            call. = FALSE
          )
        }

        basis <- labels[[k]]
        if (zero_handled) {
          basis <- sprintf("I(%s > 0) * %s", term, basis)
        }
      }
    }

    rows[[i]] <- data.frame(
      variable = display_variable,
      transformed_column = transformed_column,
      model_column = unname(transformed_to_model[[transformed_column]]),
      basis = basis,
      center = if (is.null(centers)) NA_real_ else unname(centers[[transformed_column]]),
      centered = centered,
      zero_handled = zero_handled,
      component = component,
      stringsAsFactors = FALSE,
      row.names = NULL
    )
  }

  do.call(rbind, rows)
}

# ---------------------------------------------------------------------------
# Basis coefficients table (optional)
# ---------------------------------------------------------------------------

#' Build the Optional Basis-Coefficient Table
#'
#' Builds the per-basis coefficient table shown for nonlinear terms when
#' basis details are requested in the printed summary. One row per fitted
#' basis coefficient is returned; the `variable` column is filled only for
#' the first row of each variable so the printed table stays compact.
#'
#' @param object An `"mfp2"` model object.
#' @param classified Classification result from
#'   `mfp2_summary_classify_terms()`.
#'
#' @return A data frame with columns `variable`, `term`, `center`, and `coef`, or
#'   `NULL` when no nonlinear terms are present or no coefficients match.
#'
#' @keywords internal
#' @noRd
mfp2_summary_basis_table <- function(object, classified) {
  nl_vars <- classified$variable_names[classified$is_nonlinear]
  if (length(nl_vars) == 0L) return(NULL)

  coefs <- object$coefficients
  design_info <- mfp2_design_column_info(object)
  rows <- list()
  for (v in nl_vars) {
    cols_v <- intersect(names(coefs), classified$cols_by_var[[v]])
    for (k in seq_along(cols_v)) {
      row <- match(cols_v[[k]], design_info$model_column)
      if (is.na(row)) {
        stop(sprintf("No final design metadata found for coefficient '%s'.", cols_v[[k]]),
             call. = FALSE)
      }
      center <- if (isTRUE(design_info$centered[[row]])) {
        design_info$center[[row]]
      } else {
        0
      }
      if (!is.finite(center)) {
        stop(sprintf("No finite centering constant found for coefficient '%s'.", cols_v[[k]]),
             call. = FALSE)
      }
      rows[[length(rows) + 1L]] <- data.frame(
        variable = if (k == 1L) v else "",
        term     = design_info$basis[[row]],
        center   = center,
        coef     = unname(coefs[cols_v[k]]),
        row.names = NULL,
        stringsAsFactors = FALSE
      )
    }
  }
  if (length(rows) == 0L) return(NULL)
  do.call(rbind, rows)
}

#' Readable Transformation Label for One Fitted Column
#'
#' Constructs the printable transformation label used in the basis-details
#' table for a single fitted column. Ordinary final FP coefficients multiply
#' a shifted-but-unscaled basis, because `fit_mfp()` backscales the working
#' predictors before the final transformation. ACD component columns are
#' functions of `A(x)`; new fits use shifted, unscaled input for `A(x)`, and
#' a stored non-unit ACD scale is honoured only so that formula output
#' remains exact for legacy serialised model objects.
#'
#' @param object An `"mfp2"` model object.
#' @param classified Classification result from
#'   `mfp2_summary_classify_terms()`.
#' @param v Character scalar naming the variable.
#' @param col Character scalar naming the fitted design column.
#'
#' @return Character scalar with the transformation label.
#'
#' @keywords internal
#' @noRd
mfp2_summary_term_label <- function(object, classified, v, col) {
  idx <- match(v, classified$variable_names)
  cols_v <- classified$cols_by_var[[v]]
  k <- match(col, cols_v)
  acd <- classified$acd[idx]

  base_col <- sub("\\.[0-9]+$", "", col)
  is_acd_component <- isTRUE(acd) && isTRUE(base_col == paste0("A_", v))

  if (isTRUE(acd)) {
    slots <- classified$power_slots_by_var[[idx]]
    if (length(slots) < 2L) slots <- c(slots, rep(NA_real_, 2L - length(slots)))

    if (is_acd_component) {
      power <- slots[2L]
      base <- sprintf("A(%s)", v)
    } else {
      power <- slots[1L]
      ss <- mfp2_summary_shift_scale(object, v)
      base <- mfp2_summary_fp_inner_expr(v, ss$shift)
    }

    if (is.na(power)) return(base)
    return(mfp2_summary_power_expr(base, power))
  }

  powers <- classified$powers_by_var[[idx]]
  if (length(powers) == 0L) {
    return(sprintf("I(%s > 0)", v))
  }

  ss <- mfp2_summary_shift_scale(object, v)
  base <- mfp2_summary_fp_inner_expr(v, ss$shift)
  power <- if (k <= length(powers)) powers[k] else powers[length(powers)]

  # Repeated powers have the special FP2 second basis x^p * log(x). This rule
  # applies only to ordinary FP2 terms; equal ACD powers act on different inputs
  # (x and A(x)) and must not trigger the repeated-power construction.
  repeated <- length(powers) == 2L && isTRUE(powers[1L] == powers[2L])
  mfp2_summary_power_expr(base, power, repeated = repeated && k == 2L)
}

#' Apply an FP Power to a Base Expression
#'
#' Wraps a readable base expression with one FP power. Power `0` becomes
#' `log(base)`; power `1` returns the base unchanged; other powers become
#' `base^power`. When `repeated = TRUE`, the standard FP2 second-basis
#' multiplier `* log(base)` is appended.
#'
#' @param base Character scalar with the base expression.
#' @param power Numeric FP power.
#' @param repeated Logical. If `TRUE`, append the repeated-power log
#'   multiplier.
#'
#' @return Character scalar with the powered expression.
#'
#' @keywords internal
#' @noRd
mfp2_summary_power_expr <- function(base, power, repeated = FALSE) {
  wrapped <- sprintf("(%s)", base)

  out <- if (isTRUE(power == 0)) {
    sprintf("log%s", wrapped)
  } else if (isTRUE(power == 1)) {
    wrapped
  } else {
    sprintf("%s^(%s)", wrapped, format(power, trim = TRUE))
  }

  if (isTRUE(repeated)) {
    out <- sprintf("%s*log(%s)", out, base)
  }
  out
}

#' Inner Expression for the Final Ordinary FP Basis
#'
#' Builds the parenthesised inner expression used by `mfp2_summary_power_expr()`
#' for an ordinary FP term. The final fit uses shifted but unscaled
#' predictors, so preprocessing scale is intentionally absent here.
#'
#' @param v Character scalar naming the variable.
#' @param shift Numeric shift, possibly `NA`.
#'
#' @return Character scalar such as `"(x)"` or `"(x + 0.5)"`.
#'
#' @keywords internal
#' @noRd
mfp2_summary_fp_inner_expr <- function(v, shift) {
  if (!is.na(shift) && shift != 0) {
    sprintf("(%s + %s)", v, format(shift, trim = TRUE))
  } else {
    sprintf("(%s)", v)
  }
}

#' Inner Expression for a Stored ACD Approximation
#'
#' Builds the inner expression used only by the stored ACD approximation
#' formula. New model objects store `scale = 1` because ACD variables are
#' not scaled, but a non-unit stored scale is honoured so summaries of
#' legacy serialised model objects remain exact.
#'
#' @param v Character scalar naming the variable.
#' @param shift Numeric shift, possibly `NA`.
#' @param scale Numeric scale, possibly `NA`.
#'
#' @return Character scalar with the inner expression.
#'
#' @keywords internal
#' @noRd
mfp2_summary_acd_inner_expr <- function(v, shift, scale) {
  base <- if (!is.na(shift) && shift != 0) {
    sprintf("(%s + %s)", v, format(shift, trim = TRUE))
  } else {
    sprintf("(%s)", v)
  }

  if (!is.na(scale) && scale != 1) {
    base <- sprintf("%s/%s", base, format(scale, trim = TRUE))
  }
  base
}

#' Look Up Shift and Scale for One Variable
#'
#' Reads the stored preprocessing shift and scale values for one variable
#' from the fitted model's `transformations` table.
#'
#' @param object An `"mfp2"` model object.
#' @param v Character scalar naming the variable.
#'
#' @return A named list `list(shift, scale)` of numeric scalars; either
#'   entry is `NA_real_` when the variable is absent from the table or the
#'   column is missing.
#'
#' @keywords internal
#' @noRd
mfp2_summary_shift_scale <- function(object, v) {
  tr <- object$transformations
  shift <- NA_real_
  scale <- NA_real_
  if (!is.null(tr) && v %in% rownames(tr)) {
    if ("shift" %in% colnames(tr)) shift <- suppressWarnings(as.numeric(tr[v, "shift"]))
    if ("scale" %in% colnames(tr)) scale <- suppressWarnings(as.numeric(tr[v, "scale"]))
  }
  list(shift = shift, scale = scale)
}

# ---------------------------------------------------------------------------
# Fitted-function formula strings (optional)
# ---------------------------------------------------------------------------

#' Fitted-Function Formula Strings for Nonlinear Terms
#'
#' Builds the printable fitted-function formula strings shown for nonlinear
#' terms in the printed summary. Each formula is of the form
#' `f(x) = b1 * label1 + b2 * label2 + ...`, using `digits` decimal places
#' for coefficients and centering constants.
#'
#' @param object An `"mfp2"` model object.
#' @param classified Classification result from
#'   `mfp2_summary_classify_terms()`.
#'
#' @return Character vector of formula strings, one per nonlinear term, or
#'   `NULL` when the model contains no nonlinear terms.
#'
#' @keywords internal
#' @noRd
mfp2_summary_formula_strings <- function(object, classified, digits = 3L) {
  nl_vars <- classified$variable_names[classified$is_nonlinear]
  if (length(nl_vars) == 0L) return(NULL)

  coefs <- object$coefficients
  design_info <- mfp2_design_column_info(object)
  out <- character(length(nl_vars))
  for (i in seq_along(nl_vars)) {
    v <- nl_vars[i]
    cols_v <- intersect(names(coefs), classified$cols_by_var[[v]])
    terms <- vapply(cols_v, function(col) {
      b <- unname(coefs[col])
      row <- match(col, design_info$model_column)
      if (is.na(row)) {
        stop(sprintf("No final design metadata found for coefficient '%s'.", col),
             call. = FALSE)
      }
      lbl <- design_info$basis[[row]]
      if (isTRUE(design_info$centered[[row]])) {
        center <- design_info$center[[row]]
        if (!is.finite(center)) {
          stop(sprintf("No finite centering constant found for coefficient '%s'.", col),
               call. = FALSE)
        }
        # Use the stored centre, rounding only its displayed value.
        # Preserve uncentred labels.
        if (center != 0) {
          operator <- if (center < 0) "+" else "-"
          lbl <- sprintf("(%s %s %s)", lbl, operator,
                         formatC(abs(center), format = "f", digits = digits))
        }
      }
      sprintf("%s * %s", formatC(b, format = "f", digits = digits), lbl)
    }, character(1L))
    body <- paste(terms, collapse = " + ")
    # Tidy "+ -" into "- ".
    body <- gsub("\\+ -", "- ", body)
    out[i] <- sprintf("f(%s) = %s", v, body)
  }
  out
}

#' Build ACD Definition Strings for the Printed Summary
#'
#' Assembles the printable definitions `A(x) = pnorm(beta0 + beta1 * ...)`
#' for every active ACD component. Both the ordinary FP term and new ACD
#' fits use shifted, unscaled predictor values; a non-unit stored ACD scale
#' is honoured only for compatibility with legacy fitted objects.
#'
#' @param object An `"mfp2"` model object.
#' @param classified Classification result from
#'   `mfp2_summary_classify_terms()`.
#'
#' @return Character vector of ACD definition strings, or `NULL` when no
#'   ACD components are active.
#'
#' @keywords internal
#' @noRd
mfp2_summary_acd_definitions <- function(object, classified) {
  acd_vars <- classified$variable_names[
    classified$is_nonlinear & classified$acd
  ]
  if (length(acd_vars) == 0L) return(NULL)

  definitions <- vapply(acd_vars, function(v) {
    cols_v <- classified$cols_by_var[[v]]
    base_cols <- sub("\\.[0-9]+$", "", cols_v)
    if (!any(base_cols == paste0("A_", v))) return(NA_character_)
    mfp2_summary_acd_definition(object, v)
  }, character(1L))

  definitions <- definitions[!is.na(definitions) & nzchar(definitions)]
  if (length(definitions) == 0L) NULL else unname(definitions)
}

#' ACD Definition String for One Variable
#'
#' Builds the printable ACD definition `A(v) = pnorm(beta0 + beta1 * ...)`
#' for one variable, from the stored ACD parameter list. Returns
#' `NA_character_` when any required piece is missing.
#'
#' @param object An `"mfp2"` model object.
#' @param v Character scalar naming the variable.
#'
#' @return Character scalar with the definition, or `NA_character_`.
#'
#' @keywords internal
#' @noRd
mfp2_summary_acd_definition <- function(object, v) {
  par <- object$acd_parameter[[v]]
  if (is.null(par)) return(NA_character_)

  required <- c("beta0", "beta1", "power", "shift", "scale")
  if (!all(required %in% names(par))) return(NA_character_)

  ss <- mfp2_summary_shift_scale(object, v)
  preprocessing_shift <- if (is.na(ss$shift)) 0 else ss$shift
  acd_shift <- suppressWarnings(as.numeric(par$shift)[1L])
  acd_scale <- suppressWarnings(as.numeric(par$scale)[1L])
  acd_power <- suppressWarnings(as.numeric(par$power)[1L])
  beta0 <- suppressWarnings(as.numeric(par$beta0)[1L])
  beta1 <- suppressWarnings(as.numeric(par$beta1)[1L])

  if (anyNA(c(acd_shift, acd_scale, acd_power, beta0, beta1))) {
    return(NA_character_)
  }

  total_shift <- preprocessing_shift + acd_shift
  inner <- mfp2_summary_acd_inner_expr(v, total_shift, acd_scale)
  acd_basis <- mfp2_summary_power_expr(inner, acd_power)

  sprintf(
    "A(%s) = pnorm(%s + %s * %s)",
    v,
    format(signif(beta0, 4), trim = TRUE),
    format(signif(beta1, 4), trim = TRUE),
    acd_basis
  )
}

# ---------------------------------------------------------------------------
# Model-fit statistics
# ---------------------------------------------------------------------------

#' Model-Fit Statistics Wrapper
#'
#' Returns the values used by the shared Model Fit block renderer.
#' Everything else previously in this list (LR test statistic, R-squared,
#' etc.) has been removed: the block is now purely descriptive, and
#' inferential statements are made only by the per-variable nonlinear LRTs.
#'
#' @param object An `"mfp2"` model object.
#'
#' @return A named list with a single element `model_fit` from
#'   `mfp2_summary_model_fit_values()`.
#'
#' @keywords internal
#' @noRd
mfp2_summary_fit_stats <- function(object) {
  list(
    model_fit = mfp2_summary_model_fit_values(object)
  )
}

#' Coerce a Scalar Value to a Finite Numeric
#'
#' Convenience helper that coerces a scalar value to `numeric`, returning
#' `NA_real_` for `NULL`, length mismatches, or coercion failures.
#'
#' @param x Value to coerce.
#'
#' @return Numeric scalar, possibly `NA_real_`.
#'
#' @keywords internal
#' @noRd
mfp2_summary_num <- function(x) {
  if (is.null(x) || length(x) != 1L) return(NA_real_)
  suppressWarnings(as.numeric(x))
}

#' FP-Adjusted Model Degrees of Freedom
#'
#' Returns the total FP-adjusted model degrees of freedom: the sum of
#' `df_final` over the selected variables. Each variable is charged its
#' selection-adjusted df (1 linear, 2 for FP1, 4 for FP2, etc.) rather than
#' its raw coefficient count, so the overall LR test is consistent with the
#' per-variable nonlinear LRTs and with the MFP df accounting used
#' elsewhere. The intercept is not counted, because it is already present
#' in the null model.
#'
#' @param object An `"mfp2"` model object.
#'
#' @return Integer scalar with the FP-adjusted model degrees of freedom.
#'   When `fp_terms$df_final` is unavailable, a fallback count based on
#'   `coef()` (excluding an intercept, when present) is returned.
#'
#' @keywords internal
#' @noRd
mfp2_summary_model_df <- function(object) {
  fp_terms <- object$fp_terms
  if (is.null(fp_terms) || !"df_final" %in% names(fp_terms)) {
    # Fallback: coefficient count excluding an intercept, if present.
    nm <- names(object$coefficients)
    n <- length(nm)
    if (!is.null(nm) && "(Intercept)" %in% nm) n <- n - 1L
    return(as.integer(n))
  }
  selected <- if ("selected" %in% names(fp_terms)) {
    as.logical(fp_terms[["selected"]])
  } else {
    rep(TRUE, nrow(fp_terms))
  }
  selected[is.na(selected)] <- FALSE
  df_final <- suppressWarnings(as.numeric(fp_terms[["df_final"]]))
  total <- sum(df_final[selected], na.rm = TRUE)
  as.integer(total)
}

#' Assemble the Model Fit Block Values
#'
#' Assembles the numeric values for the printed Model Fit block from a
#' fitted `"mfp2"` object. Used by both [print.mfp2()] and
#' [print.summary.mfp2()] so the two methods display identical
#' family-specific fit statistics. GEE AIC/BIC fits instead return selection
#' scores; GEE p-value fits return `NULL`.
#'
#' For non-GEE families, the `df` column counts regression coefficients,
#' excluding the intercept. For GEE selection scores it includes the intercept
#' and the FP-power search allowance, matching the score's penalty.
#' `linear_df` as stored comes from
#' `fit_model()$df`, which counts the intercept for models that have one
#' and includes any estimated GLM dispersion, negative-binomial `theta`, or
#' `survreg` scale parameter; those adjustments are stripped here so the
#' number matches the promise made in the printed note.
#'
#' @param object An `"mfp2"` model object.
#'
#' @return `NULL` for GEE p-value fits; otherwise a data frame with columns
#'   `label`, `fit_statistic`, and `df` and
#'   rows `"Full linear model"` and `"MFP model"`. Carries a
#'   `"statistic_label"` attribute (`"Deviance"` for GLMs, `"-2 log L"` for
#'   survival and multinomial models), and, where applicable, `"n_logits"`
#'   or `"n_ordinal_intercepts"` attributes used to render the df note.
#'
#' @keywords internal
#' @noRd
mfp2_summary_model_fit_values <- function(object) {
  family_string <- object$family_string
  if (identical(family_string, "gee")) {
    criterion <- mfp2_summary_criterion_label(object)
    if (identical(criterion, "p-value")) return(NULL)
    label <- if (identical(criterion, "AIC")) "Adjusted QICu" else "BIC-like score"
    values <- data.frame(
      label = c("Full linear model", "MFP model"),
      fit_statistic = c(
        mfp2_summary_num(object$linear_selection_score),
        mfp2_summary_num(object$mfp_selection_score)
      ),
      df = c(
        mfp2_summary_num(object$linear_df),
        mfp2_summary_num(object$mfp_selection_df)
      ),
      stringsAsFactors = FALSE
    )
    attr(values, "statistic_label") <- label
    attr(values, "heading") <- "Selection Scores"
    return(values)
  }
  fit_statistic <- c(
    mfp2_summary_num(object$linear_deviance),
    mfp2_summary_num(object$mfp_deviance)
  )

  # The df column follows a single convention: number of regression
  # coefficients, EXCLUDING the intercept. `linear_df` as stored comes from
  # fit_model()$df, which counts the intercept for models that have one and
  # includes any estimated GLM dispersion, negative-binomial theta, or `survreg`
  # scale parameter. These adjustments are stripped here so the number the
  # user sees matches the promise made in the note.
  linear_df <- if (!is.null(object$linear_df)) {
    d <- as.integer(object$linear_df)
    if (identical(family_string, "negbin")) {
      # Strip one for the intercept and one for theta.
      d <- d - 2L
    } else if (identical(family_string, "survreg")) {
      # survreg$idf counts the intercept plus estimated scale parameter(s).
      d <- d - as.integer(if (is.null(object$idf)) 1L else object$idf)
    } else if (identical(family_string, "multinomial")) {
      d <- d - as.integer(if (is.null(object$n_logits)) 1L else object$n_logits)
    } else if (mfp2_family_is_ordinal(family_string)) {
      d <- d - length(object$mfp2_ordinal_intercepts)
    } else if (mfp2_family_has_intercept(family_string)) {
      # Strip the intercept and, when applicable, estimated GLM dispersion.
      d <- d - 1L - as.integer(mfp2_glm_estimates_dispersion(
        family = object$family,
        family_string = family_string
      ))
    }
    d
  } else {
    NA_integer_
  }
  if (!is.na(linear_df) && linear_df < 0L) linear_df <- 0L

  # The MFP row uses the FP-adjusted convention (sum of df_final over selected
  # variables), which is already intercept- and sigma-free by construction.
  mfp_df <- mfp2_summary_model_df(object)

  values <- data.frame(
    label         = c("Full linear model", "MFP model"),
    fit_statistic = fit_statistic,
    df            = c(linear_df, mfp_df),
    stringsAsFactors = FALSE
  )
  attr(values, "statistic_label") <- if (
    mfp2_family_is_survival(family_string) ||
    identical(family_string, "multinomial")
  ) {
    "-2 log L"
  } else {
    "Deviance"
  }
  if (identical(family_string, "multinomial")) {
    attr(values, "n_logits") <- as.integer(object$n_logits)
  } else if (mfp2_family_is_ordinal(family_string)) {
    attr(values, "n_ordinal_intercepts") <- length(object$mfp2_ordinal_intercepts)
  }
  values
}

#' Print the Model Fit Block
#'
#' Prints the shared Model Fit block: heading, two-row table (Full linear /
#' MFP), and family-specific df note. Shared by [print.mfp2()] and
#' [print.summary.mfp2()] so the two methods produce identical output.
#' Callers pass a pre-computed values data frame to avoid recomputing it.
#'
#' `heading_printer` is a function of one string that draws the section
#' heading in the caller's own style, so [print.mfp2()] can reuse its
#' boxed-rule helper without leaking those internals into the summary path.
#' The summary printer supplies its own rule-based heading.
#'
#' @param values Values data frame from
#'   `mfp2_summary_model_fit_values()`.
#' @param digits Integer scalar controlling the number of decimal places
#'   used when formatting the fit statistic.
#' @param heading_printer Function of one string that prints the section
#'   heading.
#' @param notes Logical. If `TRUE`, print the explanatory df note.
#'
#' @return Invisibly returns `NULL`. Called for its side effect of
#'   printing.
#'
#' @keywords internal
#' @noRd
mfp2_format_model_fit_block <- function(values, digits, heading_printer,
                                        notes = TRUE) {
  if (is.null(values)) return(invisible(NULL))
  heading <- attr(values, "heading", exact = TRUE)
  heading_printer(if (is.null(heading)) "Model Fit" else heading)

  # Model-fit statistics use a fixed number of decimal places. The `digits`
  # argument controls decimal places here, rather than significant digits, so
  # values in the Deviance / -2 log L column remain vertically consistent.
  decimal_places <- suppressWarnings(as.integer(digits[1L]))
  if (length(decimal_places) != 1L ||
      is.na(decimal_places) ||
      decimal_places < 0L) {
    decimal_places <- 3L
  }

  # Right-align numeric columns; left-align the label. Column widths are
  # chosen from the widest formatted value so the note below reads under the
  # correct table width regardless of magnitude.
  statistic <- vapply(values$fit_statistic, function(v) {
    if (is.na(v) || !is.finite(v)) return("NA")
    formatC(v, format = "f", digits = decimal_places)
  }, character(1L))
  df_fmt <- vapply(values$df, function(v) {
    if (is.na(v)) return("NA")
    format(v, trim = TRUE)
  }, character(1L))

  statistic_label <- attr(values, "statistic_label", exact = TRUE)
  if (is.null(statistic_label) || length(statistic_label) != 1L) {
    statistic_label <- "Deviance"
  }

  label_width <- max(nchar(values$label))
  statistic_width <- max(nchar(statistic_label), max(nchar(statistic)))
  df_width <- max(nchar("df"), max(nchar(df_fmt)))

  # Column separators: two spaces after the label, four spaces before df.
  header_fmt <- sprintf(
    "%%-%ds  %%%ds    %%%ds\n",
    label_width, statistic_width, df_width
  )
  row_fmt <- header_fmt

  cat(sprintf(header_fmt, "", statistic_label, "df"))
  for (i in seq_len(nrow(values))) {
    cat(sprintf(row_fmt, values$label[i], statistic[i], df_fmt[i]))
  }
  cat("\n")

  # Note about the df column. Kept identical between print.mfp2() and
  # print.summary.mfp2() so users see one consistent explanation.
  if (isTRUE(notes)) {
    if (!is.null(heading)) {
      cat("df counts fitted mean-model coefficients, including the intercept, plus 1 df\n")
      cat("for each selected FP power. Smaller selection scores are preferred.\n")
      return(invisible(NULL))
    }
    n_logits <- attr(values, "n_logits", exact = TRUE)
    n_ordinal_intercepts <- attr(
      values, "n_ordinal_intercepts", exact = TRUE
    )
    if (!is.null(n_logits)) {
      q <- n_logits
      note_lines <- c(
        sprintf("df counts coefficients across %d non-reference logits, excluding their intercepts,", q),
        "plus 1 df for each estimated FP power shared across logits. A linear term",
        sprintf("adds %d df, FP1 adds %d df, and FP2 adds %d df.", q, q + 1L, 2L * q + 2L)
      )
    } else if (!is.null(n_ordinal_intercepts)) {
      note_lines <- c(
        sprintf(
          "df excludes the %d ordinal threshold intercept%s and counts fitted regression",
          n_ordinal_intercepts,
          if (identical(n_ordinal_intercepts, 1L)) "" else "s"
        ),
        "coefficients, plus 1 df for each estimated FP power (FP1 = 2 df, FP2 = 4 df).",
        "A retained catzero or spike-at-zero binary indicator adds 1 df."
      )
    } else {
      note_lines <- c(
        "df counts fitted regression coefficients, excluding the intercept, plus 1 df",
        "for each estimated FP power (FP1 = 2 df, FP2 = 4 df). A retained catzero",
        "or spike-at-zero binary indicator adds 1 df; binary-only SAZ uses 1 df."
      )
    }
    for (ln in note_lines) cat(ln, "\n", sep = "")
  }
}

#' Print a Summary of an `mfp2` Model Fit
#'
#' Renders the structured summary produced by [summary.mfp2()].
#'
#' @param x An object of class \code{"summary.mfp2"}.
#' @param notes Logical. If \code{FALSE}, suppress the explanatory model-df
#'   note. Defaults to the value stored by [summary.mfp2()].
#' @param ... Not used.
#'
#' @return Invisibly returns \code{x}.
#'
#' @seealso [summary.mfp2()], [print.mfp2()]
#'
#' @export
print.summary.mfp2 <- function(x, notes = x$notes, ...) {
  validate_logical_vector(notes, "notes", allowed_lengths = 1L)

  if (isTRUE(x$multinomial)) {
    digits <- if (!is.null(x$digits)) x$digits else 3L
    rule <- paste(rep("=", 78L), collapse = "")
    dash <- paste(rep("-", 78L), collapse = "")
    cat(rule, "\nMFP Model Summary\n", rule, "\n\n", sep = "")
    if (!is.null(x$call)) {
      cat("Call:\n")
      print(x$call)
      cat("\n")
    }
    mfp2_print_model_header(
      family_string = "multinomial",
      criterion = x$criterion,
      converged = x$converged,
      n = x$n,
      metadata = list(link = "logit"),
      digits = digits,
      response_frequencies = x$response_frequencies
    )
    cat(sprintf(
      "\nReference class: %s | Non-reference logits: %d\n",
      x$reference_class, x$n_logits
    ))
    cat("FP powers: common across logits\n\n")
    cat(dash, "\nSelection Overview\n", dash, "\n", sep = "")
    print.data.frame(x$function_table, row.names = FALSE, right = FALSE)
    cat("\n", dash, "\nCoefficient Tests\n", dash, "\n", sep = "")
    display <- x$coefficients
    display$logit <- paste0(display$outcome, " vs ", display$reference)
    display <- display[, c("logit", "term", "coefficient", "se", "z", "p")]
    display <- format_model_print_table(display, digits)
    print.data.frame(display, row.names = FALSE)
    cat("\n")
    mfp2_format_model_fit_block(
      x$model_fit_values,
      digits = digits,
      heading_printer = function(title) cat(dash, "\n", title, "\n", dash, "\n", sep = ""),
      notes = notes
    )
    cat("\n", rule, "\n", sep = "")
    return(invisible(x))
  }

  digits <- if (!is.null(x$digits)) x$digits else 3L
  width <- 78L
  rule_eq <- paste(rep("=", width), collapse = "")
  rule_dash <- paste(rep("-", width), collapse = "")

  section <- function(title) {
    cat(rule_dash, "\n", title, "\n", rule_dash, "\n", sep = "")
  }

  # --- Banner --------------------------------------------------------------
  cat(rule_eq, "\n", "MFP Model Summary", "\n", rule_eq, "\n\n", sep = "")

  # --- Call ----------------------------------------------------------------
  #
  # The summary opens with a plain "Call:" label rather than the boxed
  # "Model Call" section heading used by print.mfp2(). print()'s style is
  # consistent internally -- every one of its sections uses the same dashed
  # rule -- but for summary() the opening call reads better as a light
  # preamble than as a heavy first section.
  if (!is.null(x$call)) {
    cat("Call:\n")
    print(x$call)
    cat("\n")
  }

  # --- Model metadata ------------------------------------------------------
  model_metadata <- list(
    distribution = x$distribution,
    scale = x$scale,
    scale_fixed = x$scale_fixed,
    dispersion = x$dispersion,
    dispersion_fixed = x$dispersion_fixed,
    scale_strata = x$scale_strata,
    distribution_parameters = x$distribution_parameters,
    censoring = x$censoring,
    link = x$link,
    theta = x$theta,
    gee_response_family = x$gee_response_family
  )
  mfp2_print_model_header(
    family_string = x$family,
    criterion = x$criterion,
    converged = x$converged,
    n = x$n,
    nevents = x$nevents,
    metadata = model_metadata,
    digits = digits,
    response_frequencies = x$response_frequencies
  )
  cat("\n")

  # --- Selection overview --------------------------------------------------
  section("Selection Overview")
  ft <- x$function_table
  # Selected first, then excluded.
  ft <- ft[order(ft$Selected != "yes"), , drop = FALSE]
  print.data.frame(ft, row.names = FALSE, right = FALSE)
  cat(sprintf("\nVariables selected: %d of %d\n\n",
              sum(ft$Selected == "yes"), nrow(ft)))

  # --- Ordinal intercepts --------------------------------------------------
  # Printed as a dedicated section before linear/nonlinear terms so that
  # threshold parameters are not confused with MFP-selected predictor terms.
  if (!is.null(x$ordinal_intercepts) && nrow(x$ordinal_intercepts) > 0L) {
    section("Ordinal Intercepts")
    oi  <- x$ordinal_intercepts
    fmt_ordinal <- function(v) format_print_decimal(v, digits)
    disp_oi <- data.frame(
      Threshold       = oi$threshold,
      Estimate        = fmt_ordinal(oi$estimate),
      `Std. Error`    = fmt_ordinal(oi$se),
      z               = fmt_ordinal(oi$z),
      p               = mfp2_summary_format_p(oi$p, digits),
      `[95% CI coef]` = sprintf(
        "[%s, %s]",
        fmt_ordinal(oi$ci_lower),
        fmt_ordinal(oi$ci_upper)
      ),
      check.names     = FALSE,
      stringsAsFactors = FALSE
    )
    print.data.frame(disp_oi, row.names = FALSE, right = FALSE)
    link_label <- switch(
      x$link,
      logistic = "logistic (proportional-odds)",
      probit = "probit",
      loglog = "log-log",
      cloglog = "complementary log-log",
      cauchit = "cauchit",
      "ordinal"
    )
    cat(sprintf(
      "\nThresholds for the %s cumulative-link model.\n\n",
      link_label
    ))
  }

  # --- Linear terms --------------------------------------------------------
  section("Linear Terms")
  if (nrow(x$linear_terms) == 0L) {
    cat("(none)\n\n")
  } else {
    lt <- x$linear_terms
    fmt <- function(v, d = digits) format_print_decimal(v, d)

    disp <- data.frame(
      # Show the user-facing variable name, not the internal fitted-column
      # name. `lt$variable` is populated by mfp2_summary_linear_table() with
      # the ".N" suffix stripped from `lt$term`; the stored `term` remains
      # available for programmatic mapping back to coef(fit).
      Term = lt$variable,
      coef = fmt(lt$coef),
      `se(coef)` = fmt(lt$se),
      stat = fmt(lt$statistic),
      p = mfp2_summary_format_p(lt$p, digits),
      check.names = FALSE,
      stringsAsFactors = FALSE
    )
    stat_name <- attr(lt, "statistic_label", exact = TRUE)
    if (is.null(stat_name) || !stat_name %in% c("t", "z", "Wald")) {
      stat_name <- "Statistic"
    }
    names(disp)[names(disp) == "stat"] <- stat_name
    # GEE reports a Wald chi-square, so its p-value header follows geepack's
    # Pr(>|W|) convention rather than the normal-theory "p".
    if (identical(stat_name, "Wald")) {
      names(disp)[names(disp) == "p"] <- "Pr(>|W|)"
    }

    if (!is.null(lt$exp_coef)) {
      disp[["[95% CI coef]"]] <- sprintf(
        "[%s, %s]", fmt(lt$ci_lower_coef), fmt(lt$ci_upper_coef)
      )
      disp[["exp(coef)"]] <- fmt(lt$exp_coef)
      disp[["[95% CI exp(coef)]"]] <- sprintf(
        "[%s, %s]", fmt(lt$ci_lower), fmt(lt$ci_upper)
      )
    } else {
      disp[["[95% CI coef]"]] <- sprintf(
        "[%s, %s]", fmt(lt$ci_lower), fmt(lt$ci_upper)
      )
    }

    print.data.frame(disp, row.names = FALSE, right = FALSE)
    cat("\n")

    if (!is.null(lt$exp_coef)) {
      cat(sprintf(
        "exp(coef) is the %s.\n\n",
        if (is.null(x$exp_label)) "multiplicative effect" else x$exp_label
      ))
    } else {
      cat("Coefficients are on the link scale.\n\n")
    }
  }

  # --- Nonlinear terms -----------------------------------------------------
  section("Nonlinear Terms")
  if (nrow(x$nonlinear_terms) == 0L) {
    cat("(none)\n\n")
  } else {
    nt <- x$nonlinear_terms
    test_label <- attr(nt, "test_label", exact = TRUE)
    if (is.null(test_label)) test_label <- "LR chi-sq"
    disp <- data.frame(
      Variable = nt$variable,
      Function = nt$form,
      df = nt$df,
      statistic = format_print_decimal(nt$lr_chisq, digits),
      p = mfp2_summary_format_p(nt$p, digits),
      check.names = FALSE,
      stringsAsFactors = FALSE
    )
    names(disp)[names(disp) == "statistic"] <- test_label
    print.data.frame(disp, row.names = FALSE, right = FALSE)
    cat("\n")
    if (identical(x$family, "gee")) {
      cat(
        "Joint robust Wald tests for each nonlinear GEE term, using the selected\n",
        "covariance estimator. df retain the MFP power-search adjustment\n",
        "(FP1 = 2, FP2 = 4).\n\n",
        sep = ""
      )
    } else {
      cat(
        "Joint likelihood-ratio tests for each variable in the final MFP model,\n",
        "with all other selected functional forms held fixed. df follow the MFP\n",
        "convention (FP1 = 2, FP2 = 4).\n\n",
        sep = ""
      )
    }

    # Optional: fitted-function formulas.
    if (!is.null(x$formulas)) {
      cat("Fitted functions:\n")
      for (f in x$formulas) cat("  ", f, "\n", sep = "")
      cat("\n")
    }

    # Optional: coefficients and centering constants for nonlinear terms.
    if (!is.null(x$basis)) {
      cat("Coefficients for nonlinear terms:\n")
      bt <- x$basis
      disp_b <- data.frame(
        Variable = bt$variable,
        Basis = bt$term,
        Center = format_print_decimal(bt$center, digits),
        Coefficient = format_print_decimal(bt$coef, digits),
        check.names = FALSE,
        stringsAsFactors = FALSE
      )
      print.data.frame(disp_b, row.names = FALSE, right = FALSE)
      cat("\n")
    }

    # ACD component labels use the compact A(x) notation above. Print the
    # stored transformation once so the internal training scale remains
    # explicit without incorrectly scaling the ordinary FP basis.
    if (!is.null(x$acd_definitions)) {
      cat("ACD definitions:\n")
      for (definition in x$acd_definitions) {
        cat("  ", definition, "\n", sep = "")
      }
      cat("\n")
    }
  }

  # --- GEE working correlation and scale -----------------------------------
  # For marginal GEE models, report the parameters a GEE analyst reads
  # alongside the coefficients (rendered by the shared helper so print.mfp2()
  # and print.summary.mfp2() display them identically).
  mfp2_print_gee_parameters(x$gee, digits, section)

  # --- Model fit -----------------------------------------------------------
  #
  # The Model Fit block is rendered by the shared helper
  # mfp2_format_model_fit_block(), which is called identically by
  # print.mfp2(). This ensures the two methods display the same family-specific
  # fit statistic and df convention, together with the same optional note. The
  # `section()` helper defined above draws the dash-rule heading used elsewhere
  # in the summary output.
  mfp2_format_model_fit_block(
    values          = x$fit$model_fit,
    digits          = digits,
    heading_printer = section,
    notes           = notes
  )

  cat("\n", rule_eq, "\n", sep = "")
  invisible(x)
}

#' Format a P-Value Vector for Table Display
#'
#' Thin wrapper around `format_print_pvalue()` used by the summary tables so
#' that all p-value formatting flows through a single named helper.
#'
#' @param p Numeric vector of p values.
#' @param digits Integer scalar controlling the number of significant
#'   digits.
#'
#' @return Character vector of formatted p values.
#'
#' @keywords internal
#' @noRd
mfp2_summary_format_p <- function(p, digits = 3L) {
  format_print_pvalue(p, digits)
}

#' Components Kept for Compatibility With mfp2 1.0.x
#'
#' In mfp2 1.0.x, `summary()` on a fitted model returned the underlying
#' summary object (for example from [stats::summary.glm()]). This helper copies
#' the commonly used components of that object so that existing code reading
#' them from a `summary.mfp2` object keeps working.
#'
#' @param raw_summary Raw summary produced by `mfp2_summary_raw()`, or `NULL`.
#'
#' @return A named list with those of `coefficients`, `cov.scaled` and
#'   `cov.unscaled` that are present in `raw_summary`; an empty list otherwise.
#'
#' @keywords internal
#' @noRd
mfp2_summary_compat_components <- function(raw_summary) {
  if (!is.list(raw_summary)) {
    return(list())
  }
  keep <- c("coefficients", "cov.scaled", "cov.unscaled")
  keep <- keep[keep %in% names(raw_summary)]
  unclass(raw_summary)[keep]
}

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.