Package 'odyssey' reference manual

Title:	Access documents from the Open Archive HAL
Description:	Access references and download documents from the Open Archive HAL <https://hal.archives-ouvertes.fr/> using the search API.
Authors:	Nicolas Frerebeau [aut, cre] , Université Bordeaux Montaigne [cph, fnd]
Maintainer:	Nicolas Frerebeau <[email protected]>
License:	GPL (>= 3)
Version:	0.0.0.9000
Built:	2024-09-29 04:04:12 UTC
Source:	https://github.com/nfrerebeau/odyssey

HAL API

Description

Initialize a request to the HAL API.

Usage

hal_api()
hal_api()

Value

An object of class HALQuery: a list containing at least the following components:

q: (default to "⁠*:*⁠").
fl: default to "docid" "label_s").
fq
sort
rows: (default to 30).
start: (default to 0).
wt: (default to "json").

Examples

hal_api()
hal_api()

Download Documents

Description

Download Documents

Usage

hal_download(x, ...)

## S3 method for class 'HALQuery'
hal_download(
  x,
  limit = 30,
  start = 0,
  progress = getOption("odyssey.progress"),
  verbose = getOption("odyssey.verbose"),
  ...
)
hal_download(x, ...)

## S3 method for class 'HALQuery'
hal_download(
  x,
  limit = 30,
  start = 0,
  progress = getOption("odyssey.progress"),
  verbose = getOption("odyssey.verbose"),
  ...
)

Arguments

`x`	An object of class `HALQuery` (typically returned by `hal_api()`).
`...`	Currently not used.
`limit`	An `integer` giving the maximum number of results. According to HAL policy, it cannot exceed 10000.
`start`	An `integer` specifying an absolute offset in the complete sorted list of matches to be used as the beginning of the current page. Only used if `cursor` is `FALSE`.
`progress`	A `logical` scalar: should a progress bar for for the request be printed? Only used if R is being used interactively.
`verbose`	A `logical` scalar: should extra information be reported?

Value

An (invisible) logical scalar, TRUE for success and FALSE if any failure.

Author(s)

N. Frerebeau

Examples

## Not run: 
library(magrittr)

## Download the 10 most recent archaeological publication
## (if any files)
hal_api() %>%
  hal_query("archéologie") %>%
  hal_filter("ART" %IN% "docType_s") %>%
  hal_sort("producedDate_tdate", decreasing = TRUE) %>%
  hal_download(limit = 10)

## End(Not run)
## Not run: 
library(magrittr)

## Download the 10 most recent archaeological publication
## (if any files)
hal_api() %>%
  hal_query("archéologie") %>%
  hal_filter("ART" %IN% "docType_s") %>%
  hal_sort("producedDate_tdate", decreasing = TRUE) %>%
  hal_download(limit = 10)

## End(Not run)

Facet Search

Description

Facet Search

Usage

hal_facet(x, ...)

## S3 method for class 'HALQuery'
hal_facet(
  x,
  field,
  limit = 5,
  sort = c("index", "count"),
  prefix = NULL,
  contains = NULL,
  pivot = NULL,
  range = NULL,
  ignore_case = FALSE,
  ...
)
hal_facet(x, ...)

## S3 method for class 'HALQuery'
hal_facet(
  x,
  field,
  limit = 5,
  sort = c("index", "count"),
  prefix = NULL,
  contains = NULL,
  pivot = NULL,
  range = NULL,
  ignore_case = FALSE,
  ...
)

Arguments

`x`	An object of class `HALQuery` (typically returned by `hal_api()`).
`...`	Currently not used.
`field`	A `character` string specifying the field to group by.
`limit`	An `integer` giving the maximum number of results per group.
`sort`	A `character` string specifying the field to be used to sort the results.
`prefix`	A `character` string.
`contains`	A `character` string.
`pivot`	A `character` string.
`range`	A `list` containing the following components: "`range`", "`start`", "`end`", "`gap`".
`ignore_case`	A `logical` scalar: should character case be ignored?

Value

An object of class HALQuery.

Author(s)

N. Frerebeau

Examples

## Not run: 
library(magrittr)

## Most recent publication by journal
hal_api() %>%
  hal_query("archéologie") %>%
  hal_facet(
    field = "docType_s",
    limit = 100,
    sort = "count",
    range = list(
      range = "producedDateY_i",
      start = 2000,
      end = 2020,
      gap = 1
    )
  ) %>%
  hal_search(limit = 10)

## End(Not run)
## Not run: 
library(magrittr)

## Most recent publication by journal
hal_api() %>%
  hal_query("archéologie") %>%
  hal_facet(
    field = "docType_s",
    limit = 100,
    sort = "count",
    range = list(
      range = "producedDateY_i",
      start = 2000,
      end = 2020,
      gap = 1
    )
  ) %>%
  hal_search(limit = 10)

## End(Not run)

Filter Results

Description

Filter Results

Usage

hal_filter(x, ...)

## S3 method for class 'HALQuery'
hal_filter(x, value, field = NULL, ...)
hal_filter(x, ...)

## S3 method for class 'HALQuery'
hal_filter(x, value, field = NULL, ...)

Arguments

`x`	An object of class `HALQuery` (typically returned by `hal_api()`).
`...`	Currently not used.
`value`	A `character` string specifying the value to be used to filter the results.
`field`	A `character` string specifying the field to filter along.

Value

An object of class HALQuery.

Author(s)

N. Frerebeau

Examples

library(magrittr)

## Simple filer
hal1 <- hal_api() %>% hal_filter("file", "submitType_s")
hal1$fq

## Advanced filter
hal2 <- hal_api() %>% hal_filter(c("THESE", "HDR"), "docType_s")
hal2$fq

## Multiple filters
hal3 <- hal_api() %>%
  hal_filter("[NOW-1MONTHS/DAY TO NOW/HOUR]", "submittedDate_tdate") %>%
  hal_filter("-notice", "submitType_s")
hal3$fq

## Range filters
hal4 <- hal_api() %>% hal_filter("[2000 TO 2013]", "submittedDateY_i")
hal4$fq

hal5 <- hal_api() %>% hal_filter("[Aa TO Ab]", "city_s")
hal5$fq
library(magrittr)

## Simple filer
hal1 <- hal_api() %>% hal_filter("file", "submitType_s")
hal1$fq

## Advanced filter
hal2 <- hal_api() %>% hal_filter(c("THESE", "HDR"), "docType_s")
hal2$fq

## Multiple filters
hal3 <- hal_api() %>%
  hal_filter("[NOW-1MONTHS/DAY TO NOW/HOUR]", "submittedDate_tdate") %>%
  hal_filter("-notice", "submitType_s")
hal3$fq

## Range filters
hal4 <- hal_api() %>% hal_filter("[2000 TO 2013]", "submittedDateY_i")
hal4$fq

hal5 <- hal_api() %>% hal_filter("[Aa TO Ab]", "city_s")
hal5$fq

Group Results

Description

Group Results

Usage

hal_group(x, ...)

## S3 method for class 'HALQuery'
hal_group(x, field, limit = 1, sort = "score", decreasing = FALSE, ...)
hal_group(x, ...)

## S3 method for class 'HALQuery'
hal_group(x, field, limit = 1, sort = "score", decreasing = FALSE, ...)

Arguments

`x`	An object of class `HALQuery` (typically returned by `hal_api()`).
`...`	Currently not used.
`field`	A `character` string specifying the field to group by.
`limit`	An `integer` giving the maximum number of results per group.
`sort`	A `character` string specifying the field to be used to sort the results.
`decreasing`	A `logical` scalar: should the sort be increasing or decreasing?

Value

An object of class HALQuery.

Author(s)

N. Frerebeau

Examples

## Not run: 
library(magrittr)

## Most recent publication by journal
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", limit = 1,
            sort = "producedDate_tdate", decreasing = TRUE) %>%
  hal_search(limit = 10)

## End(Not run)
## Not run: 
library(magrittr)

## Most recent publication by journal
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", limit = 1,
            sort = "producedDate_tdate", decreasing = TRUE) %>%
  hal_search(limit = 10)

## End(Not run)

Build Query

Description

Build Query

Usage

hal_query(x, ...)

## S3 method for class 'HALQuery'
hal_query(x, value, field = NULL, ...)

x %OR% y

x %AND% y

x %NOT% y

x %BY% y

x %IN% y

x %TO% y
hal_query(x, ...)

## S3 method for class 'HALQuery'
hal_query(x, value, field = NULL, ...)

x %OR% y

x %AND% y

x %NOT% y

x %BY% y

x %IN% y

x %TO% y

Arguments

`x`, `y`	A `character` vector or an object of class `HALQuery` (typically returned by `hal_api()`).
`...`	Currently not used.
`value`	A `vector` giving the topics to be searched for (see details).
`field`	A `character` string specifying the field to search within. If `NULL` (the default), search within "`text`".

Value

An object of class HALQuery.

Author(s)

N. Frerebeau

Examples

library(magrittr)

## Select fields
hal1 <- hal_api() %>% hal_query("asie")
hal1$q

term <- list("japon", "france")
hal2 <- hal_api() %>% hal_query(term, field = "title_t")
hal2$q

term <- list("Journal", c("Histoire", "History"))
hal3 <- hal_api() %>% hal_query(term, field = "title_t")
hal3$q

## Update query
hal4 <- hal_query(hal1, "agricol?")
hal4$q

## Operators
term <- list("Paris", "France", "history") %NOT% list("Texas", "history")
hal5 <- hal_api() %>% hal_query(term %IN% "text")
hal5$q

term <- c("aluminium", "fer") %BY% 3 %IN% "title_t"
hal6 <- hal_api() %>% hal_query(term)
hal6$q

term <- list("ecology" %IN% "title_t", "cell" %IN% "text")
hal7 <- hal_api() %>% hal_query(term)
hal7$q
library(magrittr)

## Select fields
hal1 <- hal_api() %>% hal_query("asie")
hal1$q

term <- list("japon", "france")
hal2 <- hal_api() %>% hal_query(term, field = "title_t")
hal2$q

term <- list("Journal", c("Histoire", "History"))
hal3 <- hal_api() %>% hal_query(term, field = "title_t")
hal3$q

## Update query
hal4 <- hal_query(hal1, "agricol?")
hal4$q

## Operators
term <- list("Paris", "France", "history") %NOT% list("Texas", "history")
hal5 <- hal_api() %>% hal_query(term %IN% "text")
hal5$q

term <- c("aluminium", "fer") %BY% 3 %IN% "title_t"
hal6 <- hal_api() %>% hal_query(term)
hal6$q

term <- list("ecology" %IN% "title_t", "cell" %IN% "text")
hal7 <- hal_api() %>% hal_query(term)
hal7$q

Select Fields

Description

Select Fields

Usage

hal_select(x, ...)

## S3 method for class 'HALQuery'
hal_select(x, ...)
hal_select(x, ...)

## S3 method for class 'HALQuery'
hal_select(x, ...)

Arguments

`x`	An object of class `HALQuery` (typically returned by `hal_api()`).
`...`	One or more `character` string separated by commas giving the fields to be returned.

Value

An object of class HALQuery.

Author(s)

N. Frerebeau

Examples

library(magrittr)

## Select fields
hal1 <- hal_api() %>% hal_select("label_s")
hal1$fl

hal2 <- hal_api() %>% hal_select("halId_s", "uri_s")
hal2$fl

## Update query
hal3 <- hal_select(hal1, "docType_s")
hal3$fl
library(magrittr)

## Select fields
hal1 <- hal_api() %>% hal_select("label_s")
hal1$fl

hal2 <- hal_api() %>% hal_select("halId_s", "uri_s")
hal2$fl

## Update query
hal3 <- hal_select(hal1, "docType_s")
hal3$fl

Sort Results

Description

Sort Results

Usage

hal_sort(x, field, decreasing = FALSE, ...)

hal_sort(x, field, decreasing = FALSE, ...)
hal_sort(x, field, decreasing = FALSE, ...)

hal_sort(x, field, decreasing = FALSE, ...)

Arguments

`x`	An object of class `HALQuery` (typically returned by `hal_api()`).
`field`	A `character` string specifying the field to be used to sort the results.
`decreasing`	A `logical` scalar: should the sort be increasing or decreasing?
`...`	Currently not used.

Value

An object of class HALQuery.

Author(s)

N. Frerebeau

Examples

library(magrittr)

## Select fields
hal1 <- hal_api() %>% hal_sort("docid")
hal1$sort

## Update query
hal2 <- hal_sort(hal1, "producedDate_tdate", decreasing = TRUE)
hal2$sort
library(magrittr)

## Select fields
hal1 <- hal_api() %>% hal_sort("docid")
hal1$sort

## Update query
hal2 <- hal_sort(hal1, "producedDate_tdate", decreasing = TRUE)
hal2$sort

Search

Description

Usage

hal_count(x, ...)

hal_search(x, ...)

## S3 method for class 'HALQuery'
hal_count(x, path = "search", ...)

## S3 method for class 'HALQuery'
hal_search(
  x,
  path = "search",
  limit = 30,
  start = 0,
  cursor = FALSE,
  parse = "df",
  concat = ",",
  progress = getOption("odyssey.progress"),
  verbose = getOption("odyssey.verbose"),
  ...
)
hal_count(x, ...)

hal_search(x, ...)

## S3 method for class 'HALQuery'
hal_count(x, path = "search", ...)

## S3 method for class 'HALQuery'
hal_search(
  x,
  path = "search",
  limit = 30,
  start = 0,
  cursor = FALSE,
  parse = "df",
  concat = ",",
  progress = getOption("odyssey.progress"),
  verbose = getOption("odyssey.verbose"),
  ...
)

Arguments

`x`	An object of class `HALQuery` (typically returned by `hal_api()`).
`...`	Currently not used.
`path`	A `character` string specifying the url path (see details).
`limit`	An `integer` giving the maximum number of results. According to HAL policy, it cannot exceed 10000.
`start`	An `integer` specifying an absolute offset in the complete sorted list of matches to be used as the beginning of the current page. Only used if `cursor` is `FALSE`.
`cursor`	A `logical` scalar: should a cursor be used for the pagination of results? If `TRUE`, the `sort` parameter of the query will set to "`docid asc`".
`parse`	A `character` string specifying the type of the results. It must be one of "`df`" (default) or "`list`" (see `solrium::SolrClient()`).
`concat`	A `character` string specifying the character to concatenate elements of longer than length $1$ .
`progress`	A `logical` scalar: should a progress bar for for the request be printed? Only used if R is being used interactively.
`verbose`	A `logical` scalar: should extra information be reported?

Value

hal_count() returns the total number of results.
hal_search() returns a data.frame or list (according to type).

Author(s)

N. Frerebeau

References

Apache Solr documentation.

HAL search documentation.

HAL reference frame documentation.

Examples

## Not run: 
library(magrittr)

## Simple search
topic <- list("archéologie", "Celtes", "France") # Combined with AND
hal_api() %>%
  hal_query(topic) %>%
  hal_search(limit = 10)

## Get a list of archaeological journals
topic <- c("archéologie", "archaeology", "archäologie") # Combined with OR
hal_api() %>%
  hal_query(topic) %>%
  hal_select("title_s", "issn_s") %>%
  hal_filter("" %TO% "*" %IN% "issn_s") %>%
  hal_sort("title_s") %>%
  hal_search(path = "ref/journal")

## Get the most recent archaeological publication (in French) by journal
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)

## Get a list of archaeological laboratories
## (only joint laboratories of the CNRS and a French university)
topic <- list("archéologie" %IN% "text", "UMR" %IN% "code_t")
hal_api() %>%
  hal_query(topic) %>%
  hal_select("name_s", "acronym_s", "code_s") %>%
  hal_filter("VALID" %IN% "valid_s") %>%
  hal_sort("acronym_s", decreasing = TRUE) %>%
  hal_search(path = "ref/structure", limit = 15)

## End(Not run)
## Not run: 
library(magrittr)

## Simple search
topic <- list("archéologie", "Celtes", "France") # Combined with AND
hal_api() %>%
  hal_query(topic) %>%
  hal_search(limit = 10)

## Get a list of archaeological journals
topic <- c("archéologie", "archaeology", "archäologie") # Combined with OR
hal_api() %>%
  hal_query(topic) %>%
  hal_select("title_s", "issn_s") %>%
  hal_filter("" %TO% "*" %IN% "issn_s") %>%
  hal_sort("title_s") %>%
  hal_search(path = "ref/journal")

## Get the most recent archaeological publication (in French) by journal
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)

## Get a list of archaeological laboratories
## (only joint laboratories of the CNRS and a French university)
topic <- list("archéologie" %IN% "text", "UMR" %IN% "code_t")
hal_api() %>%
  hal_query(topic) %>%
  hal_select("name_s", "acronym_s", "code_s") %>%
  hal_filter("VALID" %IN% "valid_s") %>%
  hal_sort("acronym_s", decreasing = TRUE) %>%
  hal_search(path = "ref/structure", limit = 15)

## End(Not run)

Package 'odyssey'

Help Index

HAL API

Description

Usage

Value

Examples

Download Documents

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Facet Search

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Filter Results

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Group Results

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Build Query

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Select Fields

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Sort Results

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Search

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples