Movatterモバイル変換

Type:	Package
Title:	Species Distribution Models as a Function of Biotic, Abiotic andMovement Factors (BAM)
Version:	0.5.0
Maintainer:	Luis Osorio-Olvera <luismurao@gmail.com>
Description:	Species Distribution Modeling (SDM) is a practical methodology that aims to estimate the area of distribution of a species. However, most of the work has focused on estimating static expressions of the correlation between environmental variables. The outputs of correlative species distribution models can be interpreted as maps of the suitable environment for a species but not generally as maps of its actual distribution. Soberón and Peterson (2005) <doi:10.17161/bi.v2i0.4> presented the BAM scheme, a heuristic framework that states that the occupied area of a species occurs on sites that have been accessible through dispersal (M) and have both favorable biotic (B) and abiotic conditions (A). The 'bamm' package implements classes and functions to operate on each element of the BAM and by using a cellular automata model where the occupied area of a species at time t is estimated by the multiplication of three binary matrices: one matrix represents movements (M), another abiotic -niche- tolerances (A), and a third, biotic interactions (B). The theoretical background of the package can be found in Soberón and Osorio-Olvera (2023) <doi:10.1111/jbi.14587>.
License:	GPL (≥ 3)
URL:	https://luismurao.github.io/bamm/
BugReports:	https://github.com/luismurao/bamm/issues
Depends:	R (≥ 3.5.0)
Imports:	animation (≥ 2.3), crosstalk, dplyr (≥ 0.8.0), furrr (≥0.1.0), future (≥ 1.18.0), graphics, grDevices, igraph (≥1.2), leaflet (≥ 2.0), magrittr (≥ 1.2), Matrix (≥ 1.2.14),methods (≥ 3.3), plotly, purrr (≥ 0.2), raster (≥ 3.4-13),Rcpp (≥ 0.12.18), Rdpack (≥ 0.11.0), RSpectra (≥ 0.13.1), sp(≥ 1.3.0), stats, utils
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
LinkingTo:	Rcpp, RcppArmadillo
VignetteBuilder:	knitr
RdMacros:	Rdpack
Config/testthat/edition:	3
Encoding:	UTF-8
NeedsCompilation:	yes
RoxygenNote:	7.3.1
SystemRequirements:	GDAL (>= 2.2.3): gdal-bin (deb), libgdal-dev (deb)or gdal-devel (rmp), GEOS (>= 3.4.0), PROJ (>= 4.9.3):libproj-dev (deb), sqlite3, ImageMagick++: imagemagick (deb),libmagic-dev (deb), libmagick++-dev (deb) orImageMagick-c++-devel (rpm) ImageMagick(http://imagemagick.org) or GraphicsMagick(http://www.graphicsmagick.org) or LyX (http://www.lyx.org) forsaveGIF(); (PDF)LaTeX for saveLatex(); SWF Tools(http://swftools.org) for saveSWF(); FFmpeg (http://ffmpeg.org)or avconv (https://libav.org/avconv.html) for saveVideo()
Packaged:	2024-07-06 19:28:23 UTC; luis.osorio
Author:	Luis Osorio-Olvera [aut, cre], Jorge Soberón [aut], Rusby G. Contreras-Díaz [ctb]
Repository:	CRAN
Date/Publication:	2024-07-06 20:22:11 UTC

adj_mat: Function to compute the adjacency matrix of an area.

Description

Creates an adjacency matrix of an area of interest.This could be the accessible area (M) of a species or any geographicregion of interest.

Usage

adj_mat(modelsparse, ngbs = 1, eigen_sys = FALSE, which_eigs = 1)

Arguments

Details

The model is a raster object of the area where the dispersalprocess will occur.The number of neighbors depends on the dispersal abilities of the speciesand the spatial resolution of the niche model; for example, a species'swith big dispersal abilities will move throughout more than 1 km^2 per day,so the idea is to give an approximate number of moving neighbors (pixels)per unit of time.For more information about see adjacency matrices in the context ofthe theory of area of distribution (Soberon and Osorio-Olvera, 2022).

Value

Returns an object of classsetM with 7 slots.The first contains the adjacency matrix. A n x n sparse matrix (n=number ofnon-NA cells of the niche model) where connected cells are represented by 1.The second slot has the adjacency list. It is a list of matrices with fourcolumns (FromRasCell -from cell ID of the raster-, -to cell ID of theraster-, -from non-NA cell-, -to non-NA cell-). Other slots containinformation about initial coordinates where dispersal occurs(initial_points), number of cells used to define the neighborhood (ngbs),non-NA coordinates (coordinates), and a matrix of eigen vectors (eigen_vec).

Author(s)

Luis Osorio-Olvera & Jorge Soberón

References

Soberón J, Osorio-Olvera L (2023).“A dynamic theory of the area of distribution.”Journal of Biogeography6,50, 1037-1048.doi:10.1111/jbi.14587,https://onlinelibrary.wiley.com/doi/abs/10.1111/jbi.14587..

Examples

x_coord <- c(-106.5699, -111.3737,-113.9332,             -110.8913, -106.4262, -106.5699)y_coord <- c(16.62661, 17.72373, 19.87618,             22.50763, 21.37728, 16.62661)xy <- cbind(x_coord, y_coord)p <- sp::Polygon(xy)ps <- sp::Polygons(list(p),1)sps <- sp::SpatialPolygons(list(ps))mx_grid <- bamm::shape2Grid(sps,resolution = 0.25,ones = TRUE)mx_sparse <- bamm::model2sparse(model=mx_grid, threshold = 0.1)adj_mx <- bamm::adj_mat(modelsparse=mx_sparse,                        ngbs=1,eigen_sys=TRUE,which_eigs=1)print(adj_mx)mx_grid_eigen <- mx_gridmx_grid_eigen[mx_sparse@cellIDs] <- adj_mx@eigen_vecraster::plot(mx_grid_eigen)

Classbam digram

Description

Classbam digram

Value

An object of class bam

Slots

sdm_sim

A list of sparse vectors representing the area occupied

palatable_matrices

A list of sparse vectors representing palatablesites.

sim_steps

Number of simulation stepsby the species

Author(s)

Luis Osorio-Olvera & Jorge Soberón

bam_clusters: Function to estimate the connectivity of suitable areas

Description

Function to estimate the connectivity of suitable areas givenan adjacency matrix.

Usage

bam_clusters(model, ngbs = 1, plot_model = FALSE)

Arguments

Details

The main result of the function is the Connectivity-Suitability-Diagram(CSD). In this diagram connected suitable cells make clusters of pixels.For more details about the CSD see (Soberon and Osorio-Olvera, 2022).

Value

An object of classcsd. It contains three slots.1) connections: a data.frame with three columns where first and the secondrepresent (x and y) centroid coordinates of the niche modeland the third column with the cluster ID where they belong.2) interactive_map: a leaflet map of connected suitable pixels shown inthe same color. 3) A RasterLayer of connected suitable pixels.

