The diagram on the left side represents the structure of the Mangal database. All *references*
included in Mangal correspond to a specific publication that includes one or several *dataset(s)*. This dataset is
basically a collection of ecological *networks* whose *nodes* and *interactions* (edges) are stored
in separate tables. Below, we briefly describe the content of each table.
**References** -- Information pertaining to a reference (scientific article, book, online website,
etc.) characterizing an original collection of ecological networks. URLs of data and publication
sources are included as well as persistent identifiers (when available) such as digital object
identifiers (DOIs). This allows users to retrieve more details about original publications using
appropriate R packages such as [`crossref`](https://docs.ropensci.org/rcrossref/).
**Datasets** -- Metadata of the datasets attached to a reference. It includes a general description
of the networks.
**Networks** -- Metadata of the networks attached to a dataset. It provides the sampling location, date and
specific description of the network.
**Nodes** -- Information on the population, taxa or individual in the network. Each node has the
original taxon name documented and a taxonomic backbone provided by all services embedded in `taxize`
[@chamberlain_2019].
**Interactions** -- Information on the interaction type (e.g. mutualism,
predation, etc.), the strength, and the direction of the interaction between
two nodes.
## Authentication
So far, the `rmangal` package provides methods to get access to the data store. Data requests
(performed via `rmangal_request()` or `rmangal_request_singleton()`) do not require any authentication.
A bearer authentication strategy using [ORCID](https://orcid.org/) credentials
(as a third-party services) has been implemented on all `POST`, `DELETE`, `PUT`
API operations to allow the user to add and delete new ecological to the
database. These features are not currently included in the **rmangal** package, but
remain under consideration for future major releases.
# How to use **rmangal**
## Overall approach
In order to efficiently retrieve networks from the database, **rmangal**
includes 7 search functions querying the 5 tables described above as well as a table dedicated to the taxonomy backbone.
1. `search_references()`: search in the reference table, for instance the user can look for a specific `doi`;
2. `search_datasets()`: search among datasets using a keyword;
3. `search_networks()` and `search_networks_sf()`: search networks based on a keyword or a geographical area;
4. `search_interactions()`: list all networks containing a specific interaction type;
5. `search_nodes()`: identify nodes based on nodes information;
6. `search_taxonomy()`: identify nodes based on taxonomic names and unique identifiers.
All of these functions return specific class objects with the information needed
to retrieve the corresponding set of ecological networks with
`get_collection()`. Hence, the user can easily retrieve data in two steps:
```r
networks <- search_*(query = "your query") |> get_collection()
```
If there is only one network to be retrieved, `get_collection()`
returns a `mgNetwork` object, otherwise it returns an object of class
`mgNetworksCollection` which is a collection (a list) of `mgNetwork` objects.
Below, we exemplify how to use the search functions, how to get a collection of
networks and how to use other packages to carry out specific analyses.
Requests can be cached (`rmangal` leverages `httr2::req_cache()`) either by
setting the argument `cache` to `TRUE` or by providing a path that points to the
desired cache directory. Using `cache` the basic workflow becomes:
```r
networks <- search_*(query = "your query", cache = TRUE) |> get_collection()
```
## Search functions
In **rmangal**, every function queries a specific table and allows only one
query at a time (see section [Batch analysis](#batch-analysis) to learn
how to perform more than one query). All the functions offer two ways to query
the corresponding table:
1. a keyword: in this case, the entries returned are the partial or full keyword match of any strings contained in the table;
2. a custom query: in this case, entries returned are exact matches.
We start by loading **rmangal** as well as `tibble` (enhanced data frames).
``` r
library(rmangal)
library(tibble)
```
### Search and list available datasets
Let's assume we are looking for ecological networks including species living in
lagoons. If we have no idea about any existing data set, the best starting point
is then to query the `dataset` table with `lagoon` as a keyword:
``` r
lagoon <- search_datasets(query = "lagoon")
class(lagoon)
#> [1] "tbl_df" "tbl" "data.frame" "mgSearchDatasets"
lagoon
#> # A tibble: 2 × 10
#> id name description public created_at updated_at ref_id user_id networks references
#> 
