Package 'perspectev'

Permutation of Species During Turnover Events

Description

Provides a robust framework for analyzing the reducibility of differential survival with respect to higher level trait variation. In addition to its primary test, it also provides functions for simulation-based power analysis, reading in common data set formats, and visualizing results. For tutorial see: http://evolve.zoo.ox.ac.uk/Evolve/Perspectev.html.

Details

Package:	perspectev
Type:	Package
Version:	1.1
Date:	2015-08-07
License:	GPL-3

Author(s)

Kenneth B. Hoehn <[email protected]>

---

Home range estimation

Description

Compute and plot a minimum convex polygon estimate of "home range." Source code borrowed from wild1 package.

Usage

hr.mcp(x,y=NULL,n.min=50,plot=TRUE,add=FALSE,ID=NULL,...)

Arguments

x	A vector, matrix, or data frame of coordinates.
y	A numeric vector (if x is a vector) or NULL
n.min	If x includes fewer than n.min points, the function will return NA and a warning.
plot	Parameter nonfunctional for perspectev implementation of this function.
add	Logical. Add to existing plot on current output device? Default is FALSE.
ID	Required argument from Polygons
...	Optional arguments for plot or points (see also par).

Details

See plot.Polygons for another way of plotting polygon objects.

Value

Returns an object of class Polygons (sp).

Author(s)

Glen A. Sargeant
U.S. Geological Survey
Northern Prairie Wildlife Research Center
[email protected]

Edited by Kenneth B. Hoehn
[email protected]

---

Supplied data sets

Description

Occurrence data used in perspectev tutorial, and test data set used for checking.

Details

occurrence_data: See online tutorial for futher information.

---

Calculate upper and lower level trait values and survivorship

Description

Calculates upper and lower level trait values and survivorship given a data set and trait functions

Usage

perspectev.calc(data,traitfun,vlist=list(),na.rm=FALSE)

Arguments

data	Dataframe in perspectev format (see below).
traitfun	Function for calculating trait value at each level.
vlist	Optional variable list for trait function.
na.rm	Remove NA values from trait functions? Shouldn't need to be used if trim=TRUE from perspectev.read.

Value

upper	Table of survivorship and trait value at upper level (scaled to mean 0 and variance 1)
lower	Table of survivorship and trait value at lower level (scaled to mean 0 and variance 1)
stats	[1]: correlation between upper level trait and survivorship, [2-4]: quantiles of upper level trait values (unscaled)

Author(s)

Kenneth B. Hoehn <[email protected]>

---

Plotting function for permutation analysis

Description

Make plots to summarize permutation results and power analysis results

Usage

perspectev.plot(observed, simulated, names, title)

Arguments

observed	Object returned from perspectev.test().
simulated	List of up to eight objects obtained from perspectev.simulate().
names	Names of each object in the list provided to "simulated" in order.
title	Title of the plot. Optional.

Author(s)

Kenneth B. Hoehn <[email protected]>

---

Convert occurrence data to perspectev input format

Description

Convert occurrence data (each row a separate occurrence) into standardized perspectev format.

Usage

perspectev.read(data,upper,lower,traits,survProb,traitfun,extinctionAge=NULL,
  occurrenceAge=NULL,vlist=NULL,trim=TRUE,
  projection=FALSE,quiet=FALSE)

Arguments

data	Occurrence data. This must list each occurrence on a separate row, with upper/lower level classification specified in separate columns, as well as one or more columns specifying the trait-data for that occurrence (e.g. latitude and longitude). For example see data(occurrence_data).
upper	Column name designation for upper level names.
lower	Column name designation for lower level names.
traits	A column name (string) or vector of column names which correspond to the trait data under investigation. The order in which trait names are specified is important and corresponds to the t1/t2 designation of trait functions.
survProb	Designates lower level survivorship probability, may be either: 1) A dataframe with three columns: Upper name, lower name, survivorship probability. Preferred option - compatible with continuous survivorship probability. 2) A dataframe with two columns: Upper name, lower name. Specifies lower units named as survivorship probability = 1, and all others as 0. 3) A vector of names of surviving lower level units. Upper and lower names must be separated by a space. If unspecified will assign survivorship based on occurrenceAge and extinctionAge.
occurrenceAge	Column name desigation for the age of the occurrence. Only necessary if survProb unspecified, and will be ignored if survProb is specified.
extinctionAge	Age of the extinction in backward time. E.g. 65.5 for K-Pg mass extinction if occurrenceAge is in mya. Occurrences with ages greater than or equal to extinctionAge will be used to calculate trait values, and lower level units with occurrences before and after extinctionAge are marked as survivors. Lower level units with occurrences only after extinctionAge are excluded. Only necessary if survProb unspecified, and will be ignored if survProb is specified.
traitfun	Function for calculating trait values at each level. Not necessary if trim=FALSE.
vlist	Optional variable list for trait function.
trim	Remove lower levels that give NA's from trait function? (recommended)
projection	Convert coordinates to a Mollweide projection?
quiet	Suppress information messages?

Details

Function specifies traits under analysis and survivorship probabilities of lower level units. See tutorial (http://evolve.zoo.ox.ac.uk/Evolve/Perspectev.html) for examples.

Traits are specified by supplying the column names of trait data values (e.g. Latitude and Longitude) as a vector. The order in which the traits are specified is important, as this will be the basis of the index in trait functions (first in vector is first in trait list, second in vector is second in trait list, etc..). You can check this after the fact using the Key value. If trim=TRUE, supply a trait function using the traitfun parameter, and this function will remove all lower units which give an NA value in the trait function (e.g. having < 3 distinct coordinates for MCP range).

Survivorship probability may be specified in four ways:

1) The best way is to supply a dataframe to survProb. This data frame should be of column format: <Upper Name> <Lower Name> <Survivorship Probability>, and should specify a survivorship probability for all lower level units in the occurrence data.

