plot.mfpi: Plot MFPI Fitted Functions and Group Differences

View source: R/mfpi_plot.R

plot.mfpiR Documentation

Plot MFPI Fitted Functions and Group Differences

Description

Plot group-specific fitted functions and differences between groups for variables tested for interaction by mfpi(). Continuous predictors are shown as curves; binary and categorical predictors are shown as points at each fitted level.

Usage

## S3 method for class 'mfpi'
plot(
  x,
  terms = NULL,
  plot_type = c("both", "fitted", "difference"),
  auto_print = TRUE,
  show_title = TRUE,
  show_grid = TRUE,
  show_rug = FALSE,
  show_ci_fitted = FALSE,
  show_ci_diff = TRUE,
  show_null_line = FALSE,
  show_maineffect_line = TRUE,
  show_ci_maineffect = FALSE,
  legend_position = c("inside", "right", "left", "bottom", "top", "none"),
  legend_inside = c(0.02, 0.98),
  legend_justification = c(0, 1),
  colour_ref = "#2166AC",
  colour_group = "#D6604D",
  line_types = NULL,
  colour_diff = "#1B7837",
  colour_null = "grey50",
  colour_maineffect = "grey20",
  linewidth = 1,
  ribbon_alpha = 0.2,
  rug_alpha = 0.4,
  ...
)

Arguments

x

An object of class "mfpi" returned by mfpi().

terms

An optional character vector naming variables tested for interaction. The default is NULL, which plots selected interactions only. Specify a variable to plot its interaction even if it was not selected.

plot_type

A character string specifying the plots to display: "fitted" for group-specific functions, "difference" for the comparison-group function minus the reference-group function, or "both" for side-by-side plots. Default: "both", which requires the optional patchwork package.

auto_print

A logical value indicating whether to display plots automatically. Default: TRUE. Use FALSE to return the plots without displaying them.

show_title

A logical value indicating whether to display titles and subtitles. Default: TRUE.

show_grid

A logical value indicating whether to display panel grid lines. Default: TRUE. Use FALSE to remove them.

show_rug

A logical value indicating whether to show observed continuous predictor values as rug marks along the horizontal axis. Default: FALSE.

show_ci_fitted

A logical value indicating whether to display confidence intervals for group-specific functions. Default: FALSE.

show_ci_diff

A logical value indicating whether to display confidence intervals for group differences. Default: TRUE.

show_null_line

A logical value indicating whether to add a horizontal line at zero to difference plots. Default: FALSE.

show_maineffect_line

A logical value indicating whether to add the constant group difference estimated by the model without interaction to difference plots. Default: TRUE. The line is omitted if that model is unavailable.

show_ci_maineffect

A logical value indicating whether to display a confidence band around the main-effects reference line. Requires show_maineffect_line = TRUE and an available standard error. Default: FALSE.

legend_position

A character string specifying the legend position: "inside" (default), "right", "left", "bottom", "top", or "none".

legend_inside

Two numeric values giving the horizontal and vertical position of an inside legend, between 0 and 1. The bottom-left corner is c(0, 0) and the top-right corner is c(1, 1). Default: c(0.02, 0.98).

legend_justification

Two numeric values specifying which part of an inside legend is anchored at legend_inside. Default: c(0, 1), which anchors the legend at its top-left corner.

colour_ref

Colour of the reference-group curve, points, and confidence intervals. Default: "#2166AC".

colour_group

Colour of the comparison-group curve, points, and confidence intervals. Default: "#D6604D".

line_types

An optional character vector specifying curve styles. For example, c("solid", "dashed") gives the reference group a solid line and the comparison group a dashed line. Alternatively, assign styles to group labels, for example c(Placebo = "solid", Treatment = "dashed"), using the labels in your data. Default: NULL, which makes all lines solid.

colour_diff

Colour of the difference curve, points, and confidence intervals. Default: "#1B7837".

