calcPoly {Morphoscape}

Calculate polynomial fits over a surface

Description

calcPoly calls on the spatial package to fit rectangular spatial polynomial surface models by least-squares, or GLS. These methods allow the user to test whether data have spatial trends in morphospace. Outputs are a polynomial trend surface, and ANOVA table for the model fit. multiPoly applies calcPoly to a fnc_df with outputs for each trait. For more extensive documentation for model fitting see the spatial package.

Usage

calcPoly(fnc, npoly = 3, fnc.name = NULL, 
         gls.covmod = list(covmod = expcov, d = 0.7, alpha = 0, se = 1), 
         pad = 1.2, resample = 100, range = NULL, verbose = FALSE)
                     
multiPoly(fnc_df, npoly = 3, ...)                     

Arguments

fnc

an XYZ dataframe or matrix of a spatially distributed trait.

fnc_df

a functional dataframe from as_fnc_df with colnames corresponding to X,Y and trait names.

npoly

singular numeric. Degree of polynomial to fit ragning from 1-4. For multiPoly this can also be a vector with length equal to the numer of traits in order to specify the degree of polynomial to apply to each trait.

gls.covmod

Optional list of arguments to pass to surf.gls if fitting by generalized least-squares is desired. Defaults to NULL, and fitting is performed by least-squares. See surf.gls and expcov documentation for a full list of arguments and usage.

fnc.name

Optional speficiation of the trait name. Defaults to NULL, and will use column names instead.

pad

Degree by which to extrapolate input data. Defaults to 1.2.

resample

Resampling density. Corresponds to the number of points calculated along both X and Y axes. Defaults to 100. If no resampling is desired, set reample = NULL

range

Optional. Manually set X and Y ranges. Input is a 2x2 matrix with rows corresponding to X and Y ranges respectively.

verbose

Optional. Logical. If TRUE, will print ANOVA tables.

...

Arguments to pass onto calcPoly when using multiPoly

Details

Fits polynomial trend surfaces using the 'spatial' package. First, an npoly polynomial trend surface is fit by least squares using surf.ls or generalized least-squares by surf.gls. GLS is fit by one of three covariance functions, exponential (expcov), gaussian (gaucov) or spherical (sphercov) and requires additional parameters to be passed as a list through gls.covmod (see examples). For a full description of arguments and usage see surf.gls and expcov documentation.

The surface is then evaluated using trmat within limits set by input data, or manually using range.

Value

An object of class poly_surf, or multi_surf with the following components:

fnc.name

name of trait

poly

Polynomial trend fit output from surf.ls

surface

Evaluated trend surface output from trmat

grid

Expanded surface in long XZY dataframe format

peak

Coordinates and height of the peak of the surface

Author(s)

Blake V. Dickson

References

Dickson, B.V. and Pierce, S.E. (2019), Functional performance of turtle humerus shape across an ecological adaptive landscape. Evolution, 73: 1265-1277. https://doi.org/10.1111/evo.13747

See Also

surf.ls, surf.gls, expcov, trmat,

Examples

require(spatial)

data("warps")
warps_fnc <- as_fnc_df(warps)

# Make single trait dataframe 
hydro_fnc <- data.frame(warps_fnc[ ,1:2], warps_fnc[ ,"hydro"])

polysurf <- calcPoly(hydro_fnc)
summary(polysurf)
plot(polysurf)

# Fit using gls

polysurf <- calcPoly(hydro_fnc, gls.covmod = list(covmod = expcov, d = 0.7, alpha = 0, se = 1))
## Not run: 
summary(polysurf)

## End(Not run)
plot(polysurf)

# Calculate multiple polynomial surfaces

multi_poly <- multiPoly(warps_fnc)
## Not run: 
summary(multi_poly)

## End(Not run)
plot(multi_poly)

# Set manual range

polysurf <- calcPoly(hydro_fnc, range = rbind(range(warps_fnc$x) * 1.2,
                                              range(warps_fnc$y) * 1.4))
                                              
polysurf <- calcPoly(hydro_fnc, range = rbind(c(-0.2, 0.12),
                                              c(-0.06, 0.1)) )
## Not run: 
summary(polysurf)

## End(Not run)                                              
# 
# Adjust polynomial degree

multiPoly(warps_fnc, npoly = 2)

# Specify multiple degrees

multi_poly <- multiPoly(warps_fnc, npoly = c(2,3,4,3))

## Not run: 
summary(polysurf)

## End(Not run)
plot(polysurf)