humboldt.g2e: Convert geographic space to shared environmental space
In jasonleebrown/humboldt: Analysis of Species in Environmental Space

humboldt.g2e

R Documentation

Convert geographic space to shared environmental space

Description

Convert geographic space to shared environmental space

Usage

humboldt.g2e(
  env1,
  env2,
  sp1,
  sp2,
  reduce.env = 2,
  reductype = "PCA",
  non.analogous.environments = "NO",
  nae.window = 5,
  env.trim = T,
  e.var,
  col.env = e.var,
  env.trim.type = "MCP",
  trim.mask1,
  trim.mask2,
  trim.buffer.sp1 = 200,
  trim.buffer.sp2 = 200,
  pcx = 1,
  pcy = 2,
  rarefy.dist = 0,
  rarefy.units = "km",
  env.reso,
  kern.smooth = 1,
  R = 100,
  run.silent = F
)

Arguments

`env1`	environmental variables for all sites of the study area 1 (env1). Column names should be x,y,X1,X2,...,Xn; with X1-Xn being any string label. If env1=env2, input the same file twice.
`env2`	environmental variables for all sites of the study area 2 (env2). Column names should be x,y,X1,X2,...,Xn; with X1-Xn being any string label. If env1=env2, input the same file twice.
`sp1`	occurrence sites for the species/population 1 at study area 1 (env1). Column names should be 'sp','x','y'
`sp2`	occurrence sites for the species/population 2 at study area 2 (env2). Column names should be 'sp','x','y'
`reduce.env`	the format to trim environmental space so that it is shared. If reduce.env=1, the second input environment (env2) will be trim the match the first input (env1). If reduce.env=2, both input environments trimmed so that extents of both are identical (the lower maximum value observed in env1 and env2 and the higher minimum value observed in env1 and env2 will be used to trim environmental space for each PC/environmental variable) If reduce.env=0, you will skip trimming environmental space
`reductype`	if reduce.env= 1 or 2, the 'reducetype' parameter specifies the format for how to reduce environmental space ("PCA" or "STANDARD"). If reductype="PCA", the environmental space will be trimmed based on two principal components. If reductype="STANDARD", the environmental space will be trimmed by each included variable specified in col.env. if reduce.env=0, do not include this parameter
`non.analogous.environments`	allow non-analogous environment in environmental space? If non.analogous.environments="YES" non-analogous environments between env1 and env2 will retained. If non.analogous.environments="NO" non-analogous environments between env1 and env2 will be removed. This parameter is only usable under the combinations of reductype="PCA" & reduce.env=1 or reductype="PCA" & reduce.env=2
`nae.window`	the spatial window from which non-analogous environments will be quantified. The non-analogous environments are characterized by gridding the espace of env1 and env2 into a R x R grid (e.g. 100 x 100). If nae.window=0, values absent from a cell in one environment will be removed from the other. If nae.window>0, values absent from a window (or neighborhood of cells) in one environment will be trimmed from the other. The nae.window value characterizes the number of cells to search from the focal cell of environmental space values in the other environment. The larger the nae.window value, the fewer non-analogous environments removed. This parameter allows imperfect overlap of environments. If areas of environmental space are a little patchy between environments—but generally present– a larger nae.window value will retain more of the patch environments. The default value is a nae.window=5
`env.trim`	Trim extent of environmental data in geographic space. Necessary for comparing if species have diffrent access to habitats. If this env.trim=T, non-accesible environments will be removed. See associated parameters "env.trim.type", "trim.buffer.sp1", "trim.buffer.sp2"
`e.var`	selection of variables to include in all of the analyses of E-space. This is a separate parameter than col.env, but must contain all variables included in col.env. Note that it can include more variables than those in col.env, as long as those in col.env are also included.
`col.env`	if reductype="STANDARD", then parameter specifies the number of columns to trim environmental space on. This can be any number of columns. This can be a subset or all of the enviroment layers input.
`env.trim.type`	This parameter is only used if env.trim=TRUE. There options exist, trim enviromental data by: a buffered minimum-convex-polygon (env.trim.type="MCP"), a buffer around all occurence localties (env.trim.type="RADIUS"), and an advanced input mask option (env.trim.type="MASK") that allows a user to input a shapefile. For env.trim.type="RADIUS" & "MCP", the parameters 'trim.buffer.sp1' and 'trim.buffer.sp2' specifices the buffer distance used to trim accessible enviroments in km. Default= "MCP"
`trim.mask1`	This parameter is only used if env.trim.type="MASK". This allows users to input their own mask that trim the environmental data based on access to habitats. This parameter directs Humboldt the user to input a shapefile for species 1. Input the text name of your stored shapefile in your R global enviroment. Imporant note: CRS of shapefile for must equal "+proj=longlat +datum=WGS84"
`trim.mask2`	This parameter is only used if env.trim.type="MASK". This allows users to input their own mask that trim the environmental data based on access to habitats. This parameter directs Humboldt the user to input a shapefile for species 2. Input the text name of your stored shapefile in your R global enviroment. Imporant note: CRS of shapefile for must equal "+proj=longlat +datum=WGS84"
`trim.buffer.sp1`	buffer distance (in km) for trimming available environmental space for sp1
`trim.buffer.sp2`	buffer distance (in km) for trimming available environmental space for sp2
`pcx`	An integer that identifies one (of two) principal components used to perform niche quantification and quantitative tests on. Default=1. Both defaults result in the 1 and 2 PCs being compared.
`pcy`	An integer that identifies the second (of two) principal components used to perform niche quantification and quantitative tests on. Default=2. Both defaults result in the 1 and 2 PCs being compared.
`rarefy.dist`	remove occurrences closer than a minimum distance to each other (this function uses the humboldt.occ.rarefy function). Values need to be in km[recommended] or decimal degrees. See associated parameter rarefy.units. Note: rarefy.dist=0 will remove no occurrences
`rarefy.units`	the units of rarefy.dist parameter, either "km" for kilometers or "dd" for decimal degrees
`env.reso`	the resolution of the input environmental data grid in decimal degrees
`kern.smooth`	scale at which kernel smoothing occurs on environmental data, larger values (i.e. 2) increase scale (making a espace transitions smoother and typically larger) and smaller values (i.e. 0.5) decrease scale (making occupied espace clusters more dense and irregular). Note this value is only used in this script as a secondary test of espace trimming efficiency. Default value is 1
`R`	Resolution of grid in environmental space (RxR)
`thresh.espace.z`	this parameter is an experimental parameter and controls the level at which values below the kernel density z values are removed for creating areas of analogous environmental space. Higher values will increase value from which the low-density areas are removed from the environmental space of z1 and z2. Basically values above this are retained and values below are removed. Default=0.001