colour_null

Colour of the zero reference line. Default: "grey50".

colour_maineffect

Colour of the main-effects reference line. Default: "grey20".

linewidth

A positive number controlling curve width. Default: 1.

ribbon_alpha

Confidence-band transparency, from 0 (transparent) to 1 (opaque). Default: 0.2.

rug_alpha

Rug-mark transparency, from 0 (transparent) to 1 (opaque). Default: 0.4.

...

Not used. Supplied arguments generate a warning.

Value

Invisibly returns a named list with one element per plotted interaction variable. Each element contains a list of plots comparing individual groups with the reference group.

For multinomial models, each variable's results contain an additional list level for the non-reference response categories.

Individual plots are ggplot2 objects. With plot_type = "both", each group comparison contains a combined patchwork plot. Returned plots can be modified or saved using ggplot2::ggsave(). Use auto_print = FALSE to obtain them without displaying them.

An empty list is returned if no interactions were selected and terms = NULL.

Interpreting the plots

Each variable is plotted using its separate fitted interaction model. The reference group is the one used during fitting. With more than two groups, a separate plot is produced for each comparison with the reference. Multinomial models also produce separate plots for each non-reference response category.

Fitted functions include the predictor contribution, group main effects, and model intercept where applicable. They exclude contributions from other adjustment variables and offsets. Group differences include both the group main-effect difference and differences between the predictor functions (see Kipruto, Royston and Sauerbrei (2026) for details).

Plots use the model's linear-predictor scale. For example, Gaussian models with an identity link use the outcome scale, and binomial models with a logit link use the log-odds scale. See predict.mfpi() for interpretation by model family.

Confidence intervals use a fixed confidence level of 95%. They are pointwise intervals, shown as shaded bands for continuous predictors and error bars for binary and categorical predictors. They are conditional on the fitted model and do not account for uncertainty from selecting variables, transformations, or interactions.

Reference lines

Difference plots can show two horizontal reference lines.

The zero line indicates no difference between the groups. Add it using show_null_line = TRUE.

The main-effects line shows the group difference estimated by the model without interaction. That model assumes the predictor has the same effect in every group, so the group difference is constant across predictor values. This line is shown by default; use show_maineffect_line = FALSE to hide it. Use show_ci_maineffect = TRUE to add its 95% confidence band.

References

Kipruto, E., Royston, P. and Sauerbrei, W. (2026). Multivariable Fractional Polynomial Interaction Models in R. Journal of Statistical Software.

See Also

mfpi(), predict.mfpi(), summary.mfpi()

Examples

data("prostate")

# Include the grouping variable in the formula and name it in group_var.
fit <- mfpi(
  lpsa ~ fp(age) + svi + fp(pgg45) + fp(cavol) + fp(weight) +
    fp(bph) + fp(cp),
  data = prostate,
  family = gaussian(),
  group_var = "svi",
  interaction_vars = c("cavol", "age"),
  flex = "flex1",
  p_interact = 0.9,
  include_group_var = TRUE,
  center = FALSE,
  verbose = FALSE
)

# Plotting requires ggplot2.
if (requireNamespace("ggplot2", quietly = TRUE)) {
  # Plot an interaction even if it was not selected.
  plot(fit, terms = "cavol", plot_type = "difference")

  # Plot group-specific functions with confidence bands.
  plot(
    fit, terms = "cavol", plot_type = "fitted",
    show_ci_fitted = TRUE
  )

  # Return plots without displaying them.
  plots <- plot(
    fit, terms = "cavol", plot_type = "difference",
    auto_print = FALSE
  )
  print(plots$cavol[[1]])
}


# Side-by-side plots require patchwork and ggplot2.
if (requireNamespace("patchwork", quietly = TRUE) &&
    requireNamespace("ggplot2", quietly = TRUE)) {
  plot(fit, terms = "cavol", plot_type = "both")
}



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