https://github.com/alrobles/xsdm

https://github.com/alrobles/xsdm

Repository

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# xsdm




xsdm: A demographic approach to species distribution model



## Installation

`xsdm` relies on cmdstanr package. Please install first 
this package tha is not in cran with the following code:

```{r,  eval=FALSE}
install.packages("cmdstanr", repos = c('https://stan-dev.r-universe.dev', getOption("repos")))
```

Following this you need to install cmdstan

```{r, eval=FALSE}
cmdstanr::install_cmdstan()
```

After this, you can install the development version of xsdm from [GitHub](https://github.com/alrobles/xsdm/) with:

```{r,  eval=FALSE}
remotes::install_github("alrobles/xsdm")
```


## Quick Start
We provide here a basic example to get a species distribution model (SDM) using `xsdm`.  

### First step
The first step is to create a list with the raster stack 
of environmental time series of variables. These example rasters are packaged for distribution with the `xsdm` package. We use the `terra::rast` function to convert a data frame in a time series raster.


```{r step1}
library(xsdm)
library(terra)
bio1 <- xsdm::bio1_df 
bio1 <- terra::rast(bio1)

```

These correspond to a 30-year time series of the bioclimatic variables bio1 (average annual temperature) and bio12 (cumulative annual precipitation) obtained from the project 
`CHELSA` (Climatologies at high resolution for the earth's land surface areas) that we get from https://chelsa-climate.org/.

### Second step
We create a list of this time series. In this first example we use one variables but is possible to use 2, 3 or more variables. This is depending on the model. But the computation time increase with the number of
parameters the model fits. We recomend to name the elements of the list with the environmental variable name

```{r step2}
envData <- list(bio1 = bio1)
```

### Third step
The next step is to set a `data.frame` with presence points of a species of interest you want to model.

```{r step3}
occ <- xsdm::mus_virtualis
```

In this example we provide a virtual species. Later we will show how to create these virtual species. The
structure of the `data.frame` should be a table with 4 columns with the following structure:

* *name*: The name of the taxon to model
* *longitude*: longitude in decimals
* *latitude*: latitude in decimals
* *presence*: Presence or absence value

Disclaimer: We provided limited documentation in how to download and clean data, however the main focus of `xsdm` is the modeling of species distribution. From the design philosophy of the package, it is the user's responsibility to provide correct input data. 

### Fourth step
Get our very own first model is pretty straight foward using the function `xsdm`:
```{r step4}
model <- xsdm(envData, occ)
```

In the design of xsdm we simplify the use with a main `xsdm` function. Innerlly this function controls
the model flow.

## What is xsdm
`xsdm` integrates concepts of stochastic demography into species distribution modelling. Inferences, utilizing Bayesian methods based in 'Stan', are made of aspects of the environmental niche of a species, and those inferences can be used to project species geographic range. See Berti et al. (2024, ) for a description of the statistical and demographic models used.


## Virtual species

In order to follow with more examples we provide an auxiliary data package with examples to show the xsdm funcionalities.
```{r step5, eval=FALSE}
install.packages("xsdmexamples", repos="https://alrobles.github.io/drat/")
```

Then we create a raster list with two environmental variables.
This example is centered in a small portion of South New Mexico
with 1 km^2 of spatial resolution.

```{r step6}

library(xsdmexamples)
library(terra)
bio1 <- terra::rast(bio1_df_NM)
bio12 <- terra::rast(bio12_df_NM)

envData <- list(bio1 = bio1, bio12 = bio12)

```
We are going to create a virtual species with the function 
`vsp`.


```{r step7}
library(xsdm)
virt_rast <- vsp(env_data = envData, 
                 param.list = list(mu = c(8, 700), 
                                sigl = c(1, 100),
                                sigr = c(2, 50),
                                c = -5,
                                pd = 0.8,
                                L = matrix(c(1,0,0,1), ncol = 2) ))
```
```{r plotvsp}
library(terra)
plot(virt_rast)
```

Then we are going to create a random sample of points from this
virtual species


```{r}

df_presence <- terra::spatSample(virt_rast, 1000, na.rm = TRUE, xy = TRUE)

names(df_presence) <- c("longitude", "latitude", "probs")

df_presence$presence <- rbinom(nrow(df_presence),
                               size = 1,
                               prob = df_presence$probs)



```
Let's run a model to test that `xsdm` can retrieve the parameters we created the virtual species with.

```{r step8, eval=FALSE}
model <- xsdm(envData, df_presence,
              recompile = TRUE,
              max_treedepth = 10,
              adapt_delta = 0.8,
              nchains = 4,
              parallel_chains = 4,
              threads_per_chain = 5,
              iter_warmup = 500,
              iter_sampling = 500,
              refresh = 10)
```

Owner

GitHub Events

Issues and Pull Requests

Last synced: 10 months ago