Author(s)

Luis Osorio-Olvera & Jorge Soberón

References

Soberón J, Osorio-Olvera L (2023).“A dynamic theory of the area of distribution.”Journal of Biogeography6,50, 1037-1048.doi:10.1111/jbi.14587,https://onlinelibrary.wiley.com/doi/abs/10.1111/jbi.14587..

Examples

set.seed(891)model_path <- system.file("extdata/Lepus_californicus_cont.tif",                          package = "bamm")model <- raster::raster(model_path)model <- model > 0.7clusterin <- bamm::bam_clusters(model,ngbs=1,plot_model=TRUE)raster::plot(clusterin@raster_map)clusterin@interactive_map

bam_sim: Simulate dispersal dynamics using the set B of the BAM framework.

Description

bam_sim: Simulate dispersal dynamics using the set B of the BAM framework.

Usage

bam_sim(  sp1,  sp2,  set_M,  initial_points,  periods_toxic,  periods_suitable,  nsteps,  progress_bar = TRUE)

Arguments

Details

The returned object inherits fromsetA,setM classes. Details about the dynamic modelcan be found in Soberon and Osorio-Olvera (2022). The model is cellularautomata where the occupied area of a species at timet+1 isestimated by the multiplication of threebinary matrices: one matrix represents movements (M), anotherabiotic -niche- tolerances (A), and a third, biotic interactions (B)(Soberon and Osorio-Olvera, 2022).

\mathbf{G}_j(t+1) =\mathbf{B}_j(t)\mathbf{A}_j(t)\mathbf{M}_j\mathbf{G}_j(t)

Value

An object of class bam. The object contains 12 slots of information(see details) from which simulation results are stored in sdm_sim object,a list of sparse matrices with results of each simulation step.

Author(s)

Luis Osorio-Olvera & Jorge Soberón

References

Soberón J, Osorio-Olvera L (2023).“A dynamic theory of the area of distribution.”Journal of Biogeography6,50, 1037-1048.doi:10.1111/jbi.14587,https://onlinelibrary.wiley.com/doi/abs/10.1111/jbi.14587..

Examples

# Compute dispersal dynamics of Urania boisduvalii as a function of# palatable Omphaleaurap <- system.file("extdata/urania_omph/urania_guanahacabibes.tif",                                  package = "bamm")ura <- raster::raster(urap)ompp <- system.file("extdata/urania_omph/omphalea_guanahacabibes.tif",                                  package = "bamm")omp <- raster::raster(ompp)msparse <- bamm::model2sparse(ura)init_coordsdf <- data.frame(x=-84.38751, y= 22.02932)initial_points <- bamm::occs2sparse(modelsparse = msparse,init_coordsdf)set_M <- bamm::adj_mat(modelsparse = msparse,ngbs = 1)ura_sim <- bamm::bam_sim(sp1=ura, sp2=omp, set_M=set_M,                         initial_points=initial_points,                         periods_toxic=5,                         periods_suitable=1,                         nsteps=40)ura_omp <- bamm::sim2Raster(ura_sim)raster::plot(ura_omp[[c(1,5,10,15,20,30,35,40)]])if(requireNamespace("animation")){# Animation exampleanp <-tempfile(pattern = "simulation_results_",fileext = ".gif")# new_sim <- bamm::sim2Animation(sdm_simul = ura_sim,#                                which_steps = seq_len(ura_sim@sim_steps),#                                fmt = "GIF",#                               filename = anp)}

bam_ssim: Simulate dispersal dynamics using the set B of the BAM framework.

Description

bam_ssim: Simulate dispersal dynamics using the set B of the BAM framework.

Usage

bam_ssim(  sp1,  sp2,  set_M,  initial_points,  periods_toxic,  periods_suitable,  dispersal_prob = 0.85,  palatable_matrices = FALSE,  nsteps,  progress_bar = TRUE)

Arguments

Details

The returned object inherits fromsetA,setM classes. Details about the dynamic modelcan be found in Soberon and Osorio-Olvera (2022).

Value

An object of class bam. The object contains 12 slots of information(see details) from which simulation results are stored in sdm_sim object,a list of sparse matrices with results of each simulation step. Palatablematrices are returned as a list of sparse matrices with information aboutpalatable pixels for each step of the simulation.

Author(s)

Luis Osorio-Olvera & Jorge Soberón

References

Soberón J, Osorio-Olvera L (2023).“A dynamic theory of the area of distribution.”Journal of Biogeography6,50, 1037-1048.doi:10.1111/jbi.14587,https://onlinelibrary.wiley.com/doi/abs/10.1111/jbi.14587..

Examples

