Skip to contents

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


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")
}