Package 'deposits'

Description

The Dublin Core Metadata Initiative defines a set of terms at https://www.dublincore.org/specifications/dublin-core/dcmi-terms/.

Usage

dcmi_terms(term = NULL)

Arguments

Value

A character vector of DCMI terms.

See Also

Other meta: deposits_metadata_template(), figshare_categories()

Description

The fields are those defined by the Dublin Core Metadata Initiative (DCMI), defined at https://www.dublincore.org/specifications/dublin-core/dcmi-terms/. The template produced by this function is in json format which can be manually edited to provide metadata for a deposit.

Usage

deposits_metadata_template(filename = NULL)

Arguments

Value

(Invisibly) TRUE if local file successfully created; otherwise FALSE.

See Also

Other meta: dcmi_terms(), figshare_categories()

Examples

filename <- tempfile (fileext = ".json")
deposits_metadata_template (filename)
# then edit that file to complete metadata

Description

List all deposits services and associated URLs

Usage

deposits_services()

Value

A data.frame with name and url values for each accessible service.

Examples

s <- deposits_services ()

Description

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

Methods

Public methods

• depositsClient$new()

• depositsClient$print()

• depositsClient$deposit_add_resource()

• depositsClient$deposit_delete()

• depositsClient$deposit_delete_file()

• depositsClient$deposit_download_file()

• depositsClient$deposit_embargo()

• depositsClient$deposit_fill_metadata()

• depositsClient$deposit_new()

• depositsClient$deposit_prereserve_doi()

• depositsClient$deposit_publish()

• depositsClient$deposit_retrieve()

• depositsClient$deposit_service()

• depositsClient$deposit_update()

• depositsClient$deposit_upload_file()

• depositsClient$deposit_version()

• depositsClient$deposits_list()

• depositsClient$deposits_methods()

• depositsClient$deposits_search()

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

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 ()

# Once a deposit has locally-stored metadata associated with it, only
# that parameter is needed.
path <- tempfile (pattern = "data") # A directory for data storage
dir.create (path)
f <- file.path (path, "beaver1.csv")
write.csv (datasets::beaver1, f, row.names = FALSE)
metadata <- list (
    creator = list (list (name = "P. S. Reynolds")),
    created = list (publisherPublication = "1994-01-01"),
    title = "Time-series analyses of beaver body temperatures",
    description = "Original source of 'beaver' dataset."
)
cli <- depositsClient$new (service = "figshare", metadata = metadata)
cli$deposit_new ()
cli$deposit_upload_file (f)

# A new deposits client may then be constructed by passing the data
# directory as the 'metadata' parameter:
cli <- depositsClient$new (metadata = path)
}

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

Method deposit_add_resource()

Generate a local "datapackage.json" file, and/or add metadata from client. A "resource" must be readable by the frictionless package, generally meaning either a 'datapackage.json' file, or a rectangular structure able to be read and represented as a data.frame. See https://docs.ropensci.org/frictionless/ for details.

Usage

depositsClient$deposit_add_resource(path)

Arguments

Returns

(Invisibly) Updated 'deposits' client

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

Returns

(Invisibly) Updated 'deposits' client

Method deposit_delete_file()

Delete a single from a deposits service.

This does not modify the "datapackage.json" file, either locally or on a service.

Usage

depositsClient$deposit_delete_file(filename)

Arguments

Returns

(Invisibly) Updated 'deposits' client

Examples

\dontrun{
# Initiate deposit and fill with metadata:
metadata <- list (
    title = "Time-series analyses of beaver body temperatures",
    description = "Original source of 'beaver2' data",
    creator = list (list (name = "P.S. Reynolds")),
    created = "1994-01-01T00:00:00",
    publisher = "Case Studies in Biometry"
)
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 (), "beaver.csv")
write.csv (datasets::beaver2, 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

# Then delete one of those files:
cli$deposit_delete_file ("datapackage.json")
}

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

Returns

The full path of the downloaded file.

Method deposit_embargo()

Embargo a deposit prior to publication.

Usage

depositsClient$deposit_embargo(
  embargo_date = NULL,
  embargo_type = c("deposit", "file"),
  embargo_reason = NULL
)

Arguments

Returns

(Invisibly) Updated deposits client with additional embargo information.

Method deposit_fill_metadata()

Fill deposits client with metadata.

Usage

depositsClient$deposit_fill_metadata(metadata = NULL)

Arguments

Returns

(Invisibly) Updated deposits client with metadata inserted.

Method deposit_new()

Initiate a new deposit on the external deposits service.

Usage

depositsClient$deposit_new(prereserve_doi = TRUE, quiet = FALSE)

Arguments

Returns

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

Method deposit_prereserve_doi()

Prereserve a DOI. This is generally done when a deposit is first initialised, via the prereserve_doi parameter. This method exists only to subsequently prereserve a DOI for deposits initiated with prereserve_doi = FALSE.

Usage

depositsClient$deposit_prereserve_doi()

Returns

(Invisibly) Updated 'deposits' client

Method deposit_publish()