urap <- system.file("extdata/urania_omph/urania_guanahacabibes.tif",                                  package = "bamm")ura <- raster::raster(urap)ompp <- system.file("extdata/urania_omph/omphalea_guanahacabibes.tif",                                  package = "bamm")omp <- raster::raster(ompp)msparse <- bamm::model2sparse(ura)init_coordsdf <- data.frame(x=-84.38751, y= 22.02932)initial_points <- bamm::occs2sparse(modelsparse = msparse,init_coordsdf)set_M <- bamm::adj_mat(modelsparse = msparse,ngbs = 1)ura_ssim <- bamm::bam_ssim(sp1=ura, sp2=omp, set_M=set_M,                           dispersal_prob = 0.75,                           initial_points=initial_points,                           periods_toxic=5,                           periods_suitable=1,                           nsteps=40)ura_omp <- bamm::sim2Raster(ura_ssim)raster::plot(ura_omp[[c(1,2,5,10,15,20,30,35,40)]])if(requireNamespace("animation")){# Animation exampleanp <-tempfile(pattern = "simulation_results_",fileext = ".gif")#new_sim <- bamm::sim2Animation(sdm_simul = ura_ssim,#                               which_steps = seq_len(ura_ssim@sim_steps),#                               fmt = "GIF",#                               filename = anp)}

Classbioindex

Description

Classbioindex

Value

An object of class bioindex

Slots

alpha

A matrix with the richness of species per site

omega

A matrix with the range size of every species

wBeta

A numeric value with Whittaker’s multiplicative beta index

laBeta

A numeric value with Lande’s additive beta index

leBeta

A numeric value with Legendre’s beta index

nestedness

A numeric value with Wright and Reeves' nestedness

dispersion_field

A matrix with the set of ranges of all species thatoccur in at each locality

richness_field

A matrix with the number of shared species ineach site

Author(s)

Luis Osorio-Olvera & Jorge Soberón

Classbioindex_sparse

Description

Classbioindex_sparse

Value

An object of class bioindex_sparse

Slots

alpha

A sparse matrix with the richness of species per site

omega

A sparse matrix with the range size of every species

wBeta

A numeric value with Whittaker’s multiplicative beta index

laBeta

A numeric value with Lande’s additive beta index

leBeta

A numeric value with Legendre’s beta index

nestedness

A numeric value with Wright and Reeves' nestedness

dispersion_field

A sparse matrix with the set of ranges of all speciesthat occur in at each locality

richness_field

A sparse matrix with the number of shared species ineach site

Author(s)

Luis Osorio-Olvera & Jorge Soberón

community_bam: Communitybamm

Description

Estimate community dynamics using thebamm framework

Usage

community_sim(  en_models,  ngbs_vect,  init_coords,  nsteps,  threshold_vec = NULL,  stochastic_dispersal = FALSE,  disp_prop2_suitability = TRUE,  disper_prop = 0.5)

Arguments

Details

Each element in community_sim is an object of class. For moredetails about the simulation seesdm_sim.bam.

Value

An object of class community_sim. The object contains simulationresults for each species in the community.

Author(s)

Luis Osorio-Olvera & Jorge Soberon

References

Soberón J, Osorio-Olvera L (2023).“A dynamic theory of the area of distribution.”Journal of Biogeography6,50, 1037-1048.doi:10.1111/jbi.14587,https://onlinelibrary.wiley.com/doi/abs/10.1111/jbi.14587..

Examples

lagos_path <- system.file("extdata/conejos",                          package = "bamm")enm_path <- list.files(lagos_path,                       pattern = ".tif",                       full.names = TRUE)[seq(1,10)]en_models <- raster::stack(enm_path)ngbs_vect <- sample(1:2,replace = TRUE,                    size = raster::nlayers(en_models))init_coords <- read.csv(file.path(lagos_path,                                  "lagos_initit.csv"))[seq(1,10),]nsteps <- 12sdm_comm <- bamm::community_sim(en_models = en_models,                                ngbs_vect = ngbs_vect,                                init_coords = init_coords,                                nsteps = nsteps)com_pam <- bamm::csim2pam(sdm_comm,which_steps = seq(1,nsteps))rich_pam <- pam2richness(com_pam,which_steps = c(1,5,10))raster::plot(rich_pam)

Classcommunity_sim digram

Description

Classcommunity_sim digram

Value

An object of class community_sim

Slots

community_sim

A list of sparse vectors representing the area occupiedby the species

Author(s)

Luis Osorio-Olvera & Jorge Soberón

Classcsd

Description

Classcsd

Value

An object of class csd

Slots

connections

A data.frame with four columns: x, y, clusterID andcluster_size

interactive_map

A leaflet map with markers showing the geographicalclusters

raster_map

A raster map with cluster IDs as values.

Author(s)

Luis Osorio-Olvera & Jorge Soberón

csd_estimate: Estimate the connectivity suitability and dispersal plot

Description

csd_plot gives an estimate of the number of geographic clustersgiven a set of dispersal hypothesis and a suitability raster

Usage

csd_estimate(model, dispersal_steps = c(2, 4, 8, 16, 32, 64))

Arguments

Details

For more information about the Connectivity-Suitability-Diagramseebam_clusters

Value

A list of length three. The first element contains the Connectivity-Suitability-Diagram information estimated for each element in the vectorof dispersal_steps. The second is tbl_df object with a summary of the numberof cluster of each dispersal step and the mean number of connected clusters.The last element is base plot showing the information contained inthe tbl_df object.

Author(s)

Luis Osorio-Olvera & Jorge Soberón

References

Soberón J, Osorio-Olvera L (2023).“A dynamic theory of the area of distribution.”Journal of Biogeography6,50, 1037-1048.doi:10.1111/jbi.14587,https://onlinelibrary.wiley.com/doi/abs/10.1111/jbi.14587..

Examples

model_path <- system.file("extdata/Lepus_californicus_cont.tif",                          package = "bamm")model <- raster::raster(model_path)model <- model > 0.7csd_plot <- bamm::csd_estimate(model,                         dispersal_steps=c(2,4,8))csd_plot$plot

csim2pam: Converts community simulation to a Presence Absence Matrix (PAM)

Description

Converts community simulation object into aPresence Absence Matrices (PAM) for a given simulation steps.

Usage

csim2pam(community_sim, which_steps)

Arguments

Details

For details about the object community_sim seecommunity_sim

Value

An object of classpam; it contains five slots.1) pams: a list of sparse matrices with Presence-Absence information (PAMs).2) which_steps: time steps corresponding to each PAM. 3) sp_names: avector of species names. 4) the grid area used in the simulation. 5) Non NAcell (pixel) IDs.

