pretty_predictions_1d: Pretty one-dimensional predictions

In edwardlavender/prettyGraphics: Pretty Graphics with R

Pretty one-dimensional predictions

Description

This function plots pretty one-dimensional predictions from a statistical model. Given a model, for each predictor, the function plots the predicted values of the response and associated 95 percent confidence intervals. Other predictors are held at the first level (for factors) or an average (e.g., mean or median, as specified) value (for doubles) or at custom values specified in a dataframe called newdata.

Usage

pretty_predictions_1d(
  model,
  data = NULL,
  newdata = NULL,
  constants = NULL,
  x_var = NULL,
  n_pred = 100,
  average = mean,
  extract_fit = function(p) p$fit,
  extract_se = function(p) p$se.fit,
  transform_x = NULL,
  xlim = NULL,
  ylim = NULL,
  ylim_fix = TRUE,
  pretty_axis_args = list(),
  add_points = list(cex = 0.5, lwd = 0.5, col = "grey20"),
  add_points_jitter = list(),
  add_error_bars = list(add_fit = list(pch = 3)),
  add_error_envelope = list(),
  add_order = c("predictions", "points"),
  add_xlab = list(line = 2.5),
  add_ylab = list(line = 2.5),
  add_main = list(adj = 0, font = 2),
  one_page = TRUE,
  ...
)

Arguments

model	A model (e.g. an output from gam).
data	(optional) The dataframe used to fit the model. If missing, this is extracted via model.frame(model); however, this approach may fail if functions (e.g., scale) have been applied to variables as part of the model formula.
x_var, n_pred, average, newdata, constants	(optional) Prediction controls. x_var is a character variable that defines the name(s) of predictors for which to plot predictions. If unsupplied, predictions are plotted for each predictor in the model. n_pred is a number that defines, for continuous predictors, the prediction resolution. For each continuous predictor, a sequence of values from the minimum to maximum value for that variable, with n_pred elements, is used for prediction. (For factors, predictions are plotted for each factor level.) Alternatively, newdata can be supplied. average is a function that is used to define the value at which doubles are held constant for prediction. The default is mean. newdata is a dataframe that contains the data used for prediction. If supplied, this should contain one variable that changes in value (defined in x_var), with other variables held at selected values. If supplied, this supersedes constants (see below). constants is a one-row dataframe of constant values for explanatory variables. If supplied, n_pred model predictions are generated for x_var, while holding other variables constant at the values specified in constants.
extract_fit, extract_se	Functions that extract fitted values and standard errors, respectively, from the object returned by predict.
transform_x	A function to transform values of the predictor(s) for plotting.
xlim, ylim, ylim_fix, pretty_axis_args	Axis controls. xlim and ylim control axis limits for all plots. If unsupplied, pretty limits are used. If pretty limits are used, ylim_fix is a logical variable that defines whether or not to use the same y-axis limits on all plots (TRUE), which can facilitate comparisons, or to use plot-specific limits (FALSE). pretty_axis_args is a named list of arguments, passed to pretty_axis, for further control.
add_points	(optional) A named list of arguments, passed to points, to customise observations added to plots. An empty list specifies default options. NULL suppresses this argument.
add_points_jitter	A named list of jitter values for points. If supplied, element names should correspond to selected predictor variables in the model. Each element should contain two non-negative numbers that define the amount to jitter points in the x and y directions. Jittering is implemented using runif. This is silently ignored if add_points is NULL. Note that jittering does not currently influence axis limits, so use this option with caution.
add_error_bars, add_error_envelope	(optional) Named lists of arguments, passed to add_error_bars and add_error_envelope, to customise the appearance of error bars (for factor predictors) or envelopes (for continuous predictors) respectively. Empty lists specify default options. NULL suppresses these arguments.
add_order	A character vector or a list that defines the order in which you want to add predictions and points. By default, predictions are added first, since these often mask points otherwise. However, this order is reversible. If a list is supplied, this must be a named list, with one element for each predictor variable, that defines the order.
add_xlab, add_ylab, add_main	(optional) Named lists of arguments, passed to mtext, to add axis titles to plots. X-axis labels and plot titles are added to each plot, while only one global y-axis label is added. Empty lists specify default arguments, in which case variable names are taken as specified in the model and plot titles are given as capitalised letters or numbers in square brackets (if there are more than 26 predictors). Alternatively, names can be specified via the ‘text’ argument to mtext. For add_xlab and add_main , the ‘text’ argument can be a vector with one element for each plot; for add_ylab only one element should be supplied. NULL suppress these arguments.
one_page	A logical variable that defines whether or not to plot all plots on one page.
...	Additional arguments passed to pretty_plot.

