---
title: "Mining distribution for any plant species"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Mining distribution for any plant species}
  %\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 `powoSpDist` 
for mining the entire distribution for any species of vascular plants. Despite 
yielding similar outputs, `powoSpDist` and `powoSpecies` serve distinct purposes. 
`powoSpecies` enables the retrieval of all species from a designated list of 
families and/or genera. In contrast, `powoSpDist` is designed to focus 
specifically on a designated list of species, streamlining the process of 
retrieving species distribution information. While both functions ultimately 
produce the same output, their utility depends on the user’s initial interest. 
If one’s interest is centered on a particular species, `powoSpDist` offers a 
more efficient approach, eliminating the need to run a code that mines data for 
an entire family or genus and subsequently filter the desired species—a process 
that could be more time-consuming. This targeted approach allows for a more 
streamlined and resource-efficient search. The `powoSpDist` uses the argument 
`species` to set the name or list of species names, and then the function access 
the auxiliary functions `.getgenURI` and `getInfo` to extract their respective 
distribution.\

\

## 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 distribution for any plant species

The function `powoSpDist` returns a dataframe or saves a CSV file listing the 
entire global distribution at country or botanical level for any of the given 
species scientific name(s) (excluding hybrid species), their genus, publication 
and authorship. 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 at POWO.\

The example below shows how to mine the distribution for a specified vector of 
two species. The output shown here (a table) is simplified by removing the 
family and distribution according to botanical subdivision columns.\

```{r, eval = FALSE}
BL_dist <- powoSpDist(family = c("Begoniaceae", "Lecythidaceae"),
                      species = c("Hillebrandia sandwicensis", "Lecythis pisonis"),
                      verbose = TRUE,
                      save = FALSE,
                      dir = "results_powoSpDist",
                      filename = "Begoniaceae_Lecythidaceae")
```

\

```{r, echo = FALSE, warning = FALSE}
utils::data("angioData")
fam <- c("Begoniaceae", "Lecythidaceae")
df <- angioData[angioData$family %in% fam, ]
species <- c("Hillebrandia sandwicensis", "Lecythis pisonis")
df <- df[df$taxon_name %in% species, ]

knitr::kable(df[-c(2, 3, 6, 9, 11, 13)],
             row.names = FALSE,
             align = 'c',
             caption = "TABLE 1. A general `powoSpDist` search for mining 
             distribution of two angiosperm species.")
```

\

## Mining distribution for all vascular plant species

To mine the distribution checklist for all accepted species of vascular plants, 
you can load the dataframe-formatted data 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, you just need 
to call it to your R environment.\

The example below shows how to mine the global distribution of all accepted non
hybrid species of vascular plants by using the vector of all plant
families and associated URI addresses stored in the `POWOcodes` object. Note that
the argument `species` should be as `NULL`, so that the search is not constrained
to any particular species, i.e. the function will return global distribution for
all species in all queried families.\

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

ALL_dist <- powoSpDist(POWOcodes$family,
                       species = NULL,
                       verbose = TRUE,
                       save = FALSE,
                       dir = "results_powoSpDist",
                       filename = "all_plant_distribution")
```

\

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