---
title: "Plotting species discovery"
output: rmarkdown::html_vignette
resource_files:
    - cumulative_discovery_Luetzelburgia.png
vignette: >
  %\VignetteIndexEntry{Plotting species discovery}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{css, echo=FALSE}
p.caption {
  font-size: 0.8em;
}
.table{
  width: auto;
  font-size: 14px;
}
.table caption {
  font-size: 1em;
}
```

Information concerning the year of publication of a species and its current status, obtained from the taxonomically validated [Plants of the World Online (POWO)](https://powo.science.kew.org/) database, can offer valuable insights into temporal trends related to changes in species nomenclature.\

In this article, we illustrate the utilization of the package's `accGraph` function for automatically generate plots that showcase the dynamics of species discoveries and nomenclatural changes over time – all in a single run! This versatile function is capable of producing two distinct types of graphics: one depicting the accumulation of formally described species within each genus or family, and the other illustrating changes in species nomenclature over time. The species discovery curve inherently demonstrates continuous growth, with the rate of this growth linked to the number of new discoveries - and this one is the focus of this article. To employ this function effectively, it is necessary to have data stored in a spreadsheet or dataset generated using the `powoSpecies` function, where the `synonyms` argument is set to TRUE.
\

## Setup

Install the latest developmental version of __expowo__ from 
[GitHub](https://github.com/):

``` r
#install.packages("devtools")
devtools::install_github("DBOSlab/expowo")
```
```{r package load, message=FALSE, warning=FALSE}
library(expowo)
```

\

## 1. Plotting the species discoveries for one genus
The example below shows the accumulation curve of [Luetzelburgia](https://powo.science.kew.org/taxon/urn:lsid:ipni.org:names:22832-1), 
one legume genus. The black line is derived from the publication dates of currently accepted species names, while the red line is related to the publication year of the basionym for each accepted species name. As a result, it illustrates the cumulative count of formally described species of this genus. Different file formats (e.g. JPG, PDF, PNG, TIFF) are also supported by setting the argument `format`. Notice that the `spp_changes_col` argument is set with the name of the column (in this case, "genus") of the input dataframe that we want to be used for plotting the graphic. If we defined it as "family", for example, the function would use the data of the entire family available in the input dataframe to create the graphic.\ 

```{r, eval = FALSE}
accGraph(inputdf = "Luetzelburgia_spp",
         verbose = TRUE,
         spp_acc = TRUE,
         spp_changes = TRUE,
         spp_changes_col = "genus",
         genus_plots = FALSE,         
         save = TRUE,
         dir = "results_accGraph",
         filename = "cumulative_discovery_Luetzelburgia",
         format = "jpg")

```

\
```{r, echo = FALSE, out.width = "600px", fig.cap = "FIGURE 1. Accumulation of formally described species in the big genus _Luetzelburgia_ over time."}
knitr::include_graphics("figures/cumulative_discovery_Luetzelburgia.png", 
                        dpi = 300)
```

\

The accumulation curve of _Luetzelburgia_ shows that it has 14 spp. described and a high 
increase of taxonomic changes in 2008 (noticeable by the curve in light red).

## 2. Plotting the species discoveries for the entire dataset
If your dataset contains species from more than one genus, the `accGraph` function can
automatically plot a graphic of changes in species nomenclature over the years with the data of those genera.

First, to get those graphs, we extracted all data of the genera _Achillea_, _Matricaria_ and _Launaea_ from Plants of the World Online using `powoSpecies` as follows:

```{r, eval = FALSE}
newdata <- powoSpecies(family = "Asteraceae",
                       genus = c("Achillea", "Matricaria", "Launaea"),
                       synonyms = TRUE,
                       save = FALSE,
                       dir = "Asteraceae_results",
                       filename = "Asteraceae_spp")
```

Then, we used the newly developed function `accGraph` to plot individual graphics of 
accumulation of species discovery and a violin graph for the three genera.


```{r, eval = FALSE}
accGraph(inputdf = newdata,
         verbose = TRUE,
         spp_acc = TRUE,
         spp_changes = FALSE,
         spp_changes_col = "genus",
         genus_plots = TRUE,
         save = TRUE,
         dir = "results_accGraph",
         filename = "cumulative_discovery_Asteraceae_",
         format = "jpg")
```
\
```{r, echo = FALSE, out.width = "600px", fig.cap = "FIGURE 2. Accumulation of formally described species in the genus _Achillea_ over time."}
knitr::include_graphics("figures/cumulative_discovery_Asteraceae_Achillea.png", 
                        dpi = 300)
```
\
```{r, echo = FALSE, out.width = "600px", fig.cap = "FIGURE 3. Accumulation of formally described species in the genus _Matricaria_ over time."}
knitr::include_graphics("figures/cumulative_discovery_Asteraceae_Matricaria.png", 
                        dpi = 300)
```
\
```{r, echo = FALSE, out.width = "600px", fig.cap = "FIGURE 4. Accumulation of formally described species in the genus _Launaea_ over time."}
knitr::include_graphics("figures/cumulative_discovery_Asteraceae_Launaea.png", 
                        dpi = 300)
```