R: Interpolate functional characteristics over a grid

krige_surf {Morphoscape}

R Documentation

Interpolate functional characteristics over a grid

Description

krige_surf() performs 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, 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.
`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.
`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)
kr_surf

# Add new data
data("turtles")
kr_surf <- krige_new_data(kr_surf, new_data = turtles)
kr_surf
plot(kr_surf)

# Doing it all in one step:
## Not run: 
kr_surf <- krige_surf(warps_fnc, new_data = turtles, hull = "alphahull")
kr_surf

## End(Not run)

# No hull and padding
kr_surf <- krige_surf(warps_fnc, new_data = turtles, hull = NULL, padding = 1.2)
plot(kr_surf)

[Package Morphoscape version 1.0.2 Index]