2) Similar to 1), but a dataframe of column format: <Upper Name> <Lower Name>. This will assign all lower units specified as having a survivorship probability of 1, and all others as 0.

3) Similar to 2), but a vector of names formed by pasting Upper and Lower names together, separated by a space (e.g. c("Genus1 Species1", "Genus2 Species2"))

4) Specifying occurrenceAge and extinctionAge. occurrenceAge is the column name for the age of the occurrences, and extinctionAge is the age of the extinction (both in backward time). All units with occurrences that only occur after the extinction are discarded. All units that have some occurrences with ages < extinctionAge, and some occurrences >= extinctionAge (found before and after extinction) are assigned survivorship = 1. All those which only have occurrences >= extinctionAge are assigned survivorship = 0. Note that this will assign any lower level entity found both before/during and after the extinctionAge parameter as a survivor, while any lower level entity only found in the beginning will be listed as a victim. Specifying these parameters is only necessary if survProb is unspecified, and they will be ignored if it is.

In all cases it is important to ensure your data set does not span too far back, because all occurrences provided, unless otherwise stated (see 4, above), will be used to calculate trait values. This is may or may not be good.

Value

Survivorship	Dataframe containing upper/lower level classification and survivorship probability for each lower level unit.
Traits	List containing trait data vectors for each lower level unit.
Key	Shows indexes of trait values in Traits list, corresponds to order used in "traits" parameter.

Author(s)

Kenneth B. Hoehn <[email protected]>

Examples

data(testData)
  survivorship = data.frame(cbind(testData$Genus,testData$Species,runif(nrow(testData),0,1)))
  data = perspectev.read(testData,survProb=survivorship,
  upper="Genus",lower="Species",traits=c("Lat","Long"),traitfun=mcpRange,
  projection=FALSE)

---

Simulate upper/lower level selection at different intensities and observe resulting p values.

Description

Perform simulations of natural selection on a data set, and observe what p values result. Performs linear transformation of trait vs. survivorship (using provided or fitted slope and intercept) and then transforms into survviorship probabilites using inv.logit function.

Usage

perspectev.simulate(data,simulations,cores,traitfun=mcpRange,vlist=NULL,
	binary=NA,intercept=NA,slope=NA,level=NA,noise=0,fit=FALSE,quiet=FALSE)

Arguments

data	Dataframe in perspectev format. See ?perspectev.read for more information.
simulations	Number of simulations to perform. At least 1000 is recommended but can be slow.
cores	Number of cores over which to parallelize the simulations.
traitfun	Function for calculating trait value at each level.
vlist	Optional variable list for trait function.
intercept	Intercept of the regression between range and survivorship. Can be manually provided or, if not provided, is fit to the data set. Will attempt to set automatically if unspecified.
slope	Slope of the regression between range and survivorship. Can be manually provided or, if not provided, is fit to the data set. Will attempt to set automatically if unspecified.
level	Simulate either upper or lower level selection. Accepts either "lower" or "upper" respectively. Will set to 'upper' if unspecified.
noise	Extra stochasticity to the simulation.
fit	Fit simulation to observed parameters? Will do automatically if intercept or slope are not specified.
binary	Is survivorship binary or continuous? Will attempt to set automatically if unspecified.
quiet	Suppress information messages?

Value

correlation_simulated	Correlation between trait and surivovorship from permuted groups at each simulation.
correlation_observed	Observed correlation between trait and surivovorship from simulated groups.
pvalue	p value observed under simulation of selection.
level	Level of simulated selection.
intercept	Intercept of simulation.
slope	Slope of the simulation.
noise	Noise level selected for simulation.
fitted_model	Was the model fitted to the data set?

Note

See original publication and tutorial for more information on simulation.

Author(s)

Kenneth B. Hoehn <[email protected]>

---

Test for irreducibility of relationship between upper level traits and survivorship

Description

Performs permutation tests by permuting upper level labels between lower levels, recalculating upper trait value, and taking the correlation between upper level trait and survivorship. This process is repeated until a null distribution is generated. This is then compared against observed covariance to give a p value for the null hypothesis that a relationship between trait and survivorship is explainable by random aggregations of lower level traits.

Usage

perspectev.test(data,iterations=1000,cores=1,traitfun=mcpRange,vlist=NULL,na.rm=FALSE)

Arguments

data	Dataframe in perspectev format (see ?perspectev.read).
iterations	Number of iterations to perform. At least 1000 is recommended, though can be slow.
cores	Number of cores over which to parallelize the test.
traitfun	Function for calculating trait values at each level.
vlist	Optional variable list for trait function.
na.rm	Remove NA values from trait functions? Shouldn't need to be used if trim=TRUE from perspectev.read.

Value

correlation_permuted	Correlations between trait and survivorship obtained from permuted upper levels (Si)
correlation_observed	Observed correlation between upper level trait and survivorship (Ri)
pvalue	Portion of permuted genus correlations (S) larger than observed value (R)
permuted_quantiles	Matrix of interquartile trait values obtained from each upper level permutation

Author(s)

Kenneth B. Hoehn <[email protected]>

Examples

data(testData)

  	data = perspectev.read(testData,extinctionAge=5,occurrenceAge="Age",
  	upper="Genus",lower="Species",traits=c("Lat","Long"),traitfun=mcpRange,projection=FALSE)

  	#4 iterations chosen out of convenience - use more!
	mcpTest  = perspectev.test(data,4,1,traitfun=mcpRange)
	mcpSim  = perspectev.simulate(data,4,1,traitfun=mcpRange)
	perspectev.plot(mcpTest,list(mcpSim),c("S1"),"Test")

---