https://github.com/emilio-berti/gatewayr
https://github.com/emilio-berti/gatewayr
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/emilio-berti/gatewayr
- Owner: emilio-berti
- License: other
- Created: 2024-08-14T08:07:33.000Z (10 months ago)
- Default Branch: master
- Last Pushed: 2024-11-14T07:47:41.000Z (7 months ago)
- Last Synced: 2025-01-21T04:28:08.886Z (5 months ago)
- Language: R
- Size: 5.07 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.Rmd
- License: LICENSE
Awesome Lists containing this project
README
---
title: "api-usage"
output: github_document
vignette: >
%\VignetteIndexEntry{api-usage}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
options(tibble.print_max = 4, tibble.print_min = 4)
```
```{r setup}
library(gatewayr)
```
# Access the GATEWAy API
The _gatewayr_ package is designed to interface with the [GATEWAy API](http://localhost:8000/gateway/api/).
This is achieved using the API REST framework and the _httr2_ R package.
There are **n** access points to the API implmeneted in _gatewayr_ (Table 1).
Table 1: Endpoints of the GAYEWAy API.
| **Endpoint** | **filters** | **function** |
| ------------ | ----------- | ------------ |
|`/gateway/api/foodwebs` | | query foodwebs |
| | `?foodwebID=` | filter by _foodwebID_|
| | `?ecosystemType=` | filter by _ecosystemType_|
| | `?xmin=` | filter by _decimalLongitude_|
| | `?xmax=` | filter by _decimalLongitude_|
| | `?ymin=` | filter by _decimalLatitude_|
| | `?ymax=` | filter by _decimalLatitude_|
|`/gateway/api/taxa` | | query taxa|
| | `?taxonID=` | filter by _taxonID_|
| | `?taxonRank=` | filter by _taxonRank_|
| | `?taxonomicStatus=` | filter by _taxonomicStatus_|
|`/gateway/api/communities` | | query communities |
| | `?foodwebID=` | filter by _foodwebID_ |
|`/gateway/api/lifeStages` | | list all life stages |
|`/gateway/api/mvoementTypes` | | list all life stages |
|`/gateway/api/metabolicTypes` | | list all metabolic types |
|`/gateway/api/sizeMethods` | | list all body size measurement methods |
|`/gateway/api/references` | | list all measurement references |
All endpoints that filter not based on IDs require one argument.
Endpoints filtering on IDs can take more than one argument; in that case, arguments are separated by a `,` (coma).
As example, `/gateway/api/foodwebs?ecosystemType=lakes` returns all lake food webs, and `/gateway/api/foodwebs?foodwebID=1,5,19` returns food webs 1, 5, and 9.
## Access Food Web metadata
The `get_foodweb()` accesses the food web metadata, such as the name of the food web, its ecosystem type and geographic coordinates.
```{r foodwebs}
fw <- get_foodweb()
fw
table(fw[["ecosystemType"]])
```
Food webs can be filtered based on their _foodwebID_ value.
```{r foodwebs-filtering-0}
get_foodweb(foodwebID = c(1, 9, 125))
```
The optional arguments _ecosystemType_ and _xmin_, _xmax_, _ymin_, _ymax_ can be used to filter the database to retain only the food webs from one ecosystem type or within a bounding box.
```{r foodwebs-filtering-1}
get_foodweb(ecosystemType = "lakes")
```
If some, but not all vertices of the bounding box are provided, the others will be set to not constrain the filtering.
This allows to specify, for instance, minimum longitude only.
```{r foodwebs-filtering-2}
get_foodweb(ecosystemType = "lakes", xmin = 5)
```
## Access Taxon List
The `get_taxon()` accesses the list of all taxa in the GATEWAy database.
```{r taxa}
taxa <- get_taxon()
taxa
sort(table(taxa$taxonRank))
```
Taxa can be filtered by their _taxonID_ value.
```{r taxa-filtering-0}
get_taxon(taxonID = c(1, 5, 24, 1243))
```
The optional arguments _taxonRank_ and _taxonomicStatus_ can be used to retain only taxa of a specific rank (e.g., _species_ or _family_) or taxonomic status (e.g., _accepted_ or _synonym_),
```{ taxa-filtering-1}
get_taxon(taxonRank = "species")
get_taxon(taxonRank = "species", taxonomicStatus = "accepted")
```
## Access Communities
The `get_community()` accesses the community data and takes only the argument _foodwebID_.
```{r communities-0}
get_community(foodwebID = c(2, 5, 12))
```
The optional argument `columns` can be used to retain only certain columns.
```{r communities-2}
communities <- get_community(
foodwebID = c(2, 5, 12),
columns = c("foodwebName", "ecosystemType", "acceptedTaxonName")
)
communities
```
When `columns = "all"` all columns are returned.
```{r communities-3}
communities <- get_community(foodwebID = 5, columns = "all")
communities
```
## Access Interactions
The `get_interaction()` accesses the interaction data and can take the arguments _resourceID_, _consumerID_, and _foodwebID_.
```{r interactions-0}
library(gatewayr)
interactions <- get_interaction(resourceID = 2291)
interactions
table(interactions[["foodwebName"]])
```
```{r interactions-1}
interactions <- get_interaction(resourceID = 2291, foodwebID = 100)
interactions
```
```{r interactions-2}
interactions <- get_interaction(foodwebID = 100)
interactions
```
## Access Static Tables
Static tables are tables that cannot be filtered.
These are short tables for which server-side operations are not particularly useful.
They are called within functions of _gatewayr_ to populate the queried tables.
The main reason to request these tables directly by the user is to inspect available values.
```{r static-0}
get_life_stage()
get_size_method()
get_movement_type()
get_metabolic_type()
get_reference()
```
# Database Coverage
`coverage()` calculates the data coverage of the table, i.e. the fraction of entries that are not NA.
```{r coverage}
library(gatewayr)
interactions <- get_interaction(foodwebID = 1)
coverage(interactions)
```
The coverage table is always arranged in increasing order of coverage.
```{r coverage-food-webs}
coverage(get_foodweb())
```
```{r coverage-taxa}
coverage(get_taxon())
```
```{r coverage-community}
coverage(get_community())
coverage(get_community(columns = "all"))
```
```{r coverage-interaction}
library(gatewayr)
interactions <- get_interaction()
coverage_interactions <- coverage(interactions)
coverage_interactions[coverage_interactions[["coverage"]] > 0, ]
```