| Type: | Package |
| Title: | Data Handling and Analysis in Macroecology |
| Version: | 5.0 |
| Date: | 2023-11-22 |
| Description: | Handling, processing, and analyzing geographic data on species' distributions and environmental variables. Read Vilela & Villalobos (2015) <doi:10.1111/2041-210X.12401> for details. |
| License: | GPL-2 |
| Imports: | geosphere, sf |
| Depends: | R (≥ 3.1.0), terra, grDevices, graphics, methods, stats |
| Suggests: | testthat, devtools, knitr, rmarkdown, dplyr, kableExtra, ggplot2 |
| LazyData: | true |
| URL: | https://besjournals.onlinelibrary.wiley.com/doi/full/10.1111/2041-210X.12401, https://github.com/macroecology/letsR, https://brunovilela.github.io/letsR/ |
| BugReports: | https://github.com/macroecology/letsR/issues |
| RoxygenNote: | 7.2.3 |
| Encoding: | UTF-8 |
| VignetteBuilder: | knitr |
| NeedsCompilation: | no |
| Packaged: | 2023-11-22 20:22:10 UTC; brunovilela |
| Author: | Bruno Vilela 
[aut, cre],
Fabricio Villalobos
[aut] |
| Maintainer: | Bruno Vilela <bvilela.bv@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2023-11-23 09:00:02 UTC |
Tools for Data Handling and Analysis in Macroecology.
Description
The letsR package is being developed to help researchers in the handling, processing, and analysis of macroecological data. Its purpose is to integrate these methodological processes into a single software platform for macroecological analyses. The package's main functions allow users to build presence-absence matrices, the basic analytical tool in macroecology, from species' geographical distributions and merge them with species' traits, conservation information (downloadable using functions from this package) and spatial environmental layers. In addition, other package's functions enable users to summarize and visualize information from presence-absence matrices.
Details
All functions in this package use a prefix and a suffix separated by a dot.
The prefix refers to the package's name and the suffix to the actual function.
This is done to avoid confusion with potentially similarly-named functions from other R packages.
For instance, the letsR function used to create presence-absence matrices is called lets.presab (but see also
lets.presab.birds and lets.presab.points) whereas the one used to add variables to a
presence-absence matrix is called lets.addvar.
The package's basic functions create and work on a particular S3 object class called PresenceAbsence.
Such PresenceAbsence object class allows storing information beyond presence-absence data
(e.g. user-defined grid-cell system) and using the generic plot, summary and print functions of R.
Also, some package's functions allow the user to input customary R objects (e.g. vector, matrix,
data.frame).
Another set of functions in this package allow the user to download species' information related to
their description and conservation status as provided by the IUCN's REdList database (lets.iucn,
lets.iucn.ha, lets.iucn.his).
For this, such functions use the IUCN's RedList API to retrieve information from its webpage.
If you are looking for the most recent version of the package, you can get the development version of letsR on github (https://github.com/macroecology/letsR).
| Package: | lestR |
| Type: | Package |
| Version: | 3.1 |
| Date: | 2018-01-24 |
| License: | GPL-2 |
Author(s)
Bruno Vilela
(email: bvilela@wustl.edu;
Website: https://bvilela.weebly.com/)
Fabricio Villalobos
(email: fabricio.villalobos@gmail.com;
Website: https://fabro.github.io)
References
Vilela, B., & Villalobos, F. (2015). letsR: a new R package for data handling and analysis in macroecology. Methods in Ecology and Evolution.
IUCN avaliation for frogs of Phyllomedusa genus
Description
Result of the function lets.iucn
applied to Southern American frog genera Phyllomedusa in 2014.
Usage
data(IUCN)
PresenceAbsence object for frogs of Phyllomedusa genus
Description
PresenceAbsence object obtained using the function lets.presab
in the Geographic distribution of the Southern American frog genus Phyllomedusa.
Usage
data(PAM)
Source
IUCN - https://www.iucnredlist.org/. 2014.
Geographic distribution of Phyllomedusa genus
Description
Geographic distribution of the Southern American frog genera Phyllomedusa. Data was modfied from IUCN (https://www.iucnredlist.org/, downloaded in 05/2014). There are 32 species and 46 polygons.
Usage
data(Phyllomedusa)
Source
IUCN - https://www.iucnredlist.org/. 2014.
PresenceAbsence Class
Description
The PresenceAbsence is a new S3 object class created and
used inside the letsR package. This object class is used to
store information on species distribution within a geographic domain in the
form of a presence-absence matrix. In addition, the PresenceAbsence
object also contains other essential information (e.g. user-defined grid
cell system, including resolution, projection, datum, and extent) necessary
for other analysis performed with the package's functions.
Details
Creating a PresenceAbsence object
A
PresenceAbsence object can be generated using the following
functions:
- lets.presab
- lets.presab.birds
- lets.presab.points
The PresenceAbsence information
The result is a list
object of class PresenceAbsence that includes the following
objects:
- Presence_and_Absence_Matrix: A matrix of species' presence(1) and absence(0)
information. The first two columns contain the longitude (x) and latitude (y)
of the cells' centroid (from the gridded domain used);
- Richness_Raster: A raster containing species richness information across
the geographic domain, which can be used to map the observed geographic
gradient in species richness;
- Species_name: A character vector with species' names contained in
the matrix.
Each of the objects can be obtained usign the standard
subsetting operators that are commonly applied to a list object (i.e.
'[[' and '$').
letsR functions applied to a PresenceAbsence object
The following
functions from the letsR package can be directly applied to a
PresenceAbsence:
- lets.addpoly
- lets.addvar
- lets.distmat
- lets.field
- lets.gridirizer
- lets.iucn
- lets.iucn.ha
- lets.iucn.his
- lets.maplizer
- lets.midpoint
- lets.overlap
- lets.pamcrop
- lets.rangesize
Generic functions applied to a PresenceAbsence object
The
following generic functions can be directly applied to the
PresenceAbsence object.
- print (print.PresenceAbsence)
- summary (summary.PresenceAbsence)
- plot (plot.PresenceAbsence)
Add polygon coverage to a PresenceAbscence object
Description
Add polygon coverage within cells of a PresenceAbsence object.
Usage
lets.addpoly(x, y, z, onlyvar = FALSE, count = FALSE)
Arguments
x |
A |
y |
Polygon of interest. |
z |
A character indicating the column name of the polygon containing the attributes to be used. |
onlyvar |
If |
count |
Logical, if |
Value
The result is a presence-absence matrix of species with the polygons' attributes used added as columns at the right-end of the matrix. The Values represent the percentage of the cell covered by the polygon attribute used.
Author(s)
Bruno Vilela
See Also
Examples
## Not run:
data(PAM) # Phyllomedusa presence-absence matrix
data(wrld_simpl) # World map
Brazil <- wrld_simpl[wrld_simpl$NAME == "Brazil", ] # Brazil (polygon)
# Check where is the variable name
# (in this case it is in "NAME" which will be my z value)
names(Brazil)
PAM_pol <- lets.addpoly(PAM, Brazil, "NAME", onlyvar = TRUE)
## End(Not run)
Add variables (in raster format) to a PresenceAbscence object
Description
Add variables (in raster format), usually environmental, to a PresenceAbsence object. Variables are included as additional columns containing the aggregate/summarize value of the variable(s) in each cell of the presence-absence matrix.
Usage
lets.addvar(x, y, onlyvar = FALSE, fun = mean)
Arguments
x |
A |
y |
Variables to be added in |
onlyvar |
If |
fun |
Function used to aggregate the variables(s) values over each cell. Note that this will only work for variables with a resolution value smaller (i.e. higher resolution) than the PAM. |
Value
The result is a presence-absence matrix of species with the variables added as columns at the right-end of the matrix (but see the 'onlyvar' argument).
Note
The PresenceAbsence and the Raster
variable must be in the same projection.
Author(s)
Bruno Vilela
See Also
Examples
## Not run:
data(temp) # Global mean temperature
temp <- terra::unwrap(temp)
data(PAM) # Phyllomedusa presence-absence matrix
# Mean temperature
PAM_temp_mean <- lets.addvar(PAM, temp)
# Standard deviation of temperature
PAM_temp_sd <- lets.addvar(PAM, temp, fun = sd, onlyvar = TRUE)
# Mean and SD in the PAM
PAM_temp_mean_sd <- cbind(PAM_temp_mean, PAM_temp_sd)
## End(Not run)
Frequency distribution of a variable within a species' range
Description
Based on a species Presence-Absence matrix including
variables of interest (see lets.addvar), the
function divides a continuous variable into classes and counts
the frequency of each class within each species' range.
Usage
lets.classvar(x, groups = "default", pos, xy)
Arguments
x |
Presence-absence |
groups |
The number of classes into which the variable will be divided.
Default calculates the number of classes as the
default for a histogram ( |
pos |
Column number containing the variable of interest. |
xy |
Logical, if |
Value
A matrix with species in the rows and the variable's
classes in the columns.
Author(s)
Bruno Vilela
References
Morales-Castilla et al. 2013. Range size patterns of New World oscine passerines (Aves): insights from differences among migratory and sedentary clades. Journal of Biogeography, 40, 2261-2273.
Examples
## Not run:
data(PAM)
data(temp)
pamvar <- lets.addvar(PAM, temp)
resu <- lets.classvar(x = pamvar, pos = ncol(pamvar), xy = TRUE)
## End(Not run)
Compute correlogram based on the Moran's I index
Description
Computes the Moran's I correlogram of a single or multiple variables.
Usage
lets.correl(x, y, z, equidistant = FALSE, plot = TRUE)
Arguments
x |
A single numeric variable in vector format or multiple variables in matrix format (as columns). |
y |
A distance matrix of class |
z |
The number of distance classes to use in the correlogram. |
equidistant |
Logical, if |
plot |
Logical, if |
Value
Returns a matrix with the Moran's I Observed value, Confidence Interval (95 and Expected value. Also the p value of the randomization test, the mean distance between classes, and the number of observations. quase tudo
Author(s)
Bruno Vilela, Fabricio Villalobos, Lucas Jardim & Jose Alexandre Diniz-Filho
References
Sokal, R.R. & Oden, N.L. (1978) Spatial autocorrelation in biology. 1. Methodology. Biological Journal of the Linnean Society, 10, 199-228.
Sokal, R.R. & Oden, N.L. (1978) Spatial autocorrelation in biology. 2. Some biological implications and four applications of evolutionary and ecological interest. Biological Journal of the Linnean Society, 10, 229-249.
Examples
## Not run:
data(PAM)
data(IUCN)
# Spatial autocorrelation in description year (species level)
midpoint <- lets.midpoint(PAM)
distan <- lets.distmat(midpoint[, 2:3])
moran <- lets.correl(IUCN$Description, distan, 12,
equidistant = FALSE,
plot = TRUE)
## End(Not run)
Compute a geographic distance matrix
Description
Calculates a geographic distance matrix based on a
PresenceAbsence or a two column matrix of x(longitude) and
y(latitude).
Usage
lets.distmat(xy, asdist = TRUE)
Arguments
xy |
A |
asdist |
Logical, if |
Details
This function basically facilitates the use of
terra::distance on a PresenceAbsence object, allowing also
the user to have directly a dist object. The distance is always
expressed in meter if the coordinate reference system is
longitude/latitude, and in map units otherwise. Map units are typically
meter, but inspect crs(x) if in doubt.
Value
The user can choose between dist and matrix class
object to be returned. The resulting values are in kilometres (but see the
argument 'unit' in rdist.earth).
Author(s)
Bruno Vilela & Fabricio Villalobos
Examples
## Not run:
data(PAM)
distPAM <- lets.distmat(PAM)
## End(Not run)
Create species' values based on the species co-occurrence within focal ranges
Description
Create single species' values based on the attributes of species co-occurring within individual ranges.
Usage
lets.field(x, y, z, weight = TRUE, xy = NULL, count = FALSE)
Arguments
x |
A |
y |
Species attribute to be considered. It must be a numeric attribute. |
z |
Species names in the same order as the attributes and exactly the
same as named in the |
weight |
If |
xy |
If |
count |
Logical, if |
Details
If the species do not co-occur with any other species NaN will be returned.
Author(s)
Bruno Vilela & Fabricio Villalobos
References
Villalobos, F. and Arita, H.T. 2010. The diversity field of New World leaf-nosed bats (Phyllostomidae). Global Ecology and Biogeography. 19, 200-211.
Villalobos, F., Rangel, T.F., and Diniz-Filho, J.A.F. 2013. Phylogenetic fields of species: cross-species patterns of phylogenetic structure and geographical coexistence. Proceedings of the Royal Society B. 280, 20122570.
See Also
Examples
## Not run:
data(PAM)
range <- lets.rangesize(x = PAM, units = "cell")
field <- lets.field(PAM, range, PAM$S, weight = TRUE)
## End(Not run)
Fits a grid into a PresenceAbsence object
Description
This function creates a grid in shapefile format and adds its cells' IDs to the presence-absence matrix. The function was created to facilitate the use of the PresenceAbsence object for the ones who prefer to work with a grid in shapefile format.
Usage
lets.gridirizer(x)
Arguments
x |
A |
Value
The result is a list of two objects. The first is a grid in shapefile format; the second is a presence-absence matrix with an aditional column called SP_ID (shapefile cell identifier).
Author(s)
Bruno Vilela
See Also
Examples
## Not run:
data(PAM)
PAM.grid <- lets.gridirizer(PAM)
names(PAM.grid)
# Grid in polygon format (can be saved in shapefile)
PAM.grid$Grid
# Presence-absence matrix (beggining only)
head(PAM.grid$Presence[, 1:5])
## End(Not run)
Download species' information from the IUCN RedList online database (No longer supported)
Description
Get species' information from the IUCN website(https://www.iucnredlist.org/) for one or more species.
Usage
lets.iucn(input, count = FALSE)
Arguments
input |
Character vector with one or more species names,
or an object of class |
count |
Logical, if |
Details
Note that you must be connected to the internet to use this function.
Value
Returns a data frame with the Species Name, Family, Conservation Status, Criteria used to estabilish the conservation status, Population Status, Year of Description (only for animals), and the Countries where it occurs. If species do not have information (i.e. have not been evaluated), the result is: NE (Not evaluated).
Author(s)
Bruno Vilela
See Also
Examples
## Not run:
# Single species
lets.iucn("Pongo pygmaeus")
# Multiple species
sp <- c("Musonycteris harrisoni", "Ailuropoda melanoleuca",
"Cebus flavius")
lets.iucn(sp)
## End(Not run)
Download species' habitat information from the IUCN RedList online database (No longer supported)
Description
Get species' habitat information from the IUCN RedList website(https://www.iucnredlist.org/) for one or more species.
Usage
lets.iucn.ha(input, count = FALSE)
Arguments
input |
Character vector with one or more species names,
or an object of the |
count |
Logical, if |
Details
Note that you must be connected to the internet to use this function.
Value
A data frame with species names in the first column and the habitats where it occurs in the remaining columns, '1' if species is present in that habitat and '0' otherwise.
Author(s)
Bruno Vilela
See Also
Examples
## Not run:
# Single species
lets.iucn.ha("Pongo pygmaeus")
# Multiple species
sp <- c("Musonycteris harrisoni", "Ailuropoda melanoleuca",
"Cebus flavius")
lets.iucn.ha(sp)
## End(Not run)
Download species' temporal trend in conservation status from the IUCN RedList online database (No longer supported)
Description
Get species conservation status over time (i.e. from 1980 to the present date available) from the IUCN website(https://www.iucnredlist.org/) for one or more species.
Usage
lets.iucn.his(input, count = FALSE)
Arguments
input |
character vector with one or more species names,
or an object of class |
count |
Logical, if |
Details
Note that you must be connected to the internet to use this function.
Value
A data frame with the species names in the first column rows and the years (1980 - present) in the remaining columns, the code represents the species' conservation status (see the IUCN RedList website for details). If species do not have information (i.e. have not been evaluated), the result is: NE (Not evaluated).
Codes and categories:
EX: Extinct
EW: Extinct in the Wild
VU: Vulnerable
EN: Endangered
CR: Critically Endangered
LC: Least Concern
NT: Near Threatened
DD: Data Deficient
CT: Commercially Threatened
IN: Indeterminate
IK: Insufficiently Known
LR: Lower Risk
RA: Rare
Author(s)
Bruno Vilela
See Also
Examples
## Not run:
# Single species
lets.iucn.his("Panthera onca")
# Multiple species
sp <- c("Rhincodon typus", "Ailuropoda melanoleuca")
lets.iucn.his(sp)
## End(Not run)
Transform IUCN RedList conservation status to continuous values
Description
Transform IUCN RedList conservation status to continuous values ranging from 0 to 5.
Usage
lets.iucncont(x, dd = NA, ne = NA)
Arguments
x |
A vector or a matrix containing IUCN codes to be transformed. |
dd |
The value to be attributed to DD (data-deficient) species, the default option is NA. |
ne |
The value to be attributed to NE (not-evaluated) species, the default option is NA. |
Value
Returns a vector/matrix with continuos values from 0 to 5.
EX and EW = 5
CR = 4
EN = 3
VU = 2
NT = 1
LC = 0
DD = NA
NE = NA
Author(s)
Bruno Vilela
References
Purvis A et al., 2000. Predicting extinction risk in declining species. Proceedings of the Royal Society of London. Series B: Biological Sciences, 267.1456: 1947-1952.
See Also
Examples
## Not run:
#Vector transformation
status <- sample(c("EN","VU", "NT", "CR", "DD", "LC", "EX"),
30, replace = TRUE)
transV <- lets.iucncont(status)
#matrix transformation
data(IUCN)
transM <- lets.iucncont(IUCN)
## End(Not run)
Load a PresenceAbsence object
Description
Reload PresenceAbsence objects written with the function
lets.save.
Usage
lets.load(file)
Arguments
file |
a character string giving the name of the file to load. |
Author(s)
Bruno Vilela
See Also
Examples
## Not run:
data(PAM)
lets.save(PAM, file = "PAM.RData")
PAM <- lets.load(file = "PAM.RData")
## End(Not run)
Create a matrix summarizing species' attributes within cells of a PresenceAbsence object
Description
Summarize species atributes per cell in a presence-absence matrix.
Usage
lets.maplizer(x, y, z, func = mean, ras = FALSE)
Arguments
x |
A |
y |
Species attribute to be considered. It must be a numeric attribute. |
z |
Species names in the same order as the attributes and exactly the
same as named in the |
func |
A function to summarize the species' atribute in each cell (the function must return only one value). |
ras |
If |
Value
The result can be both a matrix or a list cointaining
the follow objects:
Matrix: a matrix object with the cells' geographic
coordinates and the summarized species' attributes within them.
Raster: The summarized species'attributed maped in a
SpatRaster object.
Author(s)
Bruno Vilela
See Also
Examples
## Not run:
data(PAM)
data(IUCN)
trait <- IUCN$Description_Year
resu <- lets.maplizer(PAM, trait, PAM$S, ras = TRUE)
head(resu$Matrix)
plot(resu$Raster, xlab = "Longitude", ylab = "Latitude",
main = "Mean description year per site")
## End(Not run)
Compute the midpoint of species' geographic ranges
Description
Calculate species distribution midpoint from a presence-absence matrix using several methods.
Usage
lets.midpoint(pam, planar = FALSE, method = "PC", inside = FALSE)
Arguments
pam |
A presence-absence |
planar |
Logical, if |
method |
Default option, "PC" (polygon centroid) will generate a polygon
from the raster, and calculate the centroid of this polygon based on the
function |
inside |
logical. If TRUE the points returned are guaranteed to be inside the polygons or on the lines, but they are not the true centroids. True centroids may be outside a polygon, for example when a polygon is "bean shaped", and they are unlikely to be on their line |
Value
A data.frame containing the species' names and geographic
coordinates (longitude [x], latitude [y]) of species' midpoints.
Author(s)
Fabricio Villalobos & Bruno Vilela
See Also
Examples
## Not run:
data(PAM)
mid <- lets.midpoint(PAM, method = "PC")
mid2 <- lets.midpoint(PAM, method = "GM")
mid3 <- lets.midpoint(PAM, method = "CMD")
mid4 <- lets.midpoint(PAM, method = "MCC")
mid5 <- lets.midpoint(PAM, method = "PC", planar = TRUE)
mid6 <- lets.midpoint(PAM, method = "GM", planar = TRUE)
mid7 <- lets.midpoint(PAM, method = "CMD", planar = TRUE)
mid8 <- lets.midpoint(PAM, method = "MCC", planar = TRUE)
for (sp in seq_len(nrow(mid))) {
#sp = 4 # Or choose a line or species
plot(PAM, name = mid[sp, 1])
points(mid[sp, -1], col = adjustcolor("blue", .8), pch = 20, cex = 1.5)
points(mid2[sp, -1], col = adjustcolor("green", .8), pch = 20, cex = 1.5)
points(mid3[sp, -1], col = adjustcolor("yellow", .8), pch = 20, cex = 1.5)
points(mid4[sp, -1], col = adjustcolor("purple", .8), pch = 20, cex = 1.5)
points(mid5[sp, -1], col = adjustcolor("orange", .8), pch = 20, cex = 1.5)
points(mid6[sp, -1], col = adjustcolor("black", .8), pch = 20, cex = 1.5)
points(mid7[sp, -1], col = adjustcolor("gray", .8), pch = 20, cex = 1.5)
points(mid8[sp, -1], col = adjustcolor("brown", .8), pch = 20, cex = 1.5)
Sys.sleep(1)
}
## End(Not run)
Compute pairwise species' geographic overlaps
Description
Creates a species geographic overlap matrix from a Presence-absence matrix.
Usage
lets.overlap(pam, method = "Chesser&Zink", xy = NULL)
Arguments
pam |
A presence-absence matrix (sites in rows and species in columns,
with the first two columns containing the longitudinal and latitudinal
coordinates, respectively), or an object of class
|
method |
The method used to calculate the overlap matrix. "Chesser&Zink" calculates the degree of overlap as the proportion of the smaller range that overlaps within the larger range (Chesser & Zink 1994). "Proportional" calculates the proportion of a range that overlaps another range, the resultant matrix is not symmetric. "Cells" will show the number of overlapping grid cells between a pair of species' ranges (same for both species in a pair), here the resultant matrix is symmetric. |
xy |
Logical, if |
Author(s)
Fabricio Villalobos & Bruno Vilela
References
Chesser, R. Terry, and Robert M. Zink. "Modes of speciation in birds: a test of Lynch's method." Evolution (1994): 490-497.
Barraclough, Timothy G., and Alfried P. Vogler. "Detecting the geographical pattern of speciation from species-level phylogenies." The American Naturalist 155.4 (2000): 419-434.
See Also
Examples
## Not run:
data(PAM)
CZ <- lets.overlap(PAM, method = "Chesser&Zink")
prop <- lets.overlap(PAM, method = "Proportional")
cells <- lets.overlap(PAM, method = "Cells")
## End(Not run)
Crop a PresenceAbsence object based on an input shapefile
Description
Crop a PresenceAbsence object based on a shapefile provided by the user.
Usage
lets.pamcrop(x, shp, remove.sp = TRUE)
Arguments
x |
A |
shp |
Object of class SpatVector (see function
|
remove.sp |
Logical, if |
Value
The result is an object of class PresenceAbsence croped.
Author(s)
Bruno Vilela
See Also
Examples
## Not run:
data(PAM)
data("wrld_simpl")
# PAM before crop
plot(PAM, xlab = "Longitude", ylab = "Latitude",
main = "Phyllomedusa species richness")
# Crop PAM to Brazil
data(wrld_simpl) # World map
Brazil <- wrld_simpl[wrld_simpl$NAME == "Brazil", ] # Brazil (polygon)
PAM_crop <- lets.pamcrop(PAM, Brazil, remove.sp = TRUE)
plot(PAM_crop, xlab = "Longitude", ylab = "Latitude",
main = "Phyllomedusa species richness (Brazil crop)")
plot(sf::st_geometry(wrld_simpl), add = TRUE)
## End(Not run)
Create a presence-absence matrix of species' geographic ranges within a grid
Description
Convert species' ranges (in shapefile format) into a presence-absence matrix based on a user-defined grid system
Usage
lets.presab(
shapes,
xmn = NULL,
xmx = NULL,
ymn = NULL,
ymx = NULL,
resol = NULL,
remove.cells = TRUE,
remove.sp = TRUE,
show.matrix = FALSE,
crs = "+proj=longlat +datum=WGS84",
crs.grid = crs,
cover = 0,
presence = NULL,
origin = NULL,
seasonal = NULL,
count = FALSE
)
Arguments
shapes |
Object of class |
xmn |
Minimun longitude used to construct the grid in which the matrix will be based (i.e. the [gridded] geographic domain of interest). If NULL, limits will be calculated based on the limits of the shapes object. |
xmx |
Maximun longitude used to construct the grid in which the matrix will be based (i.e. the [gridded] geographic domain of interest). If NULL, limits will be calculated based on the limits of the shapes object. |
ymn |
Minimun latitude used to construct the grid in which the matrix will be based (i.e. the [gridded] geographic domain of interest). If NULL, limits will be calculated based on the limits of the shapes object. |
ymx |
Maximun latitude used to construct the grid in which the matrix will be based (i.e. the [gridded] geographic domain of interest). If NULL, limits will be calculated based on the limits of the shapes object. |
resol |
Numeric vector of length 1 or 2 to set the grid resolution. If NULL, resolution will be equivalent to 1 degree of latitude and longitude. |
remove.cells |
Logical, if |
remove.sp |
Logical, if |
show.matrix |
Logical, if |
crs |
Character representing the PROJ.4 type description of a Coordinate Reference System (map projection) of the polygons. |
crs.grid |
Character representing the PROJ.4 type description of a Coordinate Reference System (map projection) for the grid. Note that when you change this options you may probably change the extent coordinates and the resolution. |
cover |
Percentage of the cell covered by the shapefile that will be considered for presence (values between 0 and 1). |
presence |
A vector with the code numbers for the presence type to be considered in the process (for IUCN spatial data https://www.iucnredlist.org/resources/spatial-data-download, see metadata). |
origin |
A vector with the code numbers for the origin type to be considered in the process (for IUCN spatial data). |
seasonal |
A vector with the code numbers for the seasonal type to be considered in the process (for IUCN spatial data). |
count |
Logical, if |
Details
The function creates the presence-absence matrix based on a raster
object. Depending on the cell size, extension used and number of species it
may require a lot of memory, and may take some time to process it. Thus,
during the process, if count argument is set TRUE, a counting
window will open so you can see the progress (i.e. in what polygon/shapefile
the function is working). Note that the number of polygons is not the same
as the number of species that you have (i.e. a species may have more than
one polygon/shapefiles).
Value
The result is a list object of class PresenceAbsence
with the following objects: Presence-Absence Matrix: A matrix of
species' presence(1) and absence(0) information. The first two columns
contain the longitude (x) and latitude (y) of the cells' centroid (from the
gridded domain used); Richness Raster: A raster containing species
richness data; Species name: A character vector with species' names
contained in the matrix.
*But see the optional argument show.matrix.
Author(s)
Bruno Vilela & Fabricio Villalobos
See Also
Examples
## Not run:
# Spatial distribution polygons of south american frogs
# of genus Phyllomedusa.
data(Phyllomedusa)
PAM <- lets.presab(Phyllomedusa)
summary(PAM)
# Species richness map
plot(PAM, xlab = "Longitude", ylab = "Latitude",
main = "Phyllomedusa species richness")
# Map of the specific species
plot(PAM, name = "Phyllomedusa nordestina")
## End(Not run)
Create a presence-absence matrix of species' geographic ranges within a grid for the Birdlife spatial data
Description
Convert species' ranges (in shapefile format and stored in particular folders) into a presence-absence matrix based on a user-defined grid. This function is specially designed to work with BirdLife Intl. shapefiles (https://www.birdlife.org). (Notice that new versions of birds spatial data are in a similar format to other groups and should be run using the lets.presab function. We will keep this function in case someone needs to use on the previous data format.)
Usage
lets.presab.birds(
path,
xmn = NULL,
xmx = NULL,
ymn = NULL,
ymx = NULL,
resol = NULL,
remove.cells = TRUE,
remove.sp = TRUE,
show.matrix = FALSE,
crs = "+proj=longlat +datum=WGS84",
crs.grid = crs,
cover = 0,
presence = NULL,
origin = NULL,
seasonal = NULL,
count = FALSE
)
Arguments
path |
Path location of folders with one or more species' individual
shapefiles. Shapefiles with more than one species will not work on this
function. To use multi-species shapefiles see |
xmn |
Minimun longitude used to construct the grid in which the matrix will be based (i.e. the [gridded] geographic domain of interest). If NULL, limits will be calculated based on the limits of the shapes object. |
xmx |
Maximun longitude used to construct the grid in which the matrix will be based (i.e. the [gridded] geographic domain of interest). If NULL, limits will be calculated based on the limits of the shapes object. |
ymn |
Minimun latitude used to construct the grid in which the matrix will be based (i.e. the [gridded] geographic domain of interest). If NULL, limits will be calculated based on the limits of the shapes object. |
ymx |
Maximun latitude used to construct the grid in which the matrix will be based (i.e. the [gridded] geographic domain of interest). If NULL, limits will be calculated based on the limits of the shapes object. |
resol |
Numeric vector of length 1 or 2 to set the grid resolution. If NULL, resolution will be equivalent to 1 degree of latitude and longitude. |
remove.cells |
Logical, if |
remove.sp |
Logical, if |
show.matrix |
Logical, if |
crs |
Character representing the PROJ.4 type description of a Coordinate Reference System (map projection) of the polygons. |
crs.grid |
Character representing the PROJ.4 type description of a Coordinate Reference System (map projection) for the grid. Note that when you change this options you may probably change the extent coordinates and the resolution. |
cover |
Percentage of the cell covered by the shapefile that will be considered for presence (values between 0 and 1). |
presence |
A vector with the code numbers for the presence type to be considered in the process (for IUCN spatial data https://www.iucnredlist.org/resources/spatial-data-download, see metadata). |
origin |
A vector with the code numbers for the origin type to be considered in the process (for IUCN spatial data). |
seasonal |
A vector with the code numbers for the seasonal type to be considered in the process (for IUCN spatial data). |
count |
Logical, if |
Details
The function creates the presence-absence matrix based on a raster
file. Depending on the cell size, extension used and number of species it
may require a lot of memory, and may take some time to process it. Thus,
during the process, if count argument is set TRUE, a counting
window will open so you can see the progress (i.e. in what polygon the
function is working). Note that the number of polygons is not the same as
the number of species that you have (i.e. a species may have more than one
polygon/shapefiles).
Value
The result is a list object of class PresenceAbsence
with the following objects: Presence-Absence Matrix: A matrix of
species' presence(1) and absence(0) information. The first two columns
contain the longitude (x) and latitude (y) of the cells' centroid (from the
gridded domain used); Richness Raster: A raster containing species
richness data; Species name: A character vector with species' names
contained in the matrix.
*But see the optional argument show.matrix.
Author(s)
Bruno Vilela & Fabricio Villalobos
See Also
Examples
## Not run:
# Constructing a Presence/Absence matrix for birds
# Attention: For your own files, omit the 'system.file'
# and 'package="letsR"', these are just to get the path
# to files installed with the package.
path.Ramphastos <- system.file("extdata", package = "letsR")
PAM <- lets.presab.birds(path.Ramphastos, xmn = -93, xmx = -29,
ymn = -57, ymx = 25)
# Species richness map
plot(PAM, xlab = "Longitude", ylab = "Latitude",
main = "Ramphastos species Richness")
## End(Not run)
Create a presence-absence matrix of species' geographic ranges within a user's grid shapefile (beta version)
Description
Convert species' ranges (in shapefile format) into a presence-absence matrix based on a grid in shapefile format.
Usage
lets.presab.grid(
shapes,
grid,
sample.unit,
remove.sp = TRUE,
presence = NULL,
origin = NULL,
seasonal = NULL
)
Arguments
shapes |
Object of class |
grid |
Object of class shapefile representing the spatial grid (e.g. regular/irregular cells, political divisions, hexagonal grids, etc). The grid and the shapefiles must be in the same projection. |
sample.unit |
Object of class |
remove.sp |
Logical, if |
presence |
A vector with the code numbers for the presence type to be considered in the process (for IUCN spatial data https://www.iucnredlist.org/resources/spatial-data-download, see metadata). |
origin |
A vector with the code numbers for the origin type to be considered in the process (for IUCN spatial data). |
seasonal |
A vector with the code numbers for the seasonal type to be considered in the process (for IUCN spatial data). |
Details
This function is an alternative way to create a presence absence matrix when users already have their own grid.
Value
The result is a list containing two objects:
(I) A matrix the species presence (1) and absence (0) values per sample unity.
(II) The original grid.
Author(s)
Bruno Vilela & Fabricio Villalobos
See Also
Examples
## Not run:
# Species polygons
data("Phyllomedusa")
data("wrld_simpl")
# Grid
sp.r <- terra::as.polygons(terra::rast(resol = 5,
crs = terra::crs(Phyllomedusa),
xmin = -93, xmax = -29, ymin = -57, ymax = 15))
sp.r$ID <- 1:length(sp.r)
# PAM
resu <- lets.presab.grid(Phyllomedusa, sp.r, "ID")
# Plot
rich_plus1 <- rowSums(resu$PAM[, -1]) + 1
colfunc <- colorRampPalette(c("#fff5f0", "#fb6a4a", "#67000d"))
colors <- c("white", colfunc(max(rich_plus1)))
plot(resu$grid, border = "gray40",
col = colors[rich_plus1])
plot(sf::st_geometry(wrld_simpl), add = TRUE)
## End(Not run)
Create a presence-absence matrix based on species' point occurrences
Description
Convert species' occurrences into a presence-absence matrix based on a user-defined grid.
Usage
lets.presab.points(
xy,
species,
xmn = NULL,
xmx = NULL,
ymn = NULL,
ymx = NULL,
resol = NULL,
remove.cells = TRUE,
remove.sp = TRUE,
show.matrix = FALSE,
crs = "+proj=longlat +datum=WGS84",
count = FALSE
)
Arguments
xy |
A matrix with geographic coordinates of species occurrences, first column is the longitude (or x), and the second latitude (or y). |
species |
Character vector with species names, in the same order as the coordinates. |
xmn |
Minimun longitude used to construct the grid in which the matrix will be based (i.e. the [gridded] geographic domain of interest). If NULL, limits will be calculated based on the limits of the shapes object. |
xmx |
Maximun longitude used to construct the grid in which the matrix will be based (i.e. the [gridded] geographic domain of interest). If NULL, limits will be calculated based on the limits of the shapes object. |
ymn |
Minimun latitude used to construct the grid in which the matrix will be based (i.e. the [gridded] geographic domain of interest). If NULL, limits will be calculated based on the limits of the shapes object. |
ymx |
Maximun latitude used to construct the grid in which the matrix will be based (i.e. the [gridded] geographic domain of interest). If NULL, limits will be calculated based on the limits of the shapes object. |
resol |
Numeric vector of length 1 or 2 to set the grid resolution. If NULL, resolution will be equivalent to 1 degree of latitude and longitude. |
remove.cells |
Logical, if |
remove.sp |
Logical, if |
show.matrix |
Logical, if |
crs |
Character representing the PROJ.4 type description of a Coordinate Reference System (map projection) of the polygons. |
count |
Logical, if |
Details
The function creates the presence-absence matrix based on a raster
file. Depending on the cell size, extension used and number of species it
may require a lot of memory, and may take some time to process it. Thus,
during the process, if count argument is set TRUE, a counting
window will open so you can see the progress (i.e. in what polygon the
function is working). Note that the number of polygons is not the same as
the number of species that you have (i.e. a species may have more than one
polygon/shapefiles).
Value
The result is a list object of class PresenceAbsence
with the following objects: Presence-Absence Matrix: A matrix of
species' presence(1) and absence(0) information. The first two columns
contain the longitude (x) and latitude (y) of the cells' centroid (from the
gridded domain used); Richness Raster: A raster containing species
richness data; Species name: A character vector with species' names
contained in the matrix.
*But see the optional argument show.matrix.
Author(s)
Bruno Vilela & Fabricio Villalobos
See Also
Examples
## Not run:
species <- c(rep("sp1", 100), rep("sp2", 100),
rep("sp3", 100), rep("sp4", 100))
x <- runif(400, min = -69, max = -51)
y <- runif(400, min = -23, max = -4)
xy <- cbind(x, y)
PAM <- lets.presab.points(xy, species, xmn = -93, xmx = -29,
ymn = -57, ymx = 15)
summary(PAM)
# Species richness map
plot(PAM, xlab = "Longitude", ylab = "Latitude",
main = "Species richness map (simulated)")
# Map of the specific species
plot(PAM, name = "sp1")
## End(Not run)
Compute species' geographic range sizes
Description
This function calculates species' range sizes from a PresenceAbsence object or directly from the species' shapefiles.
Usage
lets.rangesize(
x,
species_name = NULL,
coordinates = "geographic",
units = "cell"
)
Arguments
x |
A |
species_name |
Species names in the same order as in the
|
coordinates |
"geographical" or "planar". Indicate whether the shapefile
has geographical or planar coordinates(only needed if x is a
|
units |
"cell" or "squaremeter". Indicate if the size units wanted are
in number of cells occupied or in square meters(only needed if x is a
|
Value
The result is a matrix with the range size of each species. If the range size accounts for the earth curvature (Yes or No) or its size unit may differ for each argument combination:
1) SpatVector & geographical = Square meters. Yes.
2) SpatVector & planar = Square meters. No.
3) PresenceAbsence & cell = number of cells. No.
4) PresenceAbsence & squaremeter = Square meters. Yes.
Author(s)
Bruno Vilela
Examples
## Not run:
# SpatialPolygonsDataFrame & geographical
data(Phyllomedusa)
rangesize <- lets.rangesize(x = Phyllomedusa,
coordinates = "geographic")
# SpatialPolygonsDataFrame & planar
rangesize2 <- lets.rangesize(x = Phyllomedusa,
coordinates = "planar")
# PresenceAbsence & cell
data(PAM)
rangesize3 <- lets.rangesize(x = PAM,
units = "cell")
# PresenceAbsence & squaremeter
rangesize4 <- lets.rangesize(x = PAM,
units = "squaremeter")
## End(Not run)
Save a PresenceAbsence object
Description
Save an external representation of a PresenceAbsence object to
the specified file. The object can be read back from the file at a later
date by using the function lets.load.
Usage
lets.save(pam, ...)
Arguments
pam |
A PresenceAbsence object. |
... |
other arguments passed to the function |
Author(s)
Bruno Vilela
See Also
Examples
## Not run:
data(PAM)
lets.save(PAM, file = "PAM.RData")
PAM <- lets.load(file = "PAM.RData")
## End(Not run)
Filter species' shapefiles based on its presence, origin, and season
Description
Filter species shapefiles by origin, presence, and seasonal type (following IUCN types: https://www.iucnredlist.org/resources/spatial-data-download, see metadata).
Usage
lets.shFilter(shapes, presence = NULL, origin = NULL, seasonal = NULL)
Arguments
shapes |
Object of class |
presence |
A vector with the code numbers for the presence type to be considered in the process (for IUCN spatial data https://www.iucnredlist.org/resources/spatial-data-download, see metadata). |
origin |
A vector with the code numbers for the origin type to be considered in the process (for IUCN spatial data). |
seasonal |
A vector with the code numbers for the seasonal type to be considered in the process (for IUCN spatial data). |
Details
Presence codes: (1) Extant, (2) Probably Extant, (3) Possibly Extant, (4) Possibly Extinct, (5) Extinct (post 1500) & (6) Presence Uncertain.
Origin codes: (1) Native, (2) Reintroduced, (3) Introduced, (4) Vagrant & (5) Origin Uncertain.
Seasonal codes: (1) Resident, (2) Breeding Season, (3) Non-breeding Season, (4) Passage & (5) Seasonal Occurrence Uncertain.
More info in the shapefiles' metadata.
Value
The result is the shapefile(s) filtered according to the selected types. If the filters remove all polygons, the result will be NULL.
Author(s)
Bruno Vilela
See Also
Subset a PresenceAbsence object based on species names
Description
Subset a PresenceAbsence object based on species character vector provided by the user.
Usage
lets.subsetPAM(x, names, remove.cells = TRUE)
Arguments
x |
A |
names |
Character vector with species names to subset the |
remove.cells |
Logical, if |
Value
The result is an object of class PresenceAbsence subseted.
Author(s)
Bruno Vilela
See Also
Examples
## Not run:
data(PAM)
# PAM before subset
plot(PAM, xlab = "Longitude", ylab = "Latitude",
main = "Phyllomedusa species richness")
# Subset PAM to the first 20 species
PAMsub <- lets.subsetPAM(PAM, PAM[[3]][1:20])
plot(PAMsub, xlab = "Longitude", ylab = "Latitude",
main = "Phyllomedusa species richness")
## End(Not run)
Summarize variable(s) values in a presence-absence matrix within species' ranges
Description
Based on a Presence-Absence matrix with added variables
(see lets.addvar), this function summarizes the values of
such variable(s) per species (across the species' occupied cells. i.e.
within their ranges).
Usage
lets.summarizer(x, pos, xy = TRUE, fun = mean, ...)
Arguments
x |
Presence-absence matrix with variables added. |
pos |
Column position of the variables of interest. |
xy |
Logical, if |
fun |
Function to be used to summarize the variable per species.
Default is |
... |
Other parameters passed to the function defined in |
Author(s)
Bruno Vilela & Fabricio Villalobos
References
Villalobos, F. and Arita, H.T. 2010. The diversity field of New World leaf-nosed bats (Phyllostomidae). Global Ecology and Biogeography. 19, 200-211.
See Also
Examples
## Not run:
data(PAM)
data(temp)
temp <- terra::unwrap(temp)
pamvar <- lets.addvar(PAM, temp)
resu <- lets.summarizer(x = pamvar, pos = ncol(pamvar),
xy = TRUE)
## End(Not run)
Transform values of a vector
Description
Transform each element of a vector.
Usage
lets.transf(x, y, z, NUMERIC = TRUE)
Arguments
x |
A vector to be transformed. |
y |
levels to be transformed. |
z |
The value to be atributed to each level (same order as y). |
NUMERIC |
logical, if |
Value
Return a vector with changed values.
Author(s)
Bruno Vilela
Examples
## Not run:
status <- sample(c("EN","VU", "NT", "CR", "DD", "LC"), 30, replace=TRUE)
TE <- "Threatened"
NT <- "Non-Threatened"
new <- c(TE, TE, NT, TE, "Data Deficient", NT)
old <- c("EN","VU", "NT", "CR", "DD", "LC")
statustrans <- lets.transf(status, old, new, NUMERIC=FALSE)
## End(Not run)
Plot an object of class PresenceAbsence
Description
Plots species richness map from an object of class PresenceAbsence or a particular species' map.
Usage
## S3 method for class 'PresenceAbsence'
plot(x, name = NULL, world = TRUE, col_rich = NULL, col_name = "red", ...)
Arguments
x |
An object of class |
name |
A character specifying a species to be ploted instead of the complete species richness map. |
world |
If |
col_rich |
Color function (e.g. |
col_name |
The color to use when ploting single species. |
... |
Other parameters pass to the plot function. |
Author(s)
Bruno Vilela
See Also
Examples
## Not run:
data(PAM)
plot(PAM)
plot(PAM, xlab = "Longitude", ylab = "Latitude",
main = "Phyllomedusa species richness")
plot(PAM, name = "Phyllomedusa atelopoides")
plot(PAM, name = "Phyllomedusa azurea")
## End(Not run)
Print for object of class PresenceAbsence
Description
Print for objects of class PresenceAbsence.
Usage
## S3 method for class 'PresenceAbsence'
print(x, ...)
Arguments
x |
an object of class |
... |
Other print parameters. |
Author(s)
Bruno Vilela
Print summary for object of class PresenceAbsence
Description
Print summary for objects of class PresenceAbsence.
Usage
## S3 method for class 'PresenceAbsence'
print.summary(x, ...)
Arguments
x |
an object of class |
... |
Other print parameters. |
Author(s)
Bruno Vilela
Summary for object of class PresenceAbsence
Description
Summary for objects of class PresenceAbsence.
Usage
## S3 method for class 'PresenceAbsence'
summary(object, ...)
Arguments
object |
an object of class |
... |
additional arguments affecting the summary produced. |
Author(s)
Bruno Vilela
Avarege temperature raster for the world.
Description
Average temperature raster in Celsius degrees(multiplied by 100) for the world in 10 arc min of resolution. Data was modfied from WorldClim (https://worldclim.com/, downloaded in 05/2014).
Usage
data(temp)
Source
Hijmans, R.J., S.E. Cameron, J.L. Parra, P.G. Jones and A. Jarvis, 2005. Very high resolution interpolated climate surfaces for global land areas. International Journal of Climatology 25: 1965-1978.
Simplified world country polygons
Description
Shapefile in sf format. The object was obtained from maptools package and converted to sf.
Usage
data(temp)
Source
Originally “https://mappinghacks.com/data/TM_WORLD_BORDERS_SIMPL-0.2.zip”, now available from https://github.com/nasa/World-Wind-Java/tree/master/WorldWind/testData/shapefiles