---
title: "4. Obtaining a Presence-Absence Matrix"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{4. Obtaining a Presence-Absence Matrix}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  warning = FALSE,
  message  = FALSE,
  eval = FALSE,
  fig.width = 8,
  fig.height = 6
)
```

One way of organizing biodiversity data is by using presence-absence matrices (PAMs), where a one represents the presence of species j in cell i, and a zero indicates absence. From a PAM, we can estimate a variety of metrics related to biodiversity patterns, including richness, range size, and composition. For a comprehensive list of biodiversity metrics, refer to the [PAM_indices function in the biosurvey package](https://claununez.github.io/biosurvey/reference/PAM_indices.html).

## Loading data
Before you begin, use the `load_florabr` function to load the data. For more detailed information on obtaining and loading the data, please refer to [1. Getting started with florabr](getting_started.html)

```{r Get data, results='hide', message=FALSE, warning=FALSE, echo=FALSE}
my_dir <- file.path(file.path(tempdir(), "florabr"))
dir.create(my_dir)
get_florabr(output_dir = my_dir, #directory to save the data
            data_version = "latest", #get the most recent version available
            overwrite = T) #Overwrite data, if it exists
```

```{r, message=FALSE, warning=F}
library(florabr)
library(terra)
#Folder where you stored the data with the function get_florabr()
#Load data
bf <- load_florabr(data_dir = my_dir,
                   data_version = "Latest_available",
                   type = "short") #short version
#> Loading version 393.401
```

## Getting a presence-absence matrix

The `get_pam()` function facilitates the utilization of species distribution information in Brazil to generate a PAM. Each site represents a Biome, a State, a vegetation type, or any combination of these. In addition to the PAM, the function also provides a summary and a SpatVector containing the number of species in each site.

As an example, let's obtain a PAM consisting of all tree species native and endemic to the Amazon biome:
```{r}
#Load Flora e Funga do Brasil data
data("bf_data")
#Select endemic and native species of trees with occurrence only in Amazon
am_trees <- select_species(data = bf_data,
                          include_subspecies = FALSE,
                          include_variety = FALSE,
                          kingdom = "Plantae",
                          group = "All", subgroup = "All",
                          family = "All", genus = "All",
                          lifeForm = "Tree", filter_lifeForm = "only",
                          habitat = "All", filter_habitat = "in",
                          biome = "Amazon",
                          filter_biome = "only",
                          state = "All", filter_state = "and",
                          vegetation = "All",
                          filter_vegetation = "in",
                          endemism = "Endemic", origin = "Native",
                          taxonomicStatus = "Accepted",
                          nomenclaturalStatus = "All")
#Get presence-absence matrix
pam_am <- get_pam(data = am_trees, by_biome = TRUE, by_state = TRUE,
                 by_vegetation = FALSE, remove_empty_sites = TRUE,
                 return_richness_summary = TRUE,
                 return_spatial_richness = TRUE,
                 return_plot = TRUE)
#Visualize (as tibble) the PAM for the first 5 species and 7 sites
tibble::tibble(pam_am$PAM[1:7, 1:5])
# # A tibble: 7 × 5
#   Biome  States `Euxylophora paraensis` `Galipea congestiflora` `Hortia longifolia`
#   <fct>  <fct>                    <dbl>                   <dbl>               <dbl>
# 1 Amazon AM                           1                       0                   1
# 2 Amazon MA                           1                       1                   0
# 3 Amazon PA                           1                       1                   1
# 4 Amazon TO                           1                       1                   0
# 5 Amazon MT                           0                       0                   1
# 6 Amazon RR                           0                       0                   1
# 7 Amazon AC                           0                       0                   0
```
Since return_richness_summary is set to TRUE, the function also returns a data frame containing the number of species per site.
```{r}
#Visualize (as tibble) the richness summary table
tibble::tibble(pam_am$Richness_summary[1:7,])
# # A tibble: 7 × 3
#   Biome  States Richness
#   <fct>  <fct>     <dbl>
# 1 Amazon AM          606
# 2 Amazon MA           34
# 3 Amazon PA          296
# 4 Amazon TO            7
# 5 Amazon MT           63
# 6 Amazon RR           45
# 7 Amazon AC          107
```

If return_spatial_richness is set to TRUE, the function will return a SpatVector containing the number of species per site. Additionally, when return_plot is also set to TRUE, the function returns a plot.
```{r IMG09, eval=TRUE, echo = FALSE}
knitr::include_graphics("vignettes_img/Image_09.png")
```