Publish a deposit. This is an irreversible action which should only be called if you are really sure that you want to publish the deposit. Some aspects of published deposits can be subsequently edited, but they can never be deleted.

Usage

depositsClient$deposit_publish()

Returns

(Invisibly) Updated 'deposits' client

Method deposit_retrieve()

Retrieve a specified deposit and store information in local client.

Usage

depositsClient$deposit_retrieve(deposit_id, quiet = FALSE)

Arguments

Returns

(Invisibly) Updated 'deposits' client

Method deposit_service()

Switch external services associated with a depositsClient object.

Usage

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

Arguments

Returns

(Invisibly) Updated deposits client.

Method deposit_update()

Update a remote (online) deposit with local metadata.

Usage

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

Arguments

Returns

(Invisibly) Updated deposits client.

Method deposit_upload_file()

Upload a local file or folder to an specified deposit, or update an existing version of file with new local version.

Usage

depositsClient$deposit_upload_file(
  path = NULL,
  deposit_id = NULL,
  overwrite = FALSE,
  compress = c("no", "zip", "tar"),
  quiet = FALSE
)

Arguments

Returns

(Invisibly) Updated 'deposits' client

Examples

\dontrun{
# Initiate deposit and fill with metadata:
metadata <- list (
    title = "Time-series analyses of beaver body temperatures",
    description = "Original source of 'beaver2' data",
    creator = list (list (name = "P.S. Reynolds")),
    created = "1994-01-01T00:00:00",
    publisher = "Case Studies in Biometry"
)
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 (), "beaver.csv")
write.csv (datasets::beaver2, 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_version()

Start a new version of a published deposit, based on current client metadata. This method is not available for Figshare.

Usage

depositsClient$deposit_version()

Returns

(Invisibly) Updated 'deposits' client

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_methods()

List public methods of a 'deposits' client.

Usage

depositsClient$deposits_methods()

Returns

Nothing; methods are listed on screen.

Method deposits_search()

Search all public deposits.

Usage

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

Arguments

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

Note

This method is generally intended to be used for private deposits; that is, to edit deposits prior to publication. It is nevertheless possible to edit published deposits on Zenodo, and this method will do so if called on a public Zenodo deposit. The updated data and/or metadata will not be publicly visible until the deposit is again published with the deposit_publish() method.

Examples

## Not run: 
# 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 (list (name = "A. Person"), list (name = "B. Person"))
)
cli$deposit_fill_metadata (metadata)
print (cli)

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

## End(Not run)

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

## Not run: 
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 ()

# Once a deposit has locally-stored metadata associated with it, only
# that parameter is needed.
path <- tempfile (pattern = "data") # A directory for data storage
dir.create (path)
f <- file.path (path, "beaver1.csv")
write.csv (datasets::beaver1, f, row.names = FALSE)
metadata <- list (
    creator = list (list (name = "P. S. Reynolds")),
    created = list (publisherPublication = "1994-01-01"),
    title = "Time-series analyses of beaver body temperatures",
    description = "Original source of 'beaver' dataset."
)
cli <- depositsClient$new (service = "figshare", metadata = metadata)
cli$deposit_new ()
cli$deposit_upload_file (f)

# A new deposits client may then be constructed by passing the data
# directory as the 'metadata' parameter:
cli <- depositsClient$new (metadata = path)

## End(Not run)

## ------------------------------------------------
## Method `depositsClient$deposit_delete_file`
## ------------------------------------------------

## Not run: 
# Initiate deposit and fill with metadata:
metadata <- list (
    title = "Time-series analyses of beaver body temperatures",
    description = "Original source of 'beaver2' data",
    creator = list (list (name = "P.S. Reynolds")),
    created = "1994-01-01T00:00:00",
    publisher = "Case Studies in Biometry"
)
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 (), "beaver.csv")
write.csv (datasets::beaver2, 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

# Then delete one of those files:
cli$deposit_delete_file ("datapackage.json")

## End(Not run)

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

## Not run: 
# Initiate deposit and fill with metadata:
metadata <- list (
    title = "Time-series analyses of beaver body temperatures",
    description = "Original source of 'beaver2' data",
    creator = list (list (name = "P.S. Reynolds")),
    created = "1994-01-01T00:00:00",
    publisher = "Case Studies in Biometry"
)
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 (), "beaver.csv")
write.csv (datasets::beaver2, 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")

## End(Not run)

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

## Not run: 
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

## End(Not run)

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

## Not run: 
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'")

## End(Not run)

Description

These identifiers should then be added in deposit metadata as, for example, subject(categories=c(1,2)).

Usage

figshare_categories()

See Also

Other meta: dcmi_terms(), deposits_metadata_template()

Description

Tokens should be stored as local environment variables, optionally defined in a ⁠~/.Renviron⁠ file, and should contain the name of the desired deposits service.

Usage

get_deposits_token(service = NULL, sandbox = FALSE)

Arguments

Value

API token for nominated service.

Examples

## Not run: 
token <- get_deposits_token (service = "figshare")

## End(Not run)