# Retrieve data for taxomomic groups.

    library(fwtraits)

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

Please follow the secure_the_api_key) 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.

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

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

    head(migration$ecodata)

    #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

    fw_visualize(output = traitsout)

### 2. Macroinvertebrates

2.1: Single 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

    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

    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.

    fw_visualize(output = multspp)

    fw_visualize(output = multspp_df)

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

    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)

    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

    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.

    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