In DBOSlab/expowo: An R package for mining global plant diversity and distribution data

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")

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. See further details on how to do so in another article here.\

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.\

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

utils::data("angioData")

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

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.\

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") 

\

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.\

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")

\

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.\

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.\

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")

\

knitr::include_graphics("figures/global_richness_country_map_SR_Lecythidaceae_viridis.png", dpi = 300)

\ \

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.\

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")

\

knitr::include_graphics("figures/global_richness_botcountry_map_SR_Lecythidaceae_viridis.png", dpi = 300)

\ \

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

DBOSlab/expowo documentation built on Oct. 29, 2024, 6:27 p.m.