Heatmap of an APC surface — plot_APCheatmap • APCtools

Plot the heatmap of an APC structure. The function can be used in two ways: Either to plot the observed mean structure of a metric variable, by specifying dat and the variable y_var, or by specifying dat and the model object, to plot some mean structure represented by an estimated two-dimensional tensor product surface. The model must be estimated with gam or bam.

Usage

plot_APCheatmap(
  dat,
  y_var = NULL,
  model = NULL,
  dimensions = c("period", "age"),
  apc_range = NULL,
  bin_heatmap = TRUE,
  bin_heatmapGrid_list = NULL,
  markLines_list = NULL,
  markLines_displayLabels = c("age", "period", "cohort"),
  y_var_logScale = FALSE,
  plot_CI = TRUE,
  method_expTransform = "simple",
  legend_limits = NULL
)

Arguments

dat: Dataset with columns period and age. If y_var is specified, the dataset must contain the respective column. If model is specified, the dataset must have been used for model estimation with gam or bam.
y_var: Optional character name of a metric variable to be plotted.
model: Optional regression model estimated with gam or bam to estimate a smoothed APC surface. Only used if y_var is not specified.
dimensions: Character vector specifying the two APC dimensions that should be visualized along the x-axis and y-axis. Defaults to c("period","age").
apc_range: Optional list with one or multiple elements with names "age","period","cohort" to filter the data. Each element should contain a numeric vector of values for the respective variable that should be kept in the data. All other values are deleted.
bin_heatmap, bin_heatmapGrid_list: bin_heatmap indicates if the heatmap surface should be binned. Defaults to TRUE. If TRUE, the binning grid borders are defined by bin_heatmapGrid_list. This is a list with each element a numeric vector and a name out of c("age","period","cohort"). Can maximally have three elements. Defaults to NULL, where the heatmap is binned in 5 year steps along the x-axis and the y-axis.
markLines_list: Optional list that can be used to highlight the borders of specific age groups, time intervals or cohorts. Each element must be a numeric vector of values where horizontal, vertical or diagonal lines should be drawn (depends on which APC dimension is displayed on which axis). The list can maximally have three elements and must have names out of c("age","period","cohort").
markLines_displayLabels: Optional character vector defining for which dimensions the lines defined through markLines_list should be marked by a respective label. The vector should be a subset of c("age","period","cohort"), or NULL to suppress all labels. Defaults to c("age","period","cohort").
y_var_logScale: Indicator if y_var should be log10 transformed. Only used if y_var is specified. Defaults to FALSE.
plot_CI: Indicator if the confidence intervals should be plotted. Only used if y_var is not specified. Defaults to TRUE.
method_expTransform: One of c("simple","delta"), stating if confidence interval limits should be transformed by a simple exp transformation or using the delta method. The delta method can be unstable in situations and lead to negative confidence interval limits. Only used when the model was estimated with a log or logit link and confidence intervals are supposed to be plotted. Defaults to simple.
legend_limits: Optional numeric vector passed as argument limits to scale_fill_gradient2.

Value

Plot grid created with ggarrange (if plot_CI is TRUE) or a ggplot2 object (if plot_CI is FALSE).

Details

See also plot_APChexamap to plot a hexagonal heatmap with adapted axes.

If the plot is created based on the model object and the model was estimated with a log or logit link, the function automatically performs an exponential transformation of the effect.

References

Weigert, M., Bauer, A., Gernert, J., Karl, M., Nalmpatian, A., Küchenhoff, H., and Schmude, J. (2021). Semiparametric APC analysis of destination choice patterns: Using generalized additive models to quantify the impact of age, period, and cohort on travel distances. Tourism Economics. doi:10.1177/1354816620987198.

Author

Alexander Bauer alexander.bauer@stat.uni-muenchen.de, Maximilian Weigert maximilian.weigert@stat.uni-muenchen.de

Examples

library(APCtools)
library(mgcv)

data(travel)

# variant A: plot observed mean structures
# observed heatmap
plot_APCheatmap(dat = travel, y_var = "mainTrip_distance",
                bin_heatmap = FALSE, y_var_logScale = TRUE)


# with binning
plot_APCheatmap(dat = travel, y_var = "mainTrip_distance",
                bin_heatmap = TRUE, y_var_logScale = TRUE)


# variant B: plot some smoothed, estimated mean structure
model <- gam(mainTrip_distance ~ te(age, period) + residence_region +
             household_size + s(household_income), data = travel)

# plot the smooth tensor product surface
plot_APCheatmap(dat = travel, model = model, bin_heatmap = FALSE, plot_CI = FALSE)


# ... same plot including the confidence intervals
plot_APCheatmap(dat = travel, model = model, bin_heatmap = FALSE)


# the APC dimensions can be flexibly assigned to the x-axis and y-axis
plot_APCheatmap(dat = travel, model = model, dimensions = c("age","cohort"),
                bin_heatmap = FALSE, plot_CI = FALSE)


# add some reference lines
plot_APCheatmap(dat = travel, model = model, bin_heatmap = FALSE, plot_CI = FALSE,
                markLines_list = list(cohort = c(1910,1939,1955,1980)))


# default binning of the tensor product surface in 5-year-blocks
plot_APCheatmap(dat = travel, model = model, plot_CI = FALSE)


# manual binning
manual_binning <- list(period = seq(min(travel$period, na.rm = TRUE) - 1,
                                    max(travel$period, na.rm = TRUE), by = 5),
                       cohort = seq(min(travel$period - travel$age, na.rm = TRUE) - 1,
                                    max(travel$period - travel$age, na.rm = TRUE), by = 10))
plot_APCheatmap(dat = travel, model = model, plot_CI = FALSE,
                bin_heatmapGrid_list = manual_binning)