-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
149 lines (123 loc) · 5.6 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# smarterapi
<!-- badges: start -->
[](https://github.com/cnr-ibba/r-smarter-api/actions/workflows/R-CMD-check.yaml)
[](https://github.com/cnr-ibba/r-smarter-api/actions/workflows/lint.yaml)
[](https://github.com/cnr-ibba/r-smarter-api/actions/workflows/pkgdown.yaml)
<!-- badges: end -->
The goal of `smarterapi` is to collect data from
[SMARTER REST API](https://webserver.ibba.cnr.it/smarter-api/docs/) and provide them to
the user as a dataframe. Get more information with the
[online vignette](https://cnr-ibba.github.io/r-smarter-api/articles/smarterapi.html).
## Installation
The `smarterapi` package is only available from [GitHub](https://github.com/)
and can be installed as a *source package* or in alternative using
[devtools](https://CRAN.R-project.org/package=devtools)
package, for example:
```r
# install devtools if needed
# install.packages("devtools")
devtools::install_github("cnr-ibba/r-smarter-api")
```
After the installation, you can load the package in your R session:
```{r eval = FALSE, import}
# import this library to deal with the SMARTER API
library(smarterapi)
```
## SMARTER credentials
After the public release of SMARTER data, there's no need to provide credentials
to access the data. If you used to have credentials to access the data, you need
to install the latest version of `smarterapi` package.
## Querying the SMARTER backend
`smarterapi` provides a set of functions used to fetch data from *SMARTER-backend*
endpoints described in [api documentation](https://webserver.ibba.cnr.it/smarter-api/docs/)
and returning them into a `data.frame` object. For example, the `get_smarter_datasets`
lets to query the [Datasets endpoint](https://webserver.ibba.cnr.it/smarter-api/docs/#/Datasets/get_datasets),
while `get_smarter_samples` is able to query and parse the
[Sample endpoints](https://webserver.ibba.cnr.it/smarter-api/docs/#/Samples)
response. Each `smarterapi` function is documented in `R` and you can get help on
each function like any other R functions.
There are two types of parameters that are required to fetch data through
the *SMARTER-backend*: the `species` parameter, which can be `Goat` or `Sheep` respectively
for goat and sheep [Samples](https://webserver.ibba.cnr.it/smarter-api/docs/#/Samples)
or [Variants](https://webserver.ibba.cnr.it/smarter-api/docs/#/Variants) endpoints,
and the `query` parameter which can be provided to any *get_smarter_* function.
The `species` parameter is *mandatory* in order to query an endpoint specific for
*Goat* or *Sheep*, while the `query` parameter is optional and need to be specified
as a `list()` object in order to limit your query to some data in particular.
For example, if you need all the foreground genotypes datasets, you can collect
data like this:
```{r eval = FALSE, dataset}
datasets <- get_smarter_datasets(
query = list(type = "genotypes", type = "foreground"))
```
while if you require only background goat samples, you can do like this:
```{r eval = FALSE, samples}
goat_samples <- get_smarter_samples(
species = "Goat", query = list(type = "background"))
```
The full option list available to each endpoint is available on the SMARTER-backend
[swagger documentation](https://webserver.ibba.cnr.it/smarter-api/docs/): the option
name to use is the same name described in *parameters*, and description and parameter
types can give you hints on how to exploit endpoint properly. For instance, parameters
described as *array of objects* can be specified multiple times:
```r
> goat_breeds <- get_smarter_breeds(query = list(species="Goat", search="land"))
> goat_breeds[c("name","code")]
name code
1 Rangeland RAN
2 Landrace LNR
3 Landin LND
4 Icelandic goat ICL
> goat_samples <- get_smarter_samples(
species = "Goat",
query = list(
breed_code="RAN",
breed_code="LNR",
breed_code="LND",
breed_code="ICL"
)
)
```
## Examples
This is a basic example which shows you how to collect data from SMARTER REST API
for the *Italian* goats belonging to the *Adaptmap* dataset:
```{r eval = FALSE, adaptmap}
# collect the dataset by providing part of the name with the search option:
# since we are forcing to collect only background genotypes, only one dataset
# will be returned
datasets <- get_smarter_datasets(
query = list(
species = "Goat",
search = "adaptmap",
type = "genotypes",
type = "background"
)
)
# get the dataset id
adatpmap_id <- datasets["_id.$oid"][1]
# collect all the italian goats from the adaptmap dataset. Using the dataset id
# to filter out all the samples belonging to this dataset and the country option
# to filter out only the italian samples for this dataset
adaptmap_goats <- get_smarter_samples(
species = "Goat",
query = list(
dataset = adatpmap_id,
country = "Italy"
)
)
```
We have other examples in the [vignettes](https://cnr-ibba.github.io/r-smarter-api/articles/),
for example how to collect data from the [Variants](https://cnr-ibba.github.io/r-smarter-api/articles/variants.html)
endpoints or how to work with [geographic coordinates](https://cnr-ibba.github.io/r-smarter-api/articles/geojson.html).