Author(s)

Luis Osorio-Olvera & Jorge Soberón

References

Soberón J, Osorio-Olvera L (2023).“A dynamic theory of the area of distribution.”Journal of Biogeography6,50, 1037-1048.doi:10.1111/jbi.14587,https://onlinelibrary.wiley.com/doi/abs/10.1111/jbi.14587..

Examples

lagos_path <- system.file("extdata/conejos",                          package = "bamm")enm_path <- list.files(lagos_path,                       pattern = ".tif",                       full.names = TRUE)[seq(1,10)]en_models <- raster::stack(enm_path)ngbs_vect <- sample(1:2,replace = TRUE,                    size = raster::nlayers(en_models))init_coords <- read.csv(file.path(lagos_path,                                  "lagos_initit.csv"))[seq(1,10),]nsteps <- 10sdm_comm <- bamm::community_sim(en_models = en_models,                               ngbs_vect = ngbs_vect,                               init_coords = init_coords,                               nsteps = nsteps,                               threshold = 0.1)pamt10 <- bamm::csim2pam(community_sim = sdm_comm ,                        which_steps = 10)pams <- bamm::csim2pam(community_sim = sdm_comm ,                       which_steps = seq_len(10))rich_pam <- bamm::pam2richness(pams,which_steps = c(1,5))print(rich_pam)

Classdiversity_range

Description

Classdiversity_range

Value

An object of class diversity_range

Slots

alpha

A column vector with species richness per site

omega

A column vector with the size of the area of distribution perspecies.

alpha_raster

Species richness in raster format.

dispersion_field

A matrix with the set of ranges of all species thatoccur in at each locality.

dispersion_field_raster

Raster object with the observed values ofdispersion field.

diversity_range_raster

Raster object of diversity range.

diversity_range_colors

Colors to plot endemism levels.

null_dispersion_field_dist

A matrix with dispersion field nulldistribution.

xy_coordinates

A matrix of geographical coordinates

n_iterations

Number of iterations used to estimate the dispersionfield null distribution.

nsps

Number of species in the PAM.

nsites

Number of sites in the PAM.

Author(s)

Luis Osorio-Olvera & Jorge Soberón

range_diversity_analysis: diversity analysis

Description

diversity_range_analysis biodiversity indices related todiversity-range plots

Usage

diversity_range_analysis(  pam,  xy_mat = NULL,  lower_interval = 0.05,  upper_interval = 0.95,  raster_templete = NULL,  niter = 100,  return_null_dfield = FALSE,  randal = "indep_swap",  parallel = TRUE,  n_cores = 2)

Arguments

Details

For more information about the biodiversity indicessee Soberon and Cavner (2015). For detail about the diversity range analysissee Soberon et al. (2022). To plot diversity range results useplot method for objects of classdiversity_range.

For details about randomization algorithms applied to the PAM seenull_dispersion_field_distribution.

Value

An object of classdiversity_range. The mainresult is the diversity range analysis which shows jointly two indicesdescribing the community composition of every cell in the grid:(1) the relative number of species, and (2) the mean dispersion field(see plot method forplot (Soberon et al. 2022).The contains 12 slots with different measurements of biodiversity suchas alpha diversity (species richness in each site or pixel),omega (size of the area of distribution of each species),dispersion field (the standardized size of the area of distribution ofall species occurring in each pixel).

Author(s)

Luis Osorio-Olvera & Jorge Soberón

References

Soberón J, Cobos ME, Nuñez-Penichet C (2021).“Visualizing species richness and site similarity from presence-absence matrices.”Biodiversity Informatics,16(1), 20–27.doi:10.17161/bi.v16i1.14782,https://journals.ku.edu/jbi/article/view/14782..

Soberon J, Cavner J (2015).“Indices of Biodiversity Pattern Based on Presence-Absence Matrices: A GIS Implementation.”Biodiversity Informatics,10, 22–34..

Examples

set.seed(111)pam <- matrix(rbinom(10000,1,0.5),nrow = 100,ncol = 1000)rdivan <- bamm::diversity_range_analysis(pam=pam,                                         parallel = FALSE,                                         niter = 10,                                         return_null_dfield=TRUE)bamm::plot(rdivan,plot_type="diversity_range")# Lagomorphoslagos_path <- system.file("extdata/conejos",                          package = "bamm")enm_path <- list.files(lagos_path,                       pattern = ".tif",                       full.names = TRUE)en_models <- raster::stack(enm_path) >0.01nonas <- which(!is.na(en_models[[1]][]))xy_mat <- sp::coordinates(en_models[[1]])[ nonas,]pam <- bamm::models2pam(en_models,sparse=FALSE)rdivan <- bamm::diversity_range_analysis(pam=pam,                                         xy_mat=xy_mat,                                         raster_templete = en_models[[1]],                                         parallel=TRUE,                                         n_cores=2,                                         return_null_dfield=TRUE)bamm::plot(rdivan,plot_type="diversity_range")bamm::plot(rdivan,plot_type="diversity_range_map")if(require(plotly) && require(crosstalk)){#bamm::plot(rdivan,plot_type="diversity_range_interactive")}

eigen_bam: Compute the Eigen system of two bam objects

Description

Calculates the Eigen values and Eigen vectors of bam objects

Usage

eigen_bam(A = NULL, M = NULL, AM = TRUE, which_eigen = 1, rmap = TRUE)

Arguments

Details

The eigenvector associated with the dominant eigenvalue of anadjacency matrix provides information about the number of forms inwhich a cell can be visited from other cells. Details about theeigen analysis in the context of the area of distribution can befound in Soberon and Osorio-Olvera (2022).

Value

A list with four objects. 1) eigen_values (these are indicated inwhich_eigen parameter of the function), 2) eigen_vectors (the correspondingeigen vectors of each eigen value), 3) Standardized eigen vectors (0 to 1),4) A RasterLayer depicting the information of the first eigen vector ofthe system.

Author(s)

Luis Osorio-Olvera & Jorge Soberón

References

