-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
91 lines (69 loc) · 4.2 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
---
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%"
)
```
# odyssey
<!-- badges: start -->
[](https://github.com/nfrerebeau/odyssey/actions)
[](https://codecov.io/gh/nfrerebeau/odyssey)
[](https://nfrerebeau.r-universe.dev){.pkgdown-devel}
[](https://www.repostatus.org/#wip)
<!-- badges: end -->
Access data and download documents from the [Open Archive HAL](https://hal.archives-ouvertes.fr/). This package provides a programmatic access to the [HAL API](https://api.archives-ouvertes.fr/docs).
## Installation
You can install the development version from [GitHub](https://github.com/) with:
``` r
# install.packages("remotes")
remotes::install_github("nfrerebeau/odyssey")
```
## Usage
The use of **odyssey** involves three steps. First, a standard query is created using `hal_api()`. Then, a set of functions allows to customize this query (see below). Finally, `hal_search()` and `hal_download()` allow to collect data and to download documents.
The following functions allow you to customize a query. They must be applied to the object returned by `hal_api()` and can be called in any order. `hal_filter` can be used several times to add multiple search filters. See the HAL search API documentation for a [list of available fields](https://api.archives-ouvertes.fr/docs/search/?schema=fields#fields).
* `hal_query()` allows to choose the fields to query and to define the query terms using boolean logic (`q` parameter). For a simple search, grouping terms in a list allows to combine them with AND, while grouping terms in a vector allows to combine all the terms with OR. If needed, the infix functions `%AND%`, `%OR%`, `%NOT%`, `%IN%`, `%TO%` allow to build more complex queries (remember that infix operators are composed left to right).
* `hal_select()` is used to select the fields to be returned in the results (`fl` parameter).
* `hal_filter()` is used to [retain all results that satisfy a conditions](https://api.archives-ouvertes.fr/docs/search/?#fq) (`fq` parameter).
* `hal_sort()` [orders the results](https://api.archives-ouvertes.fr/docs/search/?#sort) by the value of the select field (`sort` parameter). According to the HAL API documentation, you should avoid text fields and multi-valued fields which will produce unpredictable results.
* `hal_group()` is used to [group search results](https://api.archives-ouvertes.fr/docs/search/?#group) (`group.*` parameters).
* `hal_facet()` is used to [facet search results](https://api.archives-ouvertes.fr/docs/search/?#facet) (`facet.*` parameters).
```{r package}
## Load packages
library(odyssey)
library(magrittr) # pipes
```
Get the 10 most recent documents about archaeology of Celts in France:
```{r search}
## Topic selection
## Will be combined with AND
topic <- list("archéologie", "Celtes", "France")
## Search publications
hal_api() %>%
hal_query(topic) %>%
hal_select("title_s", "producedDate_tdate") %>%
hal_filter("notice" %IN% "submitType_s") %>%
hal_sort("producedDate_tdate", decreasing = TRUE) %>%
hal_search(limit = 10)
```
Get the most recent archaeological publication (in French) by journal:
```{r group}
hal_api() %>%
hal_query("archéologie") %>%
hal_select("producedDate_tdate") %>%
hal_filter("ART" %IN% "docType_s") %>%
hal_sort("producedDate_tdate", decreasing = TRUE) %>%
hal_group(
field = "journalTitle_s",
sort = "producedDate_tdate",
decreasing = TRUE
) %>%
hal_search(limit = 10)
```
## Code of Conduct
Please note that the **odyssey** project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.