---
title: "Null model algorithms"
author: "Neander M. Heming, Flávio Mota, and Gabriela Alves-Ferreira"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
  #bookdown::html_document2:
  #    base_format: rmarkdown::html_vignette
  #    number_sections: FALSE
vignette: >
  %\VignetteIndexEntry{Null model algorithms}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
bibliography: references.bib
link-citations: true
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
require(kableExtra)
require(knitr)
```

## Contents

-   [Introduction](#intro)
-   [Algorithms](#algorithms)
-   [References](#references)

<br>

## Introduction {#intro}

Null models have been widely used to analyze the patterns observed in nature in the attempt to understand the ecological and evolutionary mechanisms structuring the biological communities. A null model is a simplified representation of how species would be distributed or biological communities be assembled if specific ecological processes were not operating. Until now, algorithms were designed to create null models using matrix data. The package [`SESraster`](https://github.com/HemingNM/SESraster) covers a current gap by implementing randomization algorithms to build null models using presence/absence raster data.

<br>

## Algorithms {#algorithms}

The data for null model analyses usually consists of a binary presence-absence matrix, in which the entries represent the presence (1) or absence (0) of a particular species in a particular site, rows represent species or taxa, columns represent sites or samples [@ulrich2012]. There are nine major types of null model algorithms for species co-occurrence analysis based on how sums of species (originally rows) and sites (originally columns) are treated (i.e. fixed, equiprobable, or proportional sums; see Table 1; Table 2 of [@gotelli2000]). When using raster data, layers represent species or taxa and cells represent sites or samples. `SESraster` currently implements six (green cells in Table 1) of the nine algorithms for co-occurrence analysis summarized by Gotelli [-@gotelli2000].

```{r table1-data, echo=FALSE}
type <- c("Equiprobable", "Proportional", "Fixed")
typeabv <- c("E", "P", "F") #c("Equipr.", "Prop.", "Fixed")
typeinit <- c("E", "P", "F")
sp_info <- "occurrence frequency" # "Spp occur."
site_info <- "site richness" # "Site rich."
# Species - Sites
d <- data.frame("Rows" = c("Species<br>(Row, Layer)", rep("", 2)),
                type=type,
                paste0(
                  "SIM", c(1,7,2), ": ", typeinit, typeinit[1], 
                  "<br>", 
                  paste(paste0(sp_info, ":"), typeabv, 
                        "<br>", paste0(site_info,  ":"), typeabv[1]),
                  "") ,
                paste0(
                  "SIM", c(6,8,4), ": ", typeinit, typeinit[2], 
                  "<br>", 
                  paste(paste0(sp_info, ":"), typeabv, 
                        "<br>", paste0(site_info,  ":"), typeabv[2]), 
                  "") ,
                paste0(
                  "SIM", c(3,5,9), ": ", typeinit, typeinit[3], 
                  "<br>",
                  paste(paste0(sp_info, ":"), typeabv, 
                        "<br>", paste0(site_info,  ":"), typeabv[3]), 
                  "") )
colnames(d) <- c(" ", " ", paste0("", type))
```

```{r table1, echo=FALSE}
# opts_current$append(list(label = "table1"))
kable(d, dbooktabs = TRUE, align=c("r", "c", "c", "c", "c"), escape = F, 
      label = "table1", #format = "html",
      caption = "Table 1. Nine null model algorithms for species co-occurrence analysis listed in Gotelli (2000). Cells in green represent the algorithms currently implemented in SESraster.") %>%
  collapse_rows() %>%
  kable_styling(bootstrap_options = c("bordered")) %>%
  add_header_above(c(" " = 2, "Site (Col, Cell)" = 3), background = "#F2F2F2") %>%
  row_spec(0, background = "#F2F2F2") %>% # , extra_css = c("border-bottom-style: none", "", "", "")
  column_spec(1:2, bold = TRUE, background="#F2F2F2", border_right = TRUE) %>%
  column_spec(3:4, border_right = TRUE) %>%
  column_spec(3, background=c("#B4EEB4")) %>%
  column_spec(4, background=c("#FFFAFA")) %>%
  column_spec(5, background=c("#B4EEB4"))

```

<br>

## Spatial null model algorithms in SESraster
Time to get started with `SESraster`: `vignette("spatial-null-models")`. 
See installation instructions and how the implemented null model algorithms work with spatial data.

<br>

## References {#references}