Soberón J, Osorio-Olvera L (2023).“A dynamic theory of the area of distribution.”Journal of Biogeography6,50, 1037-1048.doi:10.1111/jbi.14587,https://onlinelibrary.wiley.com/doi/abs/10.1111/jbi.14587..

Examples

model_path <- system.file("extdata/Lepus_californicus_cont.tif",                          package = "bamm")model <- raster::raster(model_path)sparse_mod <- bamm::model2sparse(model = model,0.75)plot(sparse_mod@niche_model)adj_mod <- bamm::adj_mat(sparse_mod,ngbs = 1,eigen_sys = TRUE)# Product AMeig_bam_am <- bamm::eigen_bam(A=sparse_mod,M=adj_mod,AM=TRUE)raster::plot(eig_bam_am$map)# Product MAeig_bam_ma <- bamm::eigen_bam(A=sparse_mod,M=adj_mod,AM=FALSE)raster::plot(eig_bam_ma$map)

S4 classes to organize data and results ofbamm objects

Description

S4 classes to organize data and results ofbamm objects

Value

An object of class g_area

Slots

coordinates

A two column matrix with coordinates

eigen_vec

Eigen vector of adjacency matrix

eigen_val

Eigen value of adjacency matrixslot g_model A raster representing the geographic areaslot g_sparse A sparse matrix of the geographic area

Author(s)

Luis Osorio-Olvera & Jorge Soberón

jaccard: Estimates the Jaccard index for comparing two binary maps

Description

Estimates the Jaccard index for comparing two binary maps

Usage

jaccard(m1, m2)

Arguments

Details

The Jaccard index is computed as follows

J(A,B)={{|A\cap B|}\over{|A\cup B|}}={{|A\cap B|}\over{|A|+|B|-|A\cap B|}}.

Value

Returns a data.frame with three values: 1) jaccard (Jaccard index),2) percentage_m1 (the percentage of m1 that theintersection|A \cap B| represents), and 3) percentage_m2

Author(s)

Luis Osorio-Olvera & Jorge Soberón

Examples

m1_path <- system.file("extdata/conejos/Lepus_othus_cont.tif",                       package = "bamm")m2_path <- system.file("extdata/conejos/Brachylagus_idahoensis_cont.tif",                       package = "bamm")m1 <- raster::raster(m1_path) > 0.01m2 <- raster::raster(m2_path) >0.01jcc <- bamm::jaccard(m1,m2)print(jcc)

Classleaflet leaflet

Description

Classleaflet leaflet

Value

An object of class leaflet

Author(s)

Luis Osorio-Olvera & Jorge Soberón

model2sparse: Converts a niche model into a diagonal sparse matrix

Description

model2sparse: Converts a niche model into a diagonal sparse matrix

Usage

model2sparse(model, threshold = NULL)

Arguments

Details

threshold parameter represents the suitability value used toconvert continuous model into a binary model.

Value

An object of classsetA. The niche modelis stored as diagonal sparse matrix (slot sparse_model).

Author(s)

Luis Osorio-Olvera & Jorge Soberón

Examples

model_path <- system.file("extdata/Lepus_californicus_cont.tif",                          package = "bamm")model <- raster::raster(model_path)sparse_mod <- bamm::model2sparse(model, threshold=0.75)print(sparse_mod)raster::plot(sparse_mod@niche_model)

models2pam: Converts binary rasters to a PAM

Description

Function to convert binary raster models to aPresence Absences Matrix.

Usage

models2pam(  mods_stack,  return_coords = FALSE,  sparse = TRUE,  parallel = FALSE,  ncores = 2)

Arguments

Details

For more information about PAM see Soberon and Cavner (2015).

Value

A presence-absence matrix (PAM).

Author(s)

Luis Osorio-Olvera & Jorge Soberón

References

Soberon J, Cavner J (2015).“Indices of Biodiversity Pattern Based on Presence-Absence Matrices: A GIS Implementation.”Biodiversity Informatics,10, 22–34..

Examples

lagos_path <- system.file("extdata/conejos",                          package = "bamm")enm_path <- list.files(lagos_path,                       pattern = ".tif",                       full.names = TRUE)[1:10]en_models <- raster::stack(enm_path) >0.01pam <- bamm::models2pam(en_models,                        return_coords=TRUE,                        sparse=FALSE,                        parallel=FALSE,ncores=2)head(pam)

null_dispersion_field_distribution: Null distribution of thedispersion field

Description

null_dispersion_field_distribution estimates arandom distribution of the dispersion field values.

Usage

null_dispersion_field_distribution(  pam,  n_iter = 10,  randal = "indep_swap",  parallel = TRUE,  n_cores = 2)

Arguments

Details

Estimates a random distribution of the dispersion field values. To obtainrandom values it uses the functionpermute_pamat each step of the iterations. Randomization of the PAM can beperformed using the "fastball" (Godard and Neal, 2022) and the"curveball" (Strona et al., 2014), and and the independentswap (Kembel et al. 2010) algorithms.The implementation of the "fastball" in C++ is providedinhttps://github.com/zpneal/fastball/blob/main/fastball.cpp

Value

A data matrix of size nrow(pam) X n_iter with dispersionfield values.

Author(s)

Luis Osorio-Olvera & Jorge Soberón

References

Soberon J, Cavner J (2015).“Indices of Biodiversity Pattern Based on Presence-Absence Matrices: A GIS Implementation.”Biodiversity Informatics,10, 22–34.

Strona G, Nappo D, Boccacci F, Fattorini S, San-Miguel-Ayanz J (2014).“A fast and unbiased procedure to randomize ecological binary matrices with fixed row and column totals.”Nature Communications,5(1), 1–9.ISSN 20411723,doi:10.1038/ncomms5114,https://www.r-project.org.

Godard K, Neal ZP (2022).“fastball: a fast algorithm to randomly sample bipartite graphs with fixed degree sequences.”Journal of Complex Networks,10(6), cnac049.ISSN 2051-1329,doi:10.1093/comnet/cnac049, https://academic.oup.com/comnet/article-pdf/10/6/cnac049/47758701/cnac049.pdf.

