depositsClient

An R6 client for managing deposits on external services, currently including Figshare and Zenodo. Use of a 'deposits' client is controlled by the methods listed below. Those looking for help with client usage are advised to head to that section.

Value

A depositsClient class (R6 class)

Public fields

service: (character) of deposits host service.
sandbox: (logical) Connect client with sandbox if TRUE (zenodo only)
deposits: (data.frame) Current deposits hosted on service, one row per deposit.
frictionless: (logical) Default behaviour of TRUE assumes uploads are data files in rectangular form, able to be described by frictionless metadata. frictionless integration is by-passed when this parameter if FALSE.
url_base: (character) Base URL of host service API
url_service: (character) URL of deposit service
id: (integer) Deposit identifier from host service.
headers: (list) list of named headers
hostdata: (list) Data as stored by host platform
metadata: holds list of DCMI-compliant metadata.

Methods

Public methods

depositsClient$new()
depositsClient$print()
depositsClient$deposits_methods()
depositsClient$deposits_list()
depositsClient$deposits_search()
depositsClient$deposit_delete()
depositsClient$deposit_fill_metadata()
depositsClient$deposit_new()
depositsClient$deposit_service()
depositsClient$deposit_update()
depositsClient$deposit_upload_file()
depositsClient$deposit_retrieve()
depositsClient$deposit_download_file()
depositsClient$deposit_update_frictionless()

Method `new()`

Create a new depositsClient object, as an R6 client with methods listed via deposits_emthods().

Usage

depositsClient$new(service, metadata = NULL, sandbox = FALSE, headers = NULL)

Arguments

service

(character) Name of a deposits service (see deposits_services).

metadata

Either of one two possible ways of defining metadata:

The name (or full path) or a local file containing metadata constructed with deposits_metadata_template;
A names list of metadata with names matching values given by dcmi_terms, and values specified as individual character strings or lists for multiple entries.

sandbox

If TRUE, connect client to sandbox, rather than actual API endpoint (for "zenodo" only).

headers

Any acceptable headers. See examples in httr2 package.

Returns

A new depositsClient object

Examples

\dontrun{
cli <- depositsClient$new (service = "zenodo", sandbox = TRUE)
# List methods of client:
cli$deposits_methods ()
# List all current deposits associated with user token:
cli$deposits_list ()
}

Method `print()`

print method for the depositsClient class, providing an on-screen overview of current contents and structure of client.

Usage

depositsClient$print(x, ...)

Arguments

x: self
...: ignored

Method `deposits_methods()`

List public methods of a 'deposits' client.

Usage

depositsClient$deposits_methods()

Returns

Nothing; methods are listed on screen.

Method `deposits_list()`

Update 'deposits' item of current deposits for given service. The list of deposits contained within the "deposits" item of a client may not be up-to-date; this method can be used for force synchronisation with the external service, so that "deposits" lists all current deposits.

Usage

depositsClient$deposits_list()

Returns

(Invisibly) Updated 'deposits' client

Examples

\dontrun{
cli <- depositsClient$new (service = "zenodo", sandbox = TRUE)
print (cli)
# ... then if "Current deposits" does not seem up-to-date:
cli$deposits_list ()
# That will ensure that all external deposits are then listed,
# and can be viewed with:
cli$deposits
}

Method `deposits_search()`

Search all public deposits.

Usage

depositsClient$deposits_search(
  search_string = NULL,
  page_size = 10L,
  page_number = 1L,
  ...
)

Arguments

search_string

Single string to search for

page_size

Number of records to return in one page

page_number

Starting page for return results; used in combination with 'page_size' for pagination.

...

Named pairs of query parameters. Zenodo parameters are described at https://developers.zenodo.org/#list36, and currently include:

status: either "draft" or "published"
sort: either "bestmatch" (the default) or "mostrecent"
all_versions: Either "true" or "false"
communities: Search for deposits only within specified communities
type: Return deposits only of specified type
subtype: Return deposits only of specified subtype
bound: A geolocation bounding box
custom: Custom keywords

Figshare parameters are described at https://docs.figshare.com/#articles_search, and currently include:

resource_doi: Only return deposits matching this 'resource_doi'
item_type: Return deopsits of specified type (as integer).
doi: Only return deposits matching this DOI
handle: Only return deposits matching this handle
project_id: Only return deposits from within specified project
order: Order for sorting results; one of "published_date", "modified_date", "views", "shares", "downloads", or "cites"
search_for: Search term.
order_direction: "asc" or "desc"
institution: Only return deposits from specified institution (as integer)
group: Only return deposits from specified group (as integer)
published_since: Only return deposits published since specified date (as YYYY-MM-DD)
modified_since: Only return deposits modified since specified date (as YYYY-MM-DD)

Returns

