---
title: "Mapping global distribution for any taxonomic level"
output: rmarkdown::html_vignette
resource_files:
    - global_richness_botcountry_map_SR_Cariniana_viridis.png
    - global_richness_botcountry_map_SR_Lecythidaceae_Spectral.png
    - global_richness_botcountry_map_SR_Lecythidaceae_viridis.png
    - global_richness_country_map_SR_Cariniana_viridis.png
    - global_richness_country_map_SR_Lecythidaceae_Spectral.png
    - global_richness_country_map_SR_Lecythidaceae_viridis.png
vignette: >
  %\VignetteIndexEntry{Mapping global distribution for any taxonomic level}
  %\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;
}
```

Here in this article, we show how to use the package's function `powoMap` 
for mapping the global distribution for any genus or family of plants 
either at political country or botanical country levels, following the 
[World Geographical Scheme for Recording Plant Distributions](https://www.tdwg.org/standards/wgsrpd/). 
The `powoMap` can use as input data the dataframe-formatted resulting query from 
`powoSpecies` function or an external spreadsheet. Then, `powoMap` can 
automatically create one global distribution map for the entire group 
(e.g., order, family) or multiple maps for each desired taxonomic level within 
the input data (e.g., genus). The map is colored according to the species richness 
using either [Viridis](https://CRAN.R-project.org/package=viridis) or
[RColorBrewer](https://CRAN.R-project.org/package=RColorBrewer) color palettes.\

\

# Setup

Install the latest development 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. Mining species distribution from POWO to use as input data in powoMap

To create global distribution maps using `powoMap` function, you can either import 
a spreadsheet or use the package's `powoSpecies` function to get distribution 
information for the species of the target family or genus. It is possible to 
adjust one of the arguments in `powoSpecies` function to extract data only from 
a genus or list of genera.\

The example below shows how to mine the distribution for an specific genus of
Lecythidaceae. By defining a vector within the argument `genus`, here the function
will search for all species and associated distribution data for just the genus 
_Cariniana_. Note that we create an object called `mapspdist`, which is the 
dataframe-formatted input data to create the map. The output shown here (TABLE 1) 
is a simplified version, where we have removed some columns so as to focus on the 
display of just the distribution data.\

```{r, eval = FALSE}
mapspdist <- powoSpecies(family = "Lecythidaceae", 
                         genus = "Cariniana",
                         hybridspp = FALSE,
                         country = NULL,
                         verbose = TRUE,
                         save = FALSE,
                         dir = "results_powoSpecies",
                         filename = "Lecythidaceae_Cariniana")
```

```{r, echo = FALSE, warning = FALSE}
utils::data("angioData")

df <- angioData[angioData$family %in% "Lecythidaceae", ]
df <- df[df$genus %in% "Cariniana", ]
                               
