---
title: "Mining species number of any plant family"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Mining species number of any 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 `powoFam` 
for mining the species number for any family of angiosperms, gymnosperms and 
pteridophytes. By providing a family name or a vector of family names, 
the `powoFam` function visits each POWO page of the genera within the queried 
family(ies) to extract the accepted species number. Then, it sums these values 
to deliver the total species number within each plant family.\

\

# 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 the total species number for any plant family

The function `powoFam` returns a data frame or saves a CSV file listing the total
species number (excluding hybrid species) for the queried plant families.\

The example below shows how to mine the total species number by defining a vector 
of three families: __Cabombaceae__, __Lecythidaceae__, and __Martyniaceae__. 
The resulting output (TABLE 1) is also saved directly in the specified directory
__results_powoFam__.\

```{r, eval = FALSE}
CLM <- powoFam(family = c("Cabombaceae", "Lecythidaceae", "Martyniaceae"),
               verbose = TRUE,
               save = FALSE,
               dir = "results_powoFam",
               filename = "Camb_Lecy_Martyniaceae_diversity")
```

\

```{r, echo = FALSE, warning = FALSE}
utils::data("angioData")
utils::data("POWOcodes")
family <- c("Cabombaceae", "Lecythidaceae", "Martyniaceae")
fams <- angioData$family[angioData$family %in% family]
sp_nbr <- as.data.frame(table(fams))
powo_uri <- gsub("^http", "https", POWOcodes$uri[POWOcodes$family %in% family])
kew_id <- gsub(".+[:]", "", powo_uri)
species_number <- sp_nbr$Freq
res <- data.frame(family, species_number, kew_id, powo_uri)

knitr::kable(res,
             row.names = FALSE,
             align = 'c',
             caption = "TABLE 1. A general `powoFam` search for mining the total species number of three angiosperm families.")
```

\

## Mining species number accross all plant families

To mine the species number of all families of vascular plants, we recommend to 
load the dataframe-formatted object called `POWOcodes` that comes associated 
with the __expowo__ package. The `POWOcodes` data object already contains the 
URI addresses for all plant families recognized in the 
[POWO](https://powo.science.kew.org) database, so you just need to call it to 
the R environment.\

The example below shows how to mine the species number of all vascular plant 
families by using the vector of all plant families and associated URI 
addresses stored in the `POWOcodes` object.\

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

ALL_fam <- powoFam(POWOcodes$family,
                   verbose = TRUE,
                   save = FALSE,
                   dir = "results_powoFam",
                   filename = "all_plants_species_number")
```

\

## 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."