A data.frame of data on deposits matching search parameters (with format depending on the deposits service.)

Examples

\dontrun{
cli <- depositsClient$new (service = "figshare")
search_results <- cli$deposits_search (
    search_string = "Text string query",
    page_size = 5L
)
# The 'search_string' can be used to specify precise searches:
cli <- depositsClient$new (service = "zenodo")
search_results <-
   cli$deposits_search ("keywords='frictionlessdata'&type='dataset'")
}

Method `deposit_delete()`

Deleted a specified deposit from the remote service. This removes the deposits from the associated service, along with all corresponding 'hostdata' in the local client.

Usage

depositsClient$deposit_delete(deposit_id = NULL)

Arguments

deposit_id: Integer identifier of deposit (generally obtained from list_deposits method).

Returns

(Invisibly) Updated 'deposits' client

Method `deposit_fill_metadata()`

Fill deposits client with metadata.

Usage

depositsClient$deposit_fill_metadata(metadata = NULL)

Arguments

metadata

Either one of two possible ways of defining metadata:

The name (or full path) or a local file containing metadata constructed with deposits_metadata_template;
A names list of metadata with names matching values given by dcmi_terms, and values specified as individual character strings or lists for multiple entries.

Returns

(Invisibly) Updated deposits client with metadata inserted.

Method `deposit_new()`

Initiate a new deposit on the external deposits service.

Usage

depositsClient$deposit_new(quiet = FALSE)

Arguments

quiet: If FALSE (default), print integer identifier of newly created deposit.

Returns

(Invisibly) Updated deposits client which includes data on new deposit

Method `deposit_service()`

Switch external services associated with a depositsClient object.

Usage

depositsClient$deposit_service(service = NULL, sandbox = FALSE, headers = NULL)

Arguments

service: (character) Name of a deposits service (see deposits_services).
sandbox: If TRUE, connect client to sandbox, rather than actual API endpoint (for "zenodo" only).
headers: Any acceptable headers. See examples in httr2 package.

Returns

(Invisibly) Updated deposits client.

Method `deposit_update()`

Update local metadata by downloading from specified deposit. This can be used, for example, to synchronise local client metadata after they have been modified through other methods, such as online through the service's web interface.

Usage

depositsClient$deposit_update(deposit_id = NULL)

Arguments

deposit_id: The 'id' number of deposit to update. If not specified, the 'id' value of current deposits client is used.

Returns

(Invisibly) Updated deposits client.

Method `deposit_upload_file()`

Upload a local file to an specified deposit.

Usage