Details

Interactions are not currently supported.

Value

The function plots predictions from a model. A list of axis parameters, with one element (from pretty_axis) for each variable, is returned invisibly.

Author(s)

Edward Lavender

See Also

pretty_predictions_2d

Examples

#### Define a model for predictions
mod_1 <- stats::lm(Sepal.Length ~ Sepal.Width + Species, data = iris)
summary(mod_1)

#### Example (1): Plot predictions using default options
pretty_predictions_1d(mod_1)

#### Example (2): Plot predictions for specified variables
pretty_predictions_1d(mod_1, x_var = c("Sepal.Width"))
pretty_predictions_1d(mod_1, x_var = c("Sepal.Width", "Species"))

#### Example (3): Plot predictions using custom newdata
p_dat <- data.frame(Sepal.Width = median(iris$Sepal.Width),
                    Species = factor(levels(iris$Species),
                                     levels = levels(iris$Species)))
pretty_predictions_1d(mod_1,
                      x_var = "Species",
                      newdata = p_dat)
# Or use constants to use custom constants but standard values for x_var
pretty_predictions_1d(mod_1,
                      constants = data.frame(Sepal.Width = 3),
                      x_var = "Species")

#### Example (4): Customise uncertainty
pretty_predictions_1d(mod_1,
                      add_error_bars = list(cex = 5, bg = "black"),
                      add_error_envelope = list(type = "lines"))

#### Example (5): Customise axes
pretty_predictions_1d(mod_1,
                      ylim = c(NA, 10))
pretty_predictions_1d(mod_1,
                      ylim_fix = FALSE)
pretty_predictions_1d(mod_1,
                      pretty_axis_args = list(control_digits = 2))

#### Example (6): Customise titles
pretty_predictions_1d(mod_1,
                      add_xlab = list(text = c("Width", "Species"), line = 2),
                      add_ylab = list(line = -2),
                      add_main = NULL)

#### Example (7) Back transformations
# The function can be implemented with tranformed variables, but note:
# * Transformations must be applied to the dataframe used to fit the model
# ... (and not in the model fitting function);
# * Transformations should not change variable types (e.g. scale() transforms
# ... numbers into matrices, and this is not permitted).
# * All numeric variables are affected by transform_x

## (A) Scale variable and plot predictions on transformed scale
# Define function to scale numbers that doesn't change variable types
scale_num <- function(x) {
  y <- scale(x)
  attributes(y)$dim <- NULL
  y
}
# Scale Sepal.Width
iris$Sepal.Width.S <- scale_num(iris$Sepal.Width)
# Implement model
mod_2 <- stats::lm(Sepal.Length ~ Sepal.Width.S + Species, data = iris)
# Visualise predictions
pretty_predictions_1d(mod_2)

## (B) Back-transform predictions
unscale <- function(x) {
  mu      <- attr(x, "scaled:center")
  sigma   <- attr(x, "scaled:scale")
  x * sigma + mu
}
pretty_predictions_1d(mod_2, transform_x = unscale)

#### Example (8) Jitter points
# Jitter points horizontally for species
pretty_predictions_1d(mod_1, add_points_jitter = list(Species = c(0.1, 0)))

#### Example (9) Modify order of points/predictions
# Customise plot order across all predictors
pretty_predictions_1d(mod_1, add_order = c("points", "predictions"))
# Predictor-specific customisation
pretty_predictions_1d(mod_1,
                      add_order = list(Sepal.Width = c("predictions", "points"),
                                      Species = c("points", "predictions")))

edwardlavender/prettyGraphics documentation built on Jan. 19, 2025, 2:47 p.m.