---
title: "Retrieve data for taxomomic groups."
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Retrieve data for taxomomic groups.}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = identical(Sys.getenv("NOT_CRAN"), "true")
)

```

```{r setup}
library(fwtraits)
```

## Step 1: Securing and loading the API key.

Please follow the [secure_the_api_key](https://anthonybasooma.github.io/fwtraits/articles/Secure_API_key.html)) steps and secure the API in the R environment before retrieving the species traits form the database. To check on the available traits in the database, you can check with the **`fw_dbguide()`** or browse the database directly in the [species traits](https://www.freshwaterecology.info/abbreviations.php).


## Step2: Fetching groups data and visualisation

* To ensure the exact trait spellings are used, the user is strongly advised to run **`fw_dbguide()`** function and filter out the organism groups. The trait names can be copied and pasted in the **`ecoparams`** parameter of the **`fw_fetchdata()`** function.

* Multiple species can be set in a list or dataframe.

* Wide data formats can be displayed, but the longer version is the output by default.

* Ensure the right species names are indicated to avoid detailed checks that delays data search and might lead to erroneous trait extraction or errors. Checks are conducted on the species names to ensure they are harmonized to trait searches.

**Data output columns and meaning**

+------------------------------+-------------------------------------------------------------------------------------------------+
| Function                     | Explanation                                                                                     |
+:=============================+:================================================================================================+
|`ID_FWE`                      |Indicates the record ID number in the www.freshwaterecology.info database.                       |
+------------------------------+-------------------------------------------------------------------------------------------------+
|`OrganismGroup`               |The highest taxonomic group nomenclature, which includes five groups, namely\                    |
|                              |macroinvertebrates, fish, phytoplankton, phtyobenthos (diatoms) and macrophtes.                  |
+------------------------------+-------------------------------------------------------------------------------------------------+
|`TaxaGroup`                   |The taxonomic classification of a species. Its a class for phytobenthos but\                     |
|                              |sometimes order, family.Not recommended for querying data.                                       |
+------------------------------+-------------------------------------------------------------------------------------------------+
|`Family`                      |Family of particular species or taxonomic group. **Recommended for data search.**\               |
|                              |search since taxa families are taxonomic classification.                                         |
+------------------------------+-------------------------------------------------------------------------------------------------+
|`Genus`                       | The taxonomic genera for a particular taxon.  **Recommended for data search.**                  |
+------------------------------+-------------------------------------------------------------------------------------------------+
|`Species`                     |The specific epithet for a particular species. Combining both the genera \                       |
|                              |forms the taxonomic scientific name. **Recommended for data search** but the\                    |
|                              |but its disadvantageous if many are required and are from the same genus or family\              |
|                              |genus or family                                                                                  |
+------------------------------+-------------------------------------------------------------------------------------------------+
|`Taxonname`                   | Complete taxonomic but without the naming authorities. *Not used in data search*\               |
+------------------------------+-------------------------------------------------------------------------------------------------+
|`Author`                      | The taxonomic authority of a particular of taxon.\                                              |
+------------------------------+-------------------------------------------------------------------------------------------------+
|`Parameter`                   |The ecological parameter being searched from the database. The *raw* and *tidyr*\                |
|                              | names can be obtained using the fw_dbguide() function.                                          |
+------------------------------+-------------------------------------------------------------------------------------------------+
|`CategoryName`                | The particular ecological trait of taxon or species.                                            |
+------------------------------+-------------------------------------------------------------------------------------------------+
|`CategoryLevels`              | Some ecological parameters such as stream ecological preference for macroinvertebrates,         |
|                              | catchment region for fish, provide more information. For example, for catchment                 |
|                              | region, beside knowing where the basin is located, its indicated whether the .                  |
|                              | specie is native or invasive in particular basin.                                               |
+------------------------------+-------------------------------------------------------------------------------------------------+
|`DataType`                    |The type, whether fuzzy, factor, categorical or numerical. However, the\                         |
|                              |  author reclassify the data in the subsequent analysis                                          |
+------------------------------+-------------------------------------------------------------------------------------------------+
|`ClassificationType`          | The data classification criteria based on Schmidt-Kloiber & Herring et al., 2012.               |
+------------------------------+-------------------------------------------------------------------------------------------------+
|`CategoryExplanaiton`         | Describe the different category meaning.                                                        |
+------------------------------+-------------------------------------------------------------------------------------------------+


### 1. Fishes

**1.1: Single species**

```{r Retrieve fish species data for one species}

migration <- fw_fetchdata(data = "Abramis brama",
                          organismgroup = 'fi',
                          ecoparams = 'migration')

head(migration$ecodata)
```


```{r Retrieve fish species data for one fish species}

#species data archived in fwtraits

data("speciesdata") 

traitsout <- fw_fetchdata(data = speciesdata, 
                          organismgroup = 'fi',
                          taxonomic_column = 'scientificName', 
                          ecoparams = c('migration', 'threat austria',
                                        'oxygen tolerence', 'migration fibs'),
                          taxalevel = 'species')

head(traitsout$ecodata)

```

**1.3 Visualizing fish traits**
  
```{r Viszualize outputs for fish, fig.width = 8, fig.height= 6, fig.align='center'}

fw_visualize(output = traitsout)

```


### 2. Macroinvertebrates

**2.1: Single species**
  
```{r Macroinvertebrates traits retrieval for one species}

mmdata_traits <- fw_fetchdata(data =  "Margaritifera margaritifera",
                              organismgroup = 'mi',
                              ecoparams = c('stream zonation preference'),
                              inform = TRUE)
```

**2.2: More than one species in a vector/list**
  
```{r Species names in alist or vector for macroinvertebrates}

