---
title: "Mining genus list for any vascular plant family"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Mining genus list for any vascular plant family}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

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

Here in this article, we show how to use the package's function `powoGenera` for
mining all accepted genera for any family of vascular plants available at POWO.\

\

## 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)
```

\

## Mining all accepted genera for some plant families

The function `powoGenera` returns a data frame or saves a CSV file listing all 
genera with associated number of accepted species and their global geographic 
distribution at country or botanical level. The global classification of 
botanical divisions follows the 
[World Geographical Scheme](https://www.tdwg.org/standards/wgsrpd/)
for Recording Plant Distributions, which is already associated with each taxon's
distribution in POWO. Here, we extracted the data for Aristolochiaceae, Begoniaceae, Martyniaceae.\


```{r, eval = FALSE}
ABM <- powoGenera(family = c("Aristolochiaceae", "Begoniaceae", "Martyniaceae"),
                  hybrid = FALSE,
                  verbose = FALSE,
                  save = FALSE,
                  dir = "results_powoGenera",
                  filename = "Arist_Begon_Martyniaceae_search")
```

```{r, echo = FALSE, warning = FALSE}
utils::data("angioGenera")
fam <- c("Aristolochiaceae", "Begoniaceae", "Martyniaceae")
df <- angioGenera[angioGenera$family %in% fam, ]

knitr::kable(df[-c(7, 8, 9, 10, 11, 12)],
             row.names = FALSE,
             caption = "TABLE 1. A general `powoGenera` search for mining all 
             accepted genera for some specific families.")
```
\

## Mining all accepted genera for all vascular plant families

To mine a global genus checklist with associated species number and distribution 
for all families of vascular plants, we recommend to load the 
dataframe-formatted data object called `POWOcodes` that comes associated with 
the __expowo__ package. Because the `POWOcodes` data object already contains the 
URI addresses for all angiosperms, gimnosperms and pteridophytes families 
recognized in the POWO database, you just need to run the code 
below.\

The example below shows how to mine a global checklist of all accepted genera of
plants by using the vector of all families and associated 
URI addresses stored in the `POWOcodes` object.\

```{r, eval = FALSE}
data(POWOcodes)

ALL_gen <- powoGenera(POWOcodes$family,
                      hybrid = TRUE,
                      verbose = TRUE,
                      save = FALSE,
                      dir = "results_powoGenera",
                      filename = "all_plant_genera")
```

\

Since this is a very long search that might requires days to be completed, it 
may happen to loose internet connection at some point of the queried search.
But you do not need to start an entirely new search from the beginning. By 
setting the `powoGenera` with `rerun = TRUE`, a previously stopped search will 
continue from where it left off, starting with the last retrieved taxon. Please 
ensure that the 'filename' argument exactly matches the name of the CSV file 
saved from the previous search, and that the previously saved CSV file is 
located within a subfolder named after the current date. If it is not, please 
rename the date subfolder accordingly.

\

```{r, eval = FALSE}
data(POWOcodes)

ALL_gen <- powoGenera(POWOcodes$family,
                      hybrid = TRUE,
                      verbose = TRUE,
                      rerun = TRUE,
                      save = FALSE,
                      dir = "results_powoGenera",
                      filename = "all_plant_genera")
```

\

## Narrowing down the `powoGenera` search based on a specified country vector

You can also narrow down the search for all accepted genera of any family so as 
to focus on just a particular country or a list of countries. You just need to 
define a vector of country names in the argument `country`. In the example 
below, see that we have originally searched for the genera within the families Aristolochiaceae, Lecythidaceae, Fagaceae, and Dipterocarpaceae, 
but the function only returned a list of genera of Aristolochiaceae and 
Lecythidaceae, because the remaining families do not have any genera 
recorded in the list of countries of interest, i.e. Argentina, Brazil 
or French Guiana.\

```{r, eval = FALSE}
ADFL <- powoGenera(family = c("Aristolochiaceae", "Dipterocarpaceae", 
                              "Fagaceae", "Lecythidaceae"),
                   hybrid = FALSE,
                   country = c("Argentina", "Brazil", "French Guiana"),
                   verbose = FALSE,
                   save = FALSE,
                   dir = "results_powoGenera",
                   filename = "country_constrained_search")
  
```

```{r, echo = FALSE, warning = FALSE}
utils::data("angioGenera")
fam <- c("Aristolochiaceae", "Dipterocarpaceae", 
         "Fagaceae", "Lecythidaceae")
df <- angioGenera[angioGenera$family %in% fam, ]

country <- c("Argentina", "Brazil", "French Guiana")
pattern <- paste(country, collapse = "|")
df <- df[grepl(pattern, df$native_to_country), ]

knitr::kable(df[-c(7, 8, 9, 10, 11, 12, 13)],
             row.names = FALSE,
             caption = "TABLE 2. A `powoGenera` search based on a specified 
             country vector.")
```

\

## Narrowing down the `powoGenera` search based on a specified genus vector

You may want to retrieve information for just one or a list of accepted 
genera from a given country (or from a list of countries). Just like before,
you only need to define a vector of genus names in the argument `genus` and
a vector of country names in the argument `country`. In the example below,
see that we have again searched for just the genera ***Asarum*** and 
***Bertholletia*** of the families Aristolochiaceae and Lecythidaceae, 
but the function only returned the Lecythidaceae genus ***Bertholletia***, 
because ***Asarum*** does not occur in any of the provided list of countries, 
i.e. Brazil or French Guiana.\

```{r, eval = FALSE}
AL <- powoGenera(family = c("Aristolochiaceae", "Lecythidaceae"), 
                 genus = c("Asarum", "Bertholletia"),
                 hybrid = FALSE,
                 country = c("Brazil", "French Guiana"),
                 verbose = TRUE,
                 save = FALSE,
                 dir = "results_powoGenera",
                 filename = "genus_country_constrained_search")
```

```{r, echo = FALSE, warning = FALSE}
utils::data("angioGenera")
genus <- c("Asarum", "Bertholletia")
df <- angioGenera[angioGenera$genus %in% genus, ]

country <- c("Brazil", "French Guiana")
pattern <- paste(country, collapse = "|")
df <- df[grepl(pattern, df$native_to_country), ]

knitr::kable(df[-c(8, 9, 10, 11, 12)],
             row.names = FALSE,
             caption = "TABLE 3. A `powoGenera` search based on specified genus 
             and country vectors.")
```
\

## Reference

POWO (2019). "Plants of the World Online. Facilitated by the Royal Botanic Gardens, Kew. Published on the Internet. Retrieved April 2023."