Value

This function converts geographic distributions in environmental space (e-space). Several factors need to be considered when doing this. Do you include or exclude non-analogous environments? Do you trim environment space so that only shared environmental space is being analyzed? These factors directly effects the questions asked in humboldt.equivalence.stat & humboldt.background.stat. For example, if run on full environment input for background statistics and equivalence statistic, you are testing the total equivalence between species (or divergence) in current distributions. However if ran with trimmed, shared espace. The equivalence statistics for niche evolution or niche divergence (as these measures should only be evaluated in shared analogous espace)

IMPORTANT go to the following webpage for a visual explanation of input parameters: https://github.com/jasonleebrown/humboldt/blob/master/HumboldtInputExp.pdf

Examples

library(humboldt)

##load environmental variables for all sites of the study area 1 (env1). Column names should be x,y,X1,X2,...,Xn)
env1<-read.delim("env1.txt",h=T,sep="\t")

## load environmental variables for all sites of the study area 2 (env2). Column names should be x,y,X1,X2,...,Xn)
env2<-read.delim("env2.txt",h=T,sep="\t") 

## remove NAs and make sure all variables are imported as numbers
env1<-humboldt.scrub.env(env1)
env2<-humboldt.scrub.env(env2)

##load occurrence sites for the species at study area 1 (env1). Column names should be species,x,y)
occ.sp1<-na.exclude(read.delim("sp1.txt",h=T,sep="\t"))

##load occurrence sites for the species at study area 2 (env2). Column names should be species,x,y). 
occ.sp2<-na.exclude(read.delim("sp2.txt",h=T,sep="\t"))

zz=humboldt.g2e(env1=env1, env2=env2, sp1=occ.sp1, sp2=occ.sp2, reduce.env = 2, reductype = "PCA", non.analogous.environments = "NO", env.trim= T, env.trim.type= "MCP", e.var=c(3:21),  col.env = e.var, trim.buffer.sp1 = 200, trim.buffer.sp2 = 200, rarefy.dist = 50, rarefy.units="km", env.reso=0.41666669, kern.smooth = 1, R = 100, run.silent = F)

jasonleebrown/humboldt documentation built on Jan. 4, 2024, 7:46 a.m.