stgam (version 1.2.0)

evaluate_models: Evaluates multiple models with each predictor variable specified in different ways in order to determining model form

Description

Evaluates multiple models with each predictor variable specified in different ways in order to determining model form

Usage

evaluate_models(
  input_data,
  target_var,
  model_family = "gaussian()",
  vars,
  coords_x = "X",
  coords_y = "Y",
  VC_type = "SVC",
  time_var = NULL,
  k_set = FALSE,
  spatial_k = 50,
  temporal_k = 10,
  k_increase = FALSE,
  k2edf_ratio = 1.5,
  k_multiplier = 2,
  max_iter = 10,
  ncores = 2
)

Value

a data.frame with indices for each predictor variable, the knots specified in each smooth (ks), a AIC score (aic) for each model and the associated formula (f). The output should be passed to the gam_model_rank function.

Arguments

input_data

he data to be used used to create the GAM model in (data.frame or tibble format), containing an Intercept column to allow it be treated as an addressable term in the model.

target_var

the name of the target variable.

model_family

the mdoel family, defaults to Guassian

vars

a vector of the predictor variable names (without the Intercept).

coords_x

the name of the X, Easting or Longitude variable in input_data.

coords_y

the name of the Y, Northing or Latitude variable in input_data.

VC_type

the type of varying coefficient model: options are "TVC" for temporally varying, "SVC" for spatially varying and "STVC" for space-time.

time_var

the name of the time variable if undertaking STVC model evaluations.

k_set

a logical value for user defined k values. The default is FALSE. Cannot be used with k_increase.

spatial_k

the value of k for spatial smooths if k_set is TRUE.

temporal_k

the value of k for temporal smooths if k_set is TRUE.

k_increase

a logical value of whether to check and increase the number of knots in each smooth. The default is FALSE.

k2edf_ratio

a threshold of the ratio of the number of knots, k, in each smooth to its Effective Degrees of Freedom. If any smooth has a knots-to-EDF ratio less than this value then the knots are iteratively increased by the k_multiplier value until the threshold check is passed, the number knots passes the maximum degrees of freedom, or the number of iterations, max_iter is reached. Cannot be used with k_set.

k_multiplier

a multiplier by which the knots are increased on each iteration. The default is 2.

max_iter

the maximum number of iterations that k is increased.

ncores

the number of cores to use in parallelised approaches (default is 2 to overcome CRAN package checks). This can be determined for your computer by running parallel::detectCores()-1. Parallel approaches are only undertaken if the number of models to evaluate is greater than 30.

Examples

if (FALSE) {
require(dplyr)
require(doParallel)
require(sf)

# define input data
data("chaco")
input_data <-
  chaco |>
  # create Intercept as an addressable term
  mutate(Intercept = 1) |>
  # remove the geometry
  st_drop_geometry()

# evaluate different model forms
# example 1 with 6 models and no `k` adjustment
svc_mods <-
  evaluate_models(
    input_data = input_data,
    target_var = "ndvi",
    model_family = "gaussian()",
    vars = c("tmax"),
    coords_x = "X",
    coords_y = "Y",
    VC_type = "SVC"
  )
# have a look!
svc_mods

# example 2 with 6 models and `k` adjustment
svc_k1_mods <-
  evaluate_models(
    input_data = input_data,
    target_var = "ndvi",
    vars = c("tmax"),
    model_family = "gaussian()",
    coords_x = "X",
    coords_y = "Y",
    VC_type = "SVC",
    k_increase = TRUE,
    k2edf_ratio = 1.5,
    k_multiplier = 2,
    max_iter = 10
  )
# have a look!
svc_k1_mods

# example 3 with 6 models and `k` set by user
svc_k2_mods <-
  evaluate_models(
    input_data = input_data,
    model_family = "gaussian()",
    target_var = "ndvi",
    vars = c("tmax"),
    coords_x = "X",
    coords_y = "Y",
    VC_type = "SVC",
    time_var = NULL,
    k_set = TRUE,
    spatial_k = 20,
  )
# have a look!
svc_k2_mods
}