parameterise_smooth: Parameterise smooth functions and compare simulated and...

In edwardlavender/Tools4ETS: Tools for Ecological Time Series

Parameterise smooth functions and compare simulated and inferred smooths

Description

This function helps the user to define reasonable functions for the effect of a covariate on a linear predictor/response for simulations. Then, model-based inferences of the effect of that covariate can be plotted on top of simulated effects to examine the performance of a model in terms of its ability to correctly estimate the simulated function under different scenarios. This function is intended for use primarily in GAMS4DTS.

Usage

parameterise_smooth(
  x,
  f,
  param = list(),
  parameterise_smooth_ls = NULL,
  plot = TRUE,
  add_sim_args = list(type = "l", lwd = 2),
  xlab = "",
  ylab = "",
  plot_gam = FALSE,
  dat,
  model,
  term,
  plot_gam_ls,
  add_error_envelope_args = list(),
  residuals = FALSE,
  add_residuals_args = list(),
  shift_truth = 0,
  shift_predictions = 0,
  add_rug = FALSE,
  add_rug_args = list(),
  add_moons = FALSE,
  add_moons_args = list(),
  pretty_axis_args = list(side = 1:2, pretty = list(n = 10), control_axis = list(las =
    TRUE)),
  mtext_args = list(),
  ...
)

Arguments

x	A numeric sequence of values for which to evaluate the shape of a user-defined function (see below).
f	A function which relates a covariate to a linear predictor/response.
param	A named list of parameters and parameter values required to evaluate the function.
parameterise_smooth_ls	A list from a previous implementation of parameterise_smooth. This is useful following modelling when the aim is to compare simulated and model-inferred smooths. By supplying this list, the function does not have to recompute simulated smooths.
plot	A logical input which defines whether or not to create a plot.
add_sim_args	A named list of arguments to customise the visualisation of the simulated effect of a covariate on the plot.
xlab	A character input which defines the label for the x axis. By default, this is "" so that labels can be added via mtext_args which is more flexible (see below). However, the label can be specified via xlab for speed.
ylab	A character input which defines the label for the y axis. By default, this is "" so that labels can be added via mtext_args which is more flexible (see below). However, the label can be specified via ylab for speed.
plot_gam	A logical input which defines whether or not to plot the output of a GAM on top of the simulated effect.
dat	The dataframe used to fit the GAM.
model	The model used to fit the GAM.
term	A character specifying the term of interest.
plot_gam_ls	The output of plot.gam. This is used as a quick method to add model predictions for the effect of a term on the response, confidence intervals and (optionally) partial residuals to the plot, since these are all computed by plot.gam.
add_error_envelope_args	A named list of arguments passed to add_error_envelope to add predictions to the plot.
residuals	A logical input which defines whether or not to add partial residuals to the plot.
add_residuals_args	A named list of arguments to customise the partial residuals on the plot.
shift_truth	A number which defines a value by which to shift f(x) vertically.
shift_predictions	A number which defines a value by which to shift model predictions/partial residuals vertically.
add_rug	A logical input which defines whether or not to plot a rug. If so, dat, the dataframe used to fit the model, should be provided (see above).
add_rug_args	A named list of arguments passed to rug to customise the rug.
add_moons	A logical input which defines whether or not to add moons to a plot. This is useful for visualising the effects of lunar phase in models of animal movement time series.
add_moons_args	A named list of arguments passed to add_moons.
pretty_axis_args	A named list of arguments, passed to pretty_axis to customise axes.
mtext_args	A named list of arguments, passed to mtext, to add axis labels.
...	Additional plotting parameters passed to pretty_plot.

Author(s)

Edward Lavender

Examples

#### Example 1: Simulate a quadratic effect of variable (e.g. Julian day) on a response (e.g. depth)
# The function creates a plot, so we can 'play' with the parameters
# .... until we're happy with the shape:
smooth_julian_day <-
  parameterise_smooth(x = 0:365,
                      f = quadratic,
                      param = list(a = -0.001, b = 1, h = 183, k = 15),
                      plot = TRUE)
# The function returns a list containing x, f, the parameters we chose and y values:
utils::str(smooth_julian_day)
# We could then use these parameters to simulate a response, model the response using a GAM
# ... and then compare the simulated and modelled relationship using parameterise_smooth() again
# ... (see the vignette or GAMS4DTS() for further examples).

edwardlavender/Tools4ETS documentation built on Nov. 29, 2022, 7:41 a.m.