speciesvec <- c("Margaritifera margaritifera",
                "Pseudunio auricularius",
                "Musculium lacustre",
                "Musculium transversum",
                "Parastenocaris germanica")

multspp <- fw_fetchdata(data =  speciesvec,
                        organismgroup = 'mi',
                        ecoparams = c('stream zonation preference'),
                        inform = TRUE)
head(multspp$ecodata)

```

**2.3: More than one species in a dataframe**
  
```{r Species names in a dataframe not list or vector}

macrodf <- data.frame(organismgroup = rep('mi', 13),
                      species = c("Margaritifera margaritifera",
                                  "Pseudunio auricularius",
                                  "Musculium lacustre",
                                  "Musculium transversum",
                                  "Corbicula fluminea",
                                  "Congeria leucophaeata",
                                  "Dreissena polymorpha",
                                  "Dreissena rostriformis bugensis",
                                  "Parastenocaris germaica",
                                  "Branchiobdella balcanica",
                                  "Branchiobdella hexadonta",
                                  "Branchiobdella parasita",
                                  "Branchiobdella pentadonta"))

multspp_df <- fw_fetchdata(data =  macrodf,
                           organismgroup = 'mi',
                           taxonomic_column = 'species',
                           ecoparams = c("stream zonation preference", "feeding type"),
                           inform = TRUE)
head(multspp_df$ecodata)

```


**2.4: Data visualization for macroinvertebrates**
  
  If the species considered are more than 1, then visualization can be to determine the frequency of each trait. This is an optional function for post data searches.

```{r Viszualize outputs for macroinvertebrates, fig.width = 6, fig.height= 5, fig.align='center'}

fw_visualize(output = multspp)

fw_visualize(output = multspp_df)

```

### 3. Macrophytes

```{r Species names in list or vector for macrophytes}

mpp <- fw_fetchdata(data = c("Amblystegium fluviatile",
                             "Amblystegium humile",
                             "Amblystegium riparium",
                             "Amblystegium serpens",
                             "Amblystegium tenax",
                             "Amblystegium varium"),
                    organismgroup = 'mp',
                    ecoparams = c('zone - systema'))

```

### 4. Phytobenthos

```{r Species names in a list or vector for phytobenthos}

pbdata <- fw_fetchdata(data = c("Gongrosira debaryana",
                                "Gongrosira fluminensis",
                                "Hydrodictyon reticulatum",
                                "Sphaerobotrys fluviatilis",
                                "Stigeoclonium farctum",
                                "Stigeoclonium tenue",
                                "Tetraspora gelatinosa",
                                "Thorea hispida"),
                       organismgroup = 'pb',
                       ecoparams = c('substrate preference'))
head(pbdata$ecodata)

```

```{r Species names in a list for phytobenthos and macroinvertebrates}

mipbdata <- fw_fetchdata(data = list(mi=c("Congeria kusceri",
                                          "Congeria leucophaeata",
                                          "Dreissena polymorpha",
                                          "Dreissena rostriformis bugensis"),
                                     pb= c("Gongrosira debaryana",
                                           "Gongrosira fluminensis",
                                           "Hydrodictyon reticulatum",
                                           "Sphaerobotrys fluviatilis",
                                           "Stigeoclonium farctum",
                                           "Stigeoclonium tenue",
                                           "Tetraspora gelatinosa",
                                           "Thorea hispida")),
                         organismgroup = c('mi','pb'),
                         ecoparams = list(mi = c('stream zonation preference'),
                                          pb = c('substrate preference')), details = TRUE)

head(mipbdata$ecodata)

```

### 5. Phytoplankton

```{r Species names in list or vector for phytoplankton}

ppdata <- fw_fetchdata(data = c("Navicula radiosa", 'Acanthoceras zachariasii',
                                "Achnanthes brevipes",
                                "Achnanthidium catenatum",
                                "Actinocyclus normanii",
                                "Achnanthidium subatomus"),
                       organismgroup = 'pp',
                       ecoparams = c('stenoecy factor', 'life form'),
                       cachefolder = 'cache',
                       warn = TRUE,
                       inform = TRUE)

head(ppdata$ecodata)

```

### Collating by family and genus taxa levels for different species

**NOTE:**
Based the on the FWE database, the phytoplantkon don't have families but rather taxa groups, genus, and species levels. Therefore, for data extraction the family level for phytoplankton is not possible.**Check the table for the definition of a Taxa Group.**

```{r TaxaGroup and Genus taxa levels for phytoplankton}

ppdata_genus <- fw_fetchdata(data = c("Navicula"),
                       organismgroup = 'pp',
                       ecoparams = c('stenoecy factor', 'life form'),
                       cachefolder = 'cache',
                       taxalevel = 'genus',
                       inform = TRUE)

#Only Navicula genus but but multiple species
print(unique(ppdata_genus$ecodata$Genus)) 


ppdata_taxagroup <- fw_fetchdata(data = c("Bacillariophyceae"),
                       organismgroup = 'pp',
                       ecoparams = c('stenoecy factor', 'life form'),
                       cachefolder = 'cache',
                       taxalevel = 'taxagroup',
                       inform = TRUE)

 #More than more 1 genus 
print(unique(ppdata_taxagroup$ecodata$Genus)[1:5])

```

## Step3. References

1. Schmidt-Kloiber, A., & Hering, D. (2015). www.freshwaterecology.info - An online tool that unifies, standardises and codifies more than 20,000 European freshwater organisms and their ecological preferences. Ecological Indicators, 53, 271-282. https://doi.org/10.1016/j.ecolind.2015.02.007

2. Wickham H (2024). _httr2: Perform HTTP Requests and Process the Responses_. R package version 1.0.3,<https://CRAN.R-project.org/package=httr2>

3. https://httr2.r-lib.org/articles/wrapping-apis.html












