summary.mfp2: Summarize an 'mfp2' Model Fit

View source: R/mfp2_summary.R

summary.mfp2R Documentation

Summarize an mfp2 Model Fit

Description

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.

Usage

## S3 method for class 'mfp2'
summary(
  object,
  formulas = FALSE,
  basis = FALSE,
  raw = FALSE,
  notes = TRUE,
  digits = 3L,
  ...
)

Arguments

object

A fitted mfp2() object.

formulas

Logical. If TRUE, append the fitted-function formula for each nonlinear variable. Default FALSE.

basis

Logical. If TRUE, append a table of the individual fitted basis coefficients for nonlinear terms. Default FALSE.

raw

Logical. If TRUE, bypass the structured summary and return the raw model-specific summary object, with the fitting call replaced by the original mfp2() call. Default FALSE.

notes

Logical. If FALSE, suppress the explanatory model-df note when the structured summary is printed. Default TRUE.

digits

Number of decimal places used when printing numeric output other than fractional-polynomial powers and degrees of freedom. Defaults to 3.

...

Further arguments. When raw = TRUE, passed to the underlying summary method; otherwise ignored.

Details

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.

The summary is organised into the following sections:

  • Selection Overview: a compact overview of the selected functional form for each variable.

  • Ordinal Intercepts: for ordinal models, the estimated threshold intercepts with standard errors, Wald statistics, p-values, and confidence intervals.

  • 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.

  • 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.

  • 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 formulas = TRUE to append the fitted-function formulas, or basis = TRUE to append the individual fitted basis coefficients. For an active ACD component, either option also prints the fitted definition of A(x), including the scale used during fitting. Set 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.

Value

When raw = FALSE, an object of class "summary.mfp2": a list with components call, family, criterion, converged, n, nevents, model-specific components distribution, scale, scale_fixed, dispersion, dispersion_fixed, scale_strata, distribution_parameters, censoring, link, theta, and response_frequencies, plus function_table, linear_terms, nonlinear_terms, basis (or NULL), formulas (or NULL), acd_definitions (or NULL), ordinal_intercepts (a threshold-inference data frame for ordinal models, otherwise NULL), fit, raw_summary, and notes. For compatibility with earlier versions, it also contains coefficients, cov.scaled and cov.unscaled when the underlying summary provides them (for example for GLM-type models); these are not printed. For multinomial models, linear_terms, nonlinear_terms, basis, formulas, acd_definitions, ordinal_intercepts, and fit are replaced by coefficients (the outcome-specific coefficient table), model_fit_values, multinomial, class_levels, reference_class, n_logits, and digits. A dedicated print method renders these. When raw = TRUE, the underlying summary object.

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.

See Also

mfp2(), print.mfp2(), stats::summary.glm(), survival::summary.coxph(), survival::summary.survreg()

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


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