Interpolate functional characteristics over a grid

krige_surf() performs automatic or manual kriging (i.e., interpolation) of one or more functional characteristics that are spatially distributed over a morphospace to create a smoothly kriged surface. Interpolated values can also be produced for a new dataset given their coordinates in morphological space.

Usage

krige_surf(fnc_df, vgm = NULL, grid = NULL, resample = 100, padding = 1.2, hull = NULL, 
  alpha = 1, new_data = NULL)
           
  
krige_new_data(x, new_data)

Arguments

fnc_df: a fnc_df object; the output of a call to as_fnc_df, which contains coordinates in morphological space and values of functional characteristics for the warps used to create the kriged surface.
vgm: a user supplied list of variogram models generated from gstat::vgm(). When this is supplied, a manual kriging is performed using gstat::krige. Else, autoKrige is called. When supplied, list length should match the number of variables
grid: a matrix or data frame containing the grid of points over which the surface is to be interpolated. Should be the output of a call to resample_grid. If NULL, the grid will be formed by calling resample_grid() on the inputs.
resample: the number of points (or pixels) in the x and y dimensions over which to create the grid. Default is 100 for a kriged surface of 100x100=10,000 pixels. Passed to resample_grid. Ignored when grid is not NULL.
padding: a number representing how much to expand the grid beyond the ranges of the x- and y-coordinates. For example, padding = 1.2 (the default) expands the grid by 20% of the coordinates' ranges in each direction. Must be a number greater than or equal to 1. Large numbers imply greater extrapolation, and whatever padding is added will be negated if hull = TRUE. Passed to resample_grid. Ignored when grid is not NULL.
hull: method to to restrict kriging to an alpha hull to prevent extrapolation beyond the coordinates present in fnc_df. Passed to resample_grid, which uses alphahull or concaveman packages. Default is alphahull::ahull. If no hull is desired set hull = NULL. If NULL, kriging will take place over a rectangular grid that spans the boundaries of the coordinates in fnc_df. Ignored when grid is not NULL
alpha: the alpha value used to create the alpha hull. Passed to resample_grid and eventually to alphahull::ahull. Ignored when grid is not NULL.
new_data: a dataset of coordinates for a new sample; the values of the functional characteristics for this sample will be interpolated using the kriged surface.
debug: shows all warnings called from autoKrige. Only used for debugging purposes
x: a "kriged_surfaces" object; the output of a call to krige_surf().

Details

krige_surf() implements the automap::autoKrige function on one or more spatially distributed traits to produce an interpolated (or extrapolated) surface of evenly spaced gridpoints. This is done by automatiically finding the best variogram fit for each of the non-corrdinate variables in fnc_df. For details on automatic variogram fitting, see automap::autoKrige.

Input data in fnc_df can be unevenly distributed (direct from speciments), or gridded (determined from evenly distributed hypothetical shapes) in morphospace. Trait data inputted directly from specimen measurements will be subject to error based on the how unevenly points are distributed, with high resoultion gridded datapoints producing the least potential reconstruction error (see Smith et al 2021).

By default krige_surf will create a hull to strictly prevent any extrapolation beyond the provided data. This will produce the most conservative landscapes. If hull is set to FALSE, then the function will reconstruct a rectangle determined by the XY coordinate ranges supplied in fnc_df. Padding will be applied by default (an extra 20%) as defined by padding, to expand the rectangle beyond the supplied points. Reconstructions without a hull would be most appropriate for trait data determined from evenely spaced hypothetical gridpoints. If grid is provided the function will strictly interpolate at these gridded points.

krige_new_data() adds a new data set to the supplied kriged_surfaces object and interpolates the values of the functional characteristics on the suppllied sample. This should only be used to add a new dataset to a kriged_surfaces object produced without new_data supplied or to replace an existing new_data component.

Value

An object of class kriged_surfaces containing the following components:

fnc_df: the original data frame of functional characteristics passed to fnc_df.
autoKrige: a named list of the kriged surfaces, one for each functional characteristic. Each surface is of class autoKrige, the output of the call to automap::autoKrige.
dataframes: a list of two data frames, grid and new_data. grid contains the coordinates of the kriged surface grid (in the x and y columns) as well as the interpolated values of the functional characteristics. new_data contains the sample coordinates supplied to new_data as well as the interpolated values of the functional characteristics for each sample. This second component is absent if new_data = NULL in the call to krige_surf().

For krige_new_data(), the original kriged_surfaces object, with the $dataframes$new_data component containing the sample coordinates supplied to new_data as well as the interpolated values of the functional characteristics for each sample.

References

Smith, S. M., Stayton, C. T., & Angielczyk, K. D. (2021). How many trees to see the forest? Assessing the effects of morphospace coverage and sample size in performance surface analysis. Methods in Ecology and Evolution, 12(8), 1411-1424.

Examples

data("warps")

warps_fnc <- as_fnc_df(warps)

grid <- resample_grid(warps, hull = "concaveman", plot = TRUE)


kr_surf <- krige_surf(warps_fnc, grid = grid)
#> [using ordinary kriging]
#> [using ordinary kriging]
#> [using ordinary kriging]
#> [using ordinary kriging]
kr_surf
#> A kriged_surfaces object
#> - functional characteristics:
#> 	hydro, curve, mech, fea
#> - surface size:
#> 	70 by 70
#> 	α-hull applied (α = 1)
#> - original data:
#> 	24 rows

# Add new data
data("turtles")
kr_surf <- krige_new_data(kr_surf, new_data = turtles)
#> [using ordinary kriging]
#> [using ordinary kriging]
#> [using ordinary kriging]
#> [using ordinary kriging]
kr_surf
#> A kriged_surfaces object
#> - functional characteristics:
#> 	hydro, curve, mech, fea
#> - surface size:
#> 	70 by 70
#> 	α-hull applied (α = 1)
#> - original data:
#> 	24 rows
#> - new data:
#> 	40 rows
plot(kr_surf)


# Doing it all in one step:
if (FALSE) {
kr_surf <- krige_surf(warps_fnc, new_data = turtles, hull = "alphahull")
kr_surf
}

# No hull and padding
kr_surf <- krige_surf(warps_fnc, new_data = turtles, hull = NULL, padding = 1.2)
#> [using ordinary kriging]
#> [using ordinary kriging]
#> [using ordinary kriging]
#> [using ordinary kriging]
#> [using ordinary kriging]
#> [using ordinary kriging]
#> [using ordinary kriging]
#> [using ordinary kriging]
plot(kr_surf)