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] (<https://orcid.org/0000-0001-5759-4944>, 03pbgwk21), Université Bordeaux Montaigne [fnd] (03pbgwk21)
Maintainer:	Nicolas Frerebeau <[email protected]>
License:	GPL (>= 3)
Version:	0.0.0.9000
Built:	2025-03-06 06:19:14 UTC
Source:	https://codeberg.org/nfrerebeau/odyssey

Download Documents

Description

Download Documents

Usage

hal_download(query, ...)

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

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

Arguments

`query`	An object of class `HALQuery` (typically returned by `hal_query()`).
`...`	Currently not used.
`destination`	A `character` string giving the directory path where the downloaded files are to be saved.
`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?
`verbose`	A `logical` scalar: should extra information be reported?

Value

Invisibly returns destination.

Author(s)

N. Frerebeau

Examples

## Not run: 
## Download the 10 most recent archaeological publication
## (if any files)
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: 
## Download the 10 most recent archaeological publication
## (if any files)
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(query, ...)

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

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

Arguments

`query`	An object of class `HALQuery` (typically returned by `hal_query()`).
`...`	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: 
## Get the number of archaeological document by journal
hal_query("archéologie") |>
  hal_facet(field = "journalTitle_s", sort = "count", decreasing = TRUE) |>
  hal_search()

## Get the number of documents per year
hal_query("archéologie") |>
  hal_facet(
    sort = "count",
    range = list(
      field = "producedDateY_i",
      start = 2000,
      end = 2020,
      gap = 1
    )
  ) |>
  hal_search()

## End(Not run)
## Not run: 
## Get the number of archaeological document by journal
hal_query("archéologie") |>
  hal_facet(field = "journalTitle_s", sort = "count", decreasing = TRUE) |>
  hal_search()

## Get the number of documents per year
hal_query("archéologie") |>
  hal_facet(
    sort = "count",
    range = list(
      field = "producedDateY_i",
      start = 2000,
      end = 2020,
      gap = 1
    )
  ) |>
  hal_search()

## End(Not run)

Filter Results

Description

Filter Results

Usage

hal_filter(query, ...)

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

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

Arguments

`query`	An object of class `HALQuery` (typically returned by `hal_query()`).
`...`	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

## Simple filer
hal_query() |> hal_filter("file", "submitType_s")

## Advanced filter
hal_query() |> hal_filter("THESE" %OR% "HDR", "docType_s")

## Multiple filters
hal_query() |>
  hal_filter("NOW-1MONTHS/DAY" %TO% "NOW/HOUR", "submittedDate_tdate") |>
  hal_filter("-notice", "submitType_s")

## Range filters
hal_query() |> hal_filter(2000 %TO% 2013, "submittedDateY_i")

hal_query() |> hal_filter("Aa" %TO% "Ab", "city_s")
## Simple filer
hal_query() |> hal_filter("file", "submitType_s")

## Advanced filter
hal_query() |> hal_filter("THESE" %OR% "HDR", "docType_s")

## Multiple filters
hal_query() |>
  hal_filter("NOW-1MONTHS/DAY" %TO% "NOW/HOUR", "submittedDate_tdate") |>
  hal_filter("-notice", "submitType_s")

## Range filters
hal_query() |> hal_filter(2000 %TO% 2013, "submittedDateY_i")

hal_query() |> hal_filter("Aa" %TO% "Ab", "city_s")

Group Results

Description

Group Results

Usage

hal_group(query, ...)

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

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

Arguments

`query`	An object of class `HALQuery` (typically returned by `hal_query()`).
`...`	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: 
## Get the most recent archaeological publication (in French) by journal
hal_query("archéologie") |>
  hal_filter("ART" %IN% "docType_s") |>
  hal_select("producedDate_tdate", "docid") |>
  hal_sort("producedDate_tdate", decreasing = TRUE) |>
  hal_group(
    field = "journalTitle_s",
    sort = "producedDate_tdate",
    decreasing = TRUE
  ) |>
  hal_search()

## End(Not run)
## Not run: 
## Get the most recent archaeological publication (in French) by journal
hal_query("archéologie") |>
  hal_filter("ART" %IN% "docType_s") |>
  hal_select("producedDate_tdate", "docid") |>
  hal_sort("producedDate_tdate", decreasing = TRUE) |>
  hal_group(
    field = "journalTitle_s",
    sort = "producedDate_tdate",
    decreasing = TRUE
  ) |>
  hal_search()

## End(Not run)

Build Query

Description

Initialize a query to the HAL API.

Usage

hal_query(value = "*", field = "text", ...)
hal_query(value = "*", field = "text", ...)

Arguments

`value`	A `vector` giving the topics to be searched for (see details).
`field`	A `character` string specifying the field to search within.
`...`	Currently not used.

Value

A list of class HALQuery containing at least the following components:

q: (default to "⁠text:*⁠").
fl: default to "⁠docid,label_s⁠").
wt: (default to "json").

Author(s)

N. Frerebeau

Examples

## Search for 'asie' in the 'text' field
hal_query("asie")

## Search for 'japon' and 'france' in the 'title_t' field
term <- list("japon", "france")
hal_query(term, field = "title_t")

## Search for 'Journal', and 'Histoire' or 'History' in the 'title_t' field
term <- list("Journal", c("Histoire", "History"))
hal_query(term, field = "title_t")
## Search for 'asie' in the 'text' field
hal_query("asie")

## Search for 'japon' and 'france' in the 'title_t' field
term <- list("japon", "france")
hal_query(term, field = "title_t")

## Search for 'Journal', and 'Histoire' or 'History' in the 'title_t' field
term <- list("Journal", c("Histoire", "History"))
hal_query(term, field = "title_t")

Search

Description

Usage

hal_search(query, ...)

hal_count(query, ...)

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

## S3 method for class 'HALQuery'
hal_search(
  query,
  path = "search",
  instance = NULL,
  limit = 30,
  start = 0,
  cursor = FALSE,
  simplify = TRUE,
  progress = getOption("odyssey.progress"),
  verbose = getOption("odyssey.verbose"),
  ...
)
hal_search(query, ...)

hal_count(query, ...)

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

## S3 method for class 'HALQuery'
hal_search(
  query,
  path = "search",
  instance = NULL,
  limit = 30,
  start = 0,
  cursor = FALSE,
  simplify = TRUE,
  progress = getOption("odyssey.progress"),
  verbose = getOption("odyssey.verbose"),
  ...
)

Arguments

`query`	An object of class `HALQuery` (typically returned by `hal_query()`).
`...`	Currently not used.
`path`	description
`instance`	description
`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`".
`simplify`	A `logical` scalar. If `TRUE` (the default), (try to) coerce to a `data.frame`.
`progress`	A `logical` scalar: should a progress bar for for the request be printed?
`verbose`	A `logical` scalar: should extra information be reported?

Value

hal_count() returns an integer (the number of results).
hal_search() returns a (list of) data.frame (according to simplify).

Author(s)

N. Frerebeau

References

Apache Solr documentation.

HAL search documentation.

HAL reference frame documentation.

Examples

## Not run: 
## Simple search
topic <- list("archéologie", "Celtes", "France") # Combined with AND
## Get the first ten results
docs <- hal_query(topic) |>
  hal_search(limit = 10)
## Get all results
docs <- hal_query(topic) |>
  hal_search(limit = 30, cursor = TRUE)

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

## 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")
labs <- 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", instance = "structure", limit = 15)

## End(Not run)
## Not run: 
## Simple search
topic <- list("archéologie", "Celtes", "France") # Combined with AND
## Get the first ten results
docs <- hal_query(topic) |>
  hal_search(limit = 10)
## Get all results
docs <- hal_query(topic) |>
  hal_search(limit = 30, cursor = TRUE)

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

## 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")
labs <- 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", instance = "structure", limit = 15)

## End(Not run)

Select Fields

Description

Select Fields

Usage

hal_select(query, ...)

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

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

Arguments

`query`	An object of class `HALQuery` (typically returned by `hal_query()`).
`...`	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

## Select fields
hal_query() |> hal_select("label_s")

(q <- hal_query() |> hal_select("halId_s", "uri_s"))

## Update query
hal_select(q, "docType_s")
## Select fields
hal_query() |> hal_select("label_s")

(q <- hal_query() |> hal_select("halId_s", "uri_s"))

## Update query
hal_select(q, "docType_s")

Sort Results

Description

Sort Results

Usage

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

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

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

Arguments

`query`	An object of class `HALQuery` (typically returned by `hal_query()`).
`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

## Select fields
(q <- hal_query() |> hal_sort("docid"))

## Update query
hal_sort(q, "producedDate_tdate", decreasing = TRUE)
## Select fields
(q <- hal_query() |> hal_sort("docid"))

## Update query
hal_sort(q, "producedDate_tdate", decreasing = TRUE)

Operators

Description

Operators

Usage

x %OR% y

x %AND% y

x %NOT% y

x %BY% y

x %IN% y

x %TO% y
x %OR% y

x %AND% y

x %NOT% y

x %BY% y

x %IN% y

x %TO% y

Arguments

x, y

A (list of) character vector.

Value

A character string.

Author(s)

N. Frerebeau

Examples

## Infix operators are composed left to right
c("aluminium", "fer") %BY% 3 %IN% "title_t"

## We need parenthesis
("ecology" %IN% "title_t") %AND% ("cell" %IN% "text")

## A vector allows to combine all the terms with OR
c("Histoire", "History") %IN% "title_t"

## A list allows to combine terms with AND
list("Paris", "France", "history") %NOT% list("Texas", "history")
## Infix operators are composed left to right
c("aluminium", "fer") %BY% 3 %IN% "title_t"

## We need parenthesis
("ecology" %IN% "title_t") %AND% ("cell" %IN% "text")

## A vector allows to combine all the terms with OR
c("Histoire", "History") %IN% "title_t"

## A list allows to combine terms with AND
list("Paris", "France", "history") %NOT% list("Texas", "history")

Package 'odyssey'

Help Index

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

Search

Description

Usage

Arguments

Value

Author(s)

References

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

Operators

Description

Usage

Arguments

Value

Author(s)

See Also

Examples