Kembel SW, Cowan PD, Helmus MR, Cornwell WK, Morlon H, Ackerly DD, Blomberg SP, Webb CO (2010).“Picante: R tools for integrating phylogenies and ecology.”Bioinformatics,26, 1463–1464.

Examples

set.seed(111)pam <- matrix(rbinom(100,1,0.3),nrow = 10,ncol = 10)dfield_rand <- bamm::null_dispersion_field_distribution(pam,n_iter=10,                                                       parallel=FALSE,                                                       randal="indep_swap",                                                       n_cores = 2)head(dfield_rand)

occs2sparse: Converts occurrence data into a sparse matrix object

Description

occs2sparse: Converts occurrence data into a sparse matrix object

Usage

occs2sparse(modelsparse, occs)

Arguments

Details

Rows of this column vector represent non NA pixels of theniche model.

Value

A sparse vector of zeros (presences) and ones (absences).

Author(s)

Luis Osorio-Olvera & Jorge Soberón

Examples

model_path <- system.file("extdata/Lepus_californicus_cont.tif",                          package = "bamm")model <- raster::raster(model_path)sparse_mod <- bamm::model2sparse(model,threshold=0.05)occs_lep_cal <- data.frame(longitude = c(-115.10417,                                         -104.90417),                           latitude = c(29.61846,                                        29.81846))occs_sparse <- bamm::occs2sparse(modelsparse = sparse_mod,                                occs = occs_lep_cal)head(occs_sparse)

Classpam Presence-Absence Matrix

Description

Classpam Presence-Absence Matrix

Value

An object of class pam

Slots

pams

A list of sparse matrices representing Presence-Absence Matrix foreach simulation time

which_steps

Simulation steps

sp_names

Names of species in the PAM

grid

Raster grid of the studied area

cellIDs

Cells with ids of the PAM sites

Author(s)

Luis Osorio-Olvera & Jorge Soberón

pam2bioindex: PAM to biodiversity index

Description

pam2bioindex estimates various biodiversity indices for acertain PAM.

Usage

pam2bioindex(pam, biodiv_index = "dispersion_field", as_sparse = FALSE)

Arguments

Details

The biodiversity indices can be found in Soberón and Cavner (2015).

Value

An object of classbioindex with three slotseach represents a matrix of diversity indices: alpha, omega, anddispersion field, richness_field.

Author(s)

Luis Osorio-Olvera & Jorge Soberón

References

Soberon J, Cavner J (2015).“Indices of Biodiversity Pattern Based on Presence-Absence Matrices: A GIS Implementation.”Biodiversity Informatics,10, 22–34.

Examples

set.seed(111)pam <- matrix(rbinom(100,1,0.3),nrow = 10,ncol = 10)bioindices <- bamm::pam2bioindex(pam=pam,biodiv_index="all")# Return results as sparse modelsbioindices <- bamm::pam2bioindex(pam=pam,biodiv_index="all",as_sparse=TRUE)bioindices@alphabioindices@omegabioindices@dispersion_field

pam2richness: Converts Presence Absence Matrix (pam object) torichness raster

Description

Converts Presence Absence Matrix (pam object) torichness raster

Usage

pam2richness(pamobj, which_steps)

Arguments

Value

A RasterStack richness for each simulation step

Author(s)

Luis Osorio-Olvera & Jorge Soberón.

Examples

lagos_path <- system.file("extdata/conejos",                          package = "bamm")enm_path <- list.files(lagos_path,                       pattern = ".tif",                    full.names = TRUE)[seq(1,10)]en_models <- raster::stack(enm_path)ngbs_vect <- sample(2,replace = TRUE,                    size = raster::nlayers(en_models))init_coords <- read.csv(file.path(lagos_path,                                  "lagos_initit.csv"))[seq(1,10),]nsteps <- 10sdm_comm <- bamm::community_sim(en_models = en_models,                                ngbs_vect = ngbs_vect,                                init_coords = init_coords,                                nsteps = nsteps,                                threshold = 0.1)pams <-bamm::csim2pam(community_sim = sdm_comm ,                      which_steps = seq_len(nsteps))richness_stack <- bamm::pam2richness(pamobj = pams,                                     which_steps = pams@which_steps)raster::plot(richness_stack)

permute_pam: Function to permute a Presence-Absence-Matrix.

Description

permute_pam: Function to permute a Presence-Absence-Matrix.

Usage

permute_pam(m, niter = NULL, as_sparse = FALSE, randal = "indep_swap")

Arguments

Details

This function can use the "curveball" (Strona et al., 2014), thefastball (Godard and Neal, 2022), and the independent swapalgorithms. The implementation of the "fastball" in C++ is providedinhttps://github.com/zpneal/fastball/blob/main/fastball.cpp.Please when using the "fastball" algorithm for publications citeGodard and Neal (2022). When using the "curveball" citeStrona et al. (2014). When using independent swap ("indep_swap")cite Kembel et al. (2010)

Value

Returns a permuted matrix of the same dimensions of m(same number of rows and columns). Note that the sum of each row and columnof this permuted matrix is equal to that of m.species.

Author(s)

Luis Osorio-Olvera & Jorge Soberón

References

Strona G, Nappo D, Boccacci F, Fattorini S, San-Miguel-Ayanz J (2014).“A fast and unbiased procedure to randomize ecological binary matrices with fixed row and column totals.”Nature Communications,5(1), 1–9.ISSN 20411723,doi:10.1038/ncomms5114,https://www.r-project.org.

Godard K, Neal ZP (2022).“fastball: a fast algorithm to randomly sample bipartite graphs with fixed degree sequences.”Journal of Complex Networks,10(6), cnac049.ISSN 2051-1329,doi:10.1093/comnet/cnac049, https://academic.oup.com/comnet/article-pdf/10/6/cnac049/47758701/cnac049.pdf.

Kembel SW, Cowan PD, Helmus MR, Cornwell WK, Morlon H, Ackerly DD, Blomberg SP, Webb CO (2010).“Picante: R tools for integrating phylogenies and ecology.”Bioinformatics,26, 1463–1464.

Examples

set.seed(111)pam <- matrix(rbinom(100,1,0.3),nrow = 10,ncol = 10)ppam <- bamm::permute_pam(m = pam,niter = NULL,as_sparse = FALSE)# Check if matrices are differentall(pam == ppam)# Check if row totals are the sameall(Matrix::rowSums(pam) == Matrix::rowSums(ppam))# Check if column total are the sameall(Matrix::colSums(pam) == Matrix::colSums(ppam))

Plot method for objects of class diversity_rangebamm.

Description

Plot method for objects of class diversity_rangebamm.

Usage

## S4 method for signature 'diversity_range,ANY'plot(  x,  xlab = NULL,  plot_type = "diversity_range",  legend = TRUE,  legend_position = "bottomright",  ylab = NULL,  col = NULL,  pch = NULL,  pch_legend = 19,  radius = 0.5,  ...)

Arguments

Details

To show interactive diversity_range plots install the 'plotly' Rpackage.

Value

Plot of the results of the diversity_range analysis

Author(s)

Luis Osorio-Olvera & Jorge Soberón

Predict method of the packagebamm.

Description

predicts species' distribution under suitability changes

Usage

## S4 method for signature 'bam'predict(  object,  niche_layers,  nbgs_vec = NULL,  nsteps_vec,  stochastic_dispersal = FALSE,  disp_prop2_suitability = TRUE,  disper_prop = 0.5,  animate = FALSE,  period_names = NULL,  fmt = "GIF",  filename,  bg_color = "#F6F2E5",  suit_color = "#0076BE",  occupied_color = "#03C33F",  png_keyword = "sdm_sim",  ani.width = 1200,  ani.height = 1200,  ani.res = 300)

Arguments

Value

A RasterStack of predictions of dispersal dynamics as a functionof environmental change scenarios.

Author(s)

Luis Osorio-Olvera & Jorge Soberón

Examples

# rm(list = ls())# Read raster model for Lepus californicusmodel_path <- system.file("extdata/Lepus_californicus_cont.tif",                          package = "bamm")model <- raster::raster(model_path)# Convert model to sparsesparse_mod <- bamm::model2sparse(model = model,threshold=0.1)# Compute adjacency matrixadj_mod <- bamm::adj_mat(sparse_mod,ngbs=1)# Initial points to start dispersal processoccs_lep_cal <- data.frame(longitude = c(-115.10417,                                         -104.90417),                           latitude = c(29.61846,                                        29.81846))# Convert to sparse the initial pointsoccs_sparse <- bamm::occs2sparse(modelsparse = sparse_mod,                                occs = occs_lep_cal)# Run the bam (sdm) simultation for 100 time stepssmd_lep_cal <- bamm::sdm_sim(set_A = sparse_mod,                             set_M = adj_mod,                             initial_points = occs_sparse,                             nsteps = 10)#----------------------------------------------------------------------------# Predict species' distribution under suitability change# scenarios (could be climate chage scenarios).#----------------------------------------------------------------------------# Read suitability layers (two suitability change scenarios)layers_path <- system.file("extdata/suit_change",                           package = "bamm")niche_mods_stack <- raster::stack(list.files(layers_path,                                             pattern = ".tif$",                                             full.names = TRUE))raster::plot(niche_mods_stack)# Predictnew_preds <- predict(object = smd_lep_cal,                     niche_layers = niche_mods_stack,                     nsteps_vec = c(50,100))# Generate the dispersal animation for time period 1 and 2if(requireNamespace("animation")){ani_prd <- tempfile(pattern = "prediction_",fileext = ".gif")#new_preds <- predict(object = smd_lep_cal,#                      niche_layers = niche_mods_stack,#                      nsteps_vec = c(10,10),#                      animate=TRUE,#                      filename=ani_prd,#                    fmt="GIF")}

sdm_sim: Simulate single species dispersal dynamics using the BAM framework.

Description

sdm_sim: Simulate single species dispersal dynamics using the BAM framework.

Usage

sdm_sim(  set_A,  set_M,  initial_points,  nsteps,  stochastic_dispersal = TRUE,  disp_prop2_suitability = TRUE,  disper_prop = 0.5,  progress_bar = TRUE)

Arguments

Details

The model is cellular automata where the occupied areaof a species at timet+1 is estimated by the multiplication of twobinary matrices: one matrix represents movements (M), anotherabiotic -niche- tolerances (A)(Soberon and Osorio-Olvera, 2022).

\mathbf{G}_j(t+1) =\mathbf{A}_j(t)\mathbf{M}_j\mathbf{G}_j(t)

The equation describes a very simple process: To find the occupied patchesint+1 start with those occupied at timet denoted by\mathbf{G}_j(t), allow the individuals to disperse amongadjacent patches, as defined by\mathbf{M}_j, then remove individualsfrom patches that are unsuitable, as defined by\mathbf{A}_j(t).

Value

An object of classbam with simulation results.The simulation are stored in the sdm_sim slot (a list of sparse matrices).

Author(s)

Luis Osorio-Olvera & Jorge Soberón

References

Soberón J, Osorio-Olvera L (2023).“A dynamic theory of the area of distribution.”Journal of Biogeography6,50, 1037-1048.doi:10.1111/jbi.14587,https://onlinelibrary.wiley.com/doi/abs/10.1111/jbi.14587..

Examples

model_path <- system.file("extdata/Lepus_californicus_cont.tif",                          package = "bamm")model <- raster::raster(model_path)sparse_mod <- bamm::model2sparse(model,threshold=0.05)adj_mod <- bamm::adj_mat(sparse_mod,ngbs=1)occs_lep_cal <- data.frame(longitude = c(-110.08880,                                         -98.89638),                           latitude = c(30.43455,                                        25.19919))occs_sparse <- bamm::occs2sparse(modelsparse = sparse_mod,                                occs = occs_lep_cal)sdm_lep_cal <- bamm::sdm_sim(set_A = sparse_mod,                             set_M = adj_mod,                             initial_points = occs_sparse,                             nsteps = 10,                             stochastic_dispersal = TRUE,                             disp_prop2_suitability=TRUE,                             disper_prop=0.5,                             progress_bar=TRUE)sim_res <- bamm::sim2Raster(sdm_lep_cal)raster::plot(sim_res)

Class for the A set of the BAM diagram

Description

A class for the A set of the BAM diagram. It contains raster models andIDs of pixels with values different than NA.

Value

An object of class setAshowClass("setA")

Slots

niche_model

A niche model in raster format. It can be a binary modelor continuous.If the model is in a continuous format.

suit_threshold

Suitability value used to binarize continuous model

cellIDs

A numeric vector with the IDs of the cells with predictionvalues

suit_values

A numeric vector with suitability value of the continuousmap

sparse_model

A niche model in sparse matrix format

Author(s)

Luis Osorio-Olvera & Jorge Soberón

Class for the M set of thebamm diagram

Description

Class for the M set of thebamm diagram

Value

An object of class setM

Slots

adj_matix

An adjacency matrix

adj_list

An adjacency list

initial_points

A presence-absence vector with species' occurrences

n_initial_points

Number of initial points used to start the dispersalprocess

ngbs

Number of neighbors

Author(s)

Luis Osorio-Olvera & Jorge Soberón

Examples

showClass("setM")

shape2Grid: Function to create a grid given a spatial polygon

Description

shape2Grid creates a raster grid given a spatial polygon anda grid resolution.

Usage

shape2Grid(shpolygon, resolution, ones = TRUE)

Arguments

Value

Returns a raster object with the shape of 'shpolygon' of a givenresolution.

Author(s)

Luis Osorio-Olvera & Jorge Soberón

Examples

x_coord <- c(-106.5699, -111.3737,-113.9332, -110.8913, -106.4262, -106.5699)y_coord <- c(16.62661, 17.72373, 19.87618, 22.50763, 21.37728, 16.62661)xy <- cbind(x_coord, y_coord)p <- sp::Polygon(xy)ps <- sp::Polygons(list(p),1)sps <- sp::SpatialPolygons(list(ps))r1 <- bamm::shape2Grid(sps,resolution = 0.1,ones = FALSE)plot(r1)sp::plot(sps,add=TRUE)

Show information in setA classbamm.

Description

Show information in setA classbamm.

Show information in csd classbamm.

Show information in pam classbamm.

Show information in pam classbamm.

Show information in setA classbamm.

Show information in diversity_range classbamm.

Usage

## S4 method for signature 'setA'show(object)## S4 method for signature 'csd'show(object)## S4 method for signature 'pam'show(object)## S4 method for signature 'bioindex_sparse'show(object)## S4 method for signature 'setM'show(object)## S4 method for signature 'diversity_range'show(object)

Arguments

Value

Display information about the setA object

Display information about the csd object

Display information about the pam object

Display information about the bioindex_spars object

Display information about the setM object

Display information about the diversity_range object

Author(s)

Luis Osorio-Olvera & Jorge Soberón

sim2Animation: Animate BAM simulation object.

Description

Animates BAM simulation object.

Usage

sim2Animation(  sdm_simul,  which_steps,  fmt = "GIF",  filename,  png_keyword = "sdm_sim",  extra_legend = NULL,  bg_color = "#F6F2E5",  suit_color = "#0076BE",  occupied_color = "#03C33F",  gif_vel = 0.8,  ani.width = 1200,  ani.height = 1200,  ani.res = 300)

Arguments

Details

The animation can be saved in a GIF or HTML format. Note thatthe generation of the GIF can be time consuming for large simulation(simulations with more than 60 time steps).

Value

A RasterStack of species' distribution at each simulation step

Author(s)

Luis Osorio-Olvera & Jorge Soberón

Examples

model_path <- system.file("extdata/Lepus_californicus_cont.tif",                          package = "bamm")model <- raster::raster(model_path)sparse_mod <- bamm::model2sparse(model,0.1)adj_mod <- bamm::adj_mat(sparse_mod,ngbs=2)occs_lep_cal <- data.frame(longitude = c(-115.10417,                                         -104.90417),                           latitude = c(29.61846,                                        29.81846))occs_sparse <- bamm::occs2sparse(modelsparse = sparse_mod,                                occs = occs_lep_cal)sdm_lep_cal <- bamm::sdm_sim(set_A = sparse_mod,                            set_M = adj_mod,                            initial_points = occs_sparse,                            nsteps = 50)if(requireNamespace("animation")){ani_name <- tempfile(pattern = "simulation_",fileext = ".html")#sdm_lep_cal_st <- bamm::sim2Animation(sdm_simul = sdm_lep_cal,#                                      which_steps = seq(1,50,by=1),#                                      fmt = "HTML",ani.width = 1200,#                                      ani.height = 1200,#                                      filename = ani_name)}

sim2Raster: Convert a BAM simulation object to RasterStack

Description

Convert a BAM simulation object to RasterStack.

Usage

sim2Raster(sdm_simul, which_steps = NULL)

Arguments

Value

A RasterStack of species' distribution at each simulation step

Author(s)

Luis Osorio-Olvera & Jorge Soberón

Examples

model_path <- system.file("extdata/Lepus_californicus_cont.tif",                          package = "bamm")model <- raster::raster(model_path)sparse_mod <- bamm::model2sparse(model,threshold=0.1)adj_mod <- bamm::adj_mat(sparse_mod,ngbs = 1)occs_lep_cal <- data.frame(longitude = c(-115.10417,                                         -104.90417),                           latitude = c(29.61846,                                        29.81846))occs_sparse <- bamm::occs2sparse(modelsparse = sparse_mod,                                occs = occs_lep_cal)sdm_lep_cal <- bamm::sdm_sim(set_A = sparse_mod,                            set_M = adj_mod,                            initial_points = occs_sparse,                            nsteps = 10)sdm_lep_cal_st <- bamm::sim2Raster(sdm_simul = sdm_lep_cal,                                  which_steps = seq(1,10,by=1))raster::plot(sdm_lep_cal_st)