```

```{r, echo = FALSE, warning = FALSE}
knitr::kable(df[-c( 2, 3, 5, 6, 7, 10, 11, 13)],
             row.names = FALSE,
             align = 'c',
             caption = "TABLE 1. A general `powoSpecies` search for mining 
             distribution of the Lecythidaceae genus _Cariniana_.")

```


\

# 2. Creating global-scale map for one genus to show species richness at political country level

To generate a global distribution map for one genus that show species richness 
at political country level, you can use the previously generated `mapspdist` 
object as input data of the `powoMap` function and set the `distcol` argument as
"native_to_country". This is the very column of the dataframe-formatted `mapspdist` 
object that is associated to species distribution at political country.\

The example below shows how to create the global distribution map of _Cariniana_'s 
species richness as colored by the `viridis` palette of the __Viridis__ package. 
If you set up both the arguments `vir_color` and `bre_color` with any of the 
__Viridis__ and __RColorBrewer__ color palettes, then two maps colored respectively 
by these color vectors will be automatically generated. Different file formats 
and resolutions (e.g. JPG, PDF, PNG, TIFF) are also supported by setting the 
arguments `format` and `dpi`.\

```{r, eval = FALSE}
powoMap(inputdf = mapspdist,
        botctrs = FALSE,
        distcol = "native_to_country",
        taxclas = "genus",
        verbose = FALSE,
        save = FALSE,
        vir_color = "viridis",
        bre_color = NULL,
        leg_title = "SR",
        dpi = 600,
        dir = "results_powoMap",
        filename = "global_richness_country_map",
        format = "jpg") 
```

\
```{r, echo = FALSE, out.width = "600px", fig.cap = "FIGURE 1. Global species richness of the genus _Cariniana_ at country level and colored with viridis scale."}
knitr::include_graphics("figures/global_richness_country_map_SR_Cariniana_viridis.png", 
                        dpi = 300)
```

\

# 3. Creating global-scale map for one genus to show species richness at botanical country level

To generate a global distribution map for one genus that show species richness 
at botanical country level, adjust the argument `botctrs` within the `powoMap` 
function to TRUE. Then, use the previously generated `mapspdist` object as input 
data in `inputdf` and set the `distcol` argument to the name of the column with 
distribution according to botanical countries between quotation marks. This is 
the column of the dataframe-formatted `mapspdist` object or from an external 
spreadsheet.\

The example below shows how to create the global distribution map of _Cariniana_'s 
species richness according to botanical countries and colored by the `viridis` 
palette of the __Viridis__ package. If you set up both the arguments `vir_color` 
and `bre_color` with any of the __Viridis__ and __RColorBrewer__ color palettes, 
then two maps colored respectively by these color vectors will be automatically 
generated. Different file formats and resolutions (e.g. JPG, PDF, PNG, TIFF) are 
also supported by setting the arguments `format` and `dpi`.\


```{r, eval = FALSE}
powoMap(inputdf = mapspdist,
        botctrs = TRUE,
        distcol = "native_to_botanical_countries",
        taxclas = "genus",
        verbose = FALSE,
        save = FALSE,
        vir_color = "viridis",
        bre_color = NULL,
        leg_title = "SR",
        dpi = 600,
        dir = "results_powoMap",
        filename = "global_richness_botcountry_map",
        format = "jpg")
```

\
```{r, echo = FALSE, out.width = "600px", fig.cap = "FIGURE 2. Global species richness of the genus _Cariniana_ at botanical country level and colored with viridis scale."}
knitr::include_graphics("figures/global_richness_botcountry_map_SR_Cariniana_viridis.png", dpi = 300)
```

\

# 4. Creating global-scale map of species richness for an entire family

To generate a family-level global distribution map of species richness, use 
`powoSpecies` function without any genus constraint so as to query a full species 
list of the desired family and the associated distribution data. Then, the 
resulting query object should be used as input data of the `powoMap` function.\

```{r, eval = FALSE}
mapspdist <- powoSpecies(family = "Lecythidaceae",
                         genus = NULL,
                         hybridspp = FALSE,
                         country = NULL,
                         verbose = FALSE,
                         save = FALSE,
                         dir = "results_powoSpecies",
                         filename = "Lecythidaceae")
```

\
The example below uses the previously generated dataframe-formatted `mapspdist` 
object as input data to `powoMap` function, with the `distcol` argument set as 
"native_to_country", the `taxclas` argument set as `"family"`, the `vir_color` 
argument set as "viridis", and the `bre_color` argument set as "Spectral", so as
to automatically produce two __global distribution maps__ of all Lecythidaceae's 
species richness at __country level__, which are distinctly colored by `Viridis` 
and `RColorBrewer` color palettes.\

Note that if you had set here the `taxclas` as `"genus"`, then the `powoMap` 
function would have produced individual distribution maps of species richness 
for every single genus within Lecythidaceae, all of them being stored in the 
desired directory at `dir` argument.\

```{r, eval = FALSE}
powoMap(inputdf = mapspdist,
        botctrs = FALSE,
        distcol = "native_to_country",
        taxclas = "family",
        verbose = FALSE,
        save = FALSE,
        vir_color = "viridis",
        bre_color = "Spectral",
        leg_title = "SR",
        dpi = 600,
        dir = "results_powoMap/",
        filename = "global_richness_botcountry_map",
        format = "jpg")
```

\
```{r, echo = FALSE, out.width = "600px", fig.cap = "FIGURE 3. Global species richness of Lecythidaceae at country level and colored with viridis scale."}
knitr::include_graphics("figures/global_richness_country_map_SR_Lecythidaceae_viridis.png", dpi = 300)
```

\
\
```{r, echo = FALSE, out.width = "600px", fig.cap = "FIGURE 4. Global species richness of Lecythidaceae at country level and colored with Spectral scale."}
knitr::include_graphics("figures/global_richness_country_map_SR_Lecythidaceae_Spectral.png", dpi = 300)
```

\
\
To create global maps of Lecythidaceae according to botanical countries, change 
the argument `distcol` to  "native_to_botanical_countries", the `vir_color` 
argument to "viridis", and the `bre_color` argument to "Spectral". This 
automatically produce two global distribution maps of Lecythidaceae's species 
richness at botanical countries, which are distinctly colored by `Viridis` 
and `RColorBrewer` color palettes.\

Note that if you had set here the `taxclas` as `"genus"`, then the `powoMap` 
function would have produced individual distribution maps of species richness 
for every single genus within Lecythidaceae, all of them being stored in the 
desired directory at `dir` argument.\

```{r, eval = FALSE}
powoMap(inputdf = mapspdist,
        botctrs = TRUE,
        distcol = "native_to_botanical_countries",
        taxclas = "family",
        verbose = FALSE,
        save = FALSE,
        vir_color = "viridis",
        bre_color = "Spectral",
        leg_title = "SR",
        dpi = 600,
        dir = "results_powoMap",
        filename = "global_richness_botcountry_map",
        format = "jpg")
```

\
```{r, echo = FALSE, out.width = "600px", fig.cap = "FIGURE 5. Global species richness of Lecythidaceae at botanical countries and colored with viridis scale."}
knitr::include_graphics("figures/global_richness_botcountry_map_SR_Lecythidaceae_viridis.png", dpi = 300)
```

\
\
```{r, echo = FALSE, out.width = "600px", fig.cap = "FIGURE 6. Global species richness of Lecythidaceae at botanical countries and colored with Spectral scale."}
knitr::include_graphics("figures/global_richness_botcountry_map_SR_Lecythidaceae_Spectral.png", dpi = 300)
```
\

# 5. Using an external spreadsheet as input data in powoMap

It is possible to use data from other databases in order to create global maps 
using our `powoMap` function. To perform this task, the spreadsheet must have at 
least a column with species names and one or two columns with associated 
distribution in the countries and/or botanical countries. The species names must 
be binomial, and the country names must be written in full and separated by a 
comma and a space right after to the `powoMap` function works properly. The data 
frame generated by our function `powoSpecies` can be used as a model to create 
this standard spreadsheet (see the examples above). 
\

To use your external dataset as an imported spreadsheet, you must provide the 
name of the object in the argument `inputdf`. The `powoMap` function also will 
need information about the taxon level to generate the maps. To do so, the user 
must provide the name of the correspondent column in the argument `taxclas` 
(e.g., `"family"`, `"genus"`). To indicate the column with the distribution, 
change the `distcol` argument. If the distribution is according to political 
country names (e.g., Brazil, Peru), you just have to write the name of the column 
with this data. Otherwise, if you need global maps according to the TDWG botanical 
countries (level 3), you must indicate in which column this data (e.g., Brazil 
North, Peru) is stored and also change the argument `botctrs` from FALSE to TRUE.\

\

# 6. Reference

POWO (2019). "Plants of the World Online. Facilitated by the Royal Botanic Gardens, Kew. Published on the Internet; http://www.plantsoftheworldonline.org/ Retrieved April 2023."