depositsClient$deposit_upload_file(
  path = NULL,
  deposit_id = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

path: Path to local file to be uploaded. If the file to be uploaded is able to be read as a tabular data file, an associated frictionless "datapackage.json" file will also be uploaded if it exists, or created if it does not. The metadata within a client will also be used to fill or update any metadata within the "datapackage.json" file.
deposit_id: The 'id' number of deposit which file is to be uploaded to. If not specified, the 'id' value of current deposits client is used.
overwrite: Set to TRUE to update existing files by overwriting.
quiet: If FALSE (default), display diagnostic information on screen.

Returns

(Invisibly) Updated 'deposits' client

Examples

\dontrun{
# Initiate deposit and fill with metadata:
metadata <- list (
    Title = "Iris Dataset",
    Creator = "Edgar Anderson",
    Publisher = "American Iris Society",
    Source = "https://doi.org/10.1111/j.1469-1809.1936.tb02137.x"
)
cli <- depositsClient$new (
    service = "zenodo",
    sandbox = TRUE,
    metadata = metadata
)
cli$deposit_new ()

# Create some local data and upload to deposit:
path <- fs::path (fs::path_temp (), "iris.csv")
write.csv (datasets::iris, path)
cli$deposit_upload_file (path = path)

# Confirm that uploaded files include \pkg{frictionless}
# "datapackage.json" file, and also that local version has been
# created:
cli$hostdata$files
fs::dir_ls (fs::path_temp (), regexp = "datapackage")
}

Method `deposit_retrieve()`

Retrieve information on specified deposit.

Usage

depositsClient$deposit_retrieve(deposit_id, quiet = FALSE)

Arguments

deposit_id: The 'id' number of deposit for which information is to be retrieved.
quiet: If FALSE (default), display information on screen on any issues encountered in retrieving deposit.

Returns

(Invisibly) Updated 'deposits' client

Method `deposit_download_file()`

Download a specified 'filename' from a deposit.

Usage

depositsClient$deposit_download_file(
  filename,
  deposit_id = NULL,
  path = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

filename: The name of the file to be download as specified in the deposit.
deposit_id: The 'id' number of deposit which file is to be downloaded from. If not specified, the 'id' value of current deposits client is used.
path: The local directory where file is to be downloaded.
overwrite: Do not overwrite existing files unless set to TRUE.
quiet: If FALSE, display download progress.

Returns

The full path of the downloaded file.

Method `deposit_update_frictionless()`

Update both local and remote "datapackage.json" files with contents of client metadata. This function is intended to be used when client itself is used to update metadata, in order for any local changes to be propagated through to the frictionless "datapackage.json" file(s).

Usage

depositsClient$deposit_update_frictionless(deposit_id = NULL, path = NULL)

Arguments

deposit_id: The 'id' number of deposit to update. If not specified, the 'id' value of current deposits client is used.
path: (Optional) path to local directory containing deposit data and a frictionless "datapackage.json" file. If specified, that local "datapackage.json" will be updated, and the updated version then uploaded to the deposits service.

Returns

(Invisibly) Updated deposits client.

Examples

if (FALSE) {
# make a client
cli <- depositsClient$new ("zenodo") # or:
cli <- depositsClient$new ("figshare")
print (cli)

# methods
cli$deposits_list ()

# Fill depositsClient metadata
metadata <- list (
    title = "New Title",
    abstract = "This is the abstract",
    creator = list ("A. Person", "B. Person")
)
cli$deposit_fill_metadata (metadata)
print (cli)

# or pass metadata directly at construction of new client
cli <- depositsClient$new ("figshare", metadata = metadata)
}

## ------------------------------------------------
## Method `depositsClient$new`
## ------------------------------------------------

if (FALSE) {
cli <- depositsClient$new (service = "zenodo", sandbox = TRUE)
# List methods of client:
cli$deposits_methods ()
# List all current deposits associated with user token:
cli$deposits_list ()
}

## ------------------------------------------------
## Method `depositsClient$deposits_list`
## ------------------------------------------------

if (FALSE) {
cli <- depositsClient$new (service = "zenodo", sandbox = TRUE)
print (cli)
# ... then if "Current deposits" does not seem up-to-date:
cli$deposits_list ()
# That will ensure that all external deposits are then listed,
# and can be viewed with:
cli$deposits
}

## ------------------------------------------------
## Method `depositsClient$deposits_search`
## ------------------------------------------------

if (FALSE) {
cli <- depositsClient$new (service = "figshare")
search_results <- cli$deposits_search (
    search_string = "Text string query",
    page_size = 5L
)
# The 'search_string' can be used to specify precise searches:
cli <- depositsClient$new (service = "zenodo")
search_results <-
   cli$deposits_search ("keywords='frictionlessdata'&type='dataset'")
}

## ------------------------------------------------
## Method `depositsClient$deposit_upload_file`
## ------------------------------------------------

if (FALSE) {
# Initiate deposit and fill with metadata:
metadata <- list (
    Title = "Iris Dataset",
    Creator = "Edgar Anderson",
    Publisher = "American Iris Society",
    Source = "https://doi.org/10.1111/j.1469-1809.1936.tb02137.x"
)
cli <- depositsClient$new (
    service = "zenodo",
    sandbox = TRUE,
    metadata = metadata
)
cli$deposit_new ()

# Create some local data and upload to deposit:
path <- fs::path (fs::path_temp (), "iris.csv")
write.csv (datasets::iris, path)
cli$deposit_upload_file (path = path)

# Confirm that uploaded files include \pkg{frictionless}
# "datapackage.json" file, and also that local version has been
# created:
cli$hostdata$files
fs::dir_ls (fs::path_temp (), regexp = "datapackage")
}

Value

Public fields

Methods

Public methods

Method new()

Usage

Arguments

Returns

Examples

Method print()

Usage

Arguments

Method deposits_methods()

Usage

Returns

Method deposits_list()

Usage

Returns

Examples

Method deposits_search()

Usage

Arguments

Returns

Examples

Method deposit_delete()

Usage

Arguments

Returns

Method deposit_fill_metadata()

Usage

Arguments

Returns

Method deposit_new()

Usage

Arguments

Returns

Method deposit_service()

Usage

Arguments

Returns

Method deposit_update()

Usage

Arguments

Returns

Method deposit_upload_file()

Usage

Arguments

Returns

Examples

Method deposit_retrieve()

Usage

Arguments

Returns

Method deposit_download_file()

Usage

Arguments

Returns

Method deposit_update_frictionless()

Usage

Arguments

Returns

Examples

Method `new()`

Method `print()`

Method `deposits_methods()`

Method `deposits_list()`

Method `deposits_search()`

Method `deposit_delete()`

Method `deposit_fill_metadata()`

Method `deposit_new()`

Method `deposit_service()`

Method `deposit_update()`

Method `deposit_upload_file()`

Method `deposit_retrieve()`

Method `deposit_download_file()`

Method `deposit_update_frictionless()`