Skip to content

Home

Jump to bottom
Emmanuel Blondel edited this page Jan 21, 2019 · 35 revisions

zen4R - R Interface to Zenodo REST API

R Interface to Zenodo REST API

If you wish to sponsor zen4R, do not hesitate to contact me

Table of contents

1. Overview
2. Package status
3. Credits
4. User guide
   4.1 Installation
   4.2 Connect to Zenodo REST API
   4.3 Manage Zenodo record depositions
      4.3.1 Create an empty record
      4.3.2 Fill a record
      4.3.3 Deposit/Update a record
      4.3.4 Delete a record
      4.3.5 Publish a record
   4.4 Manage Zenodo record deposition files
      4.4.1 Upload file
      4.4.2 Get files
      4.4.3 Delete file
5. Issue reporting

1. Overview and vision

TODO

2. Development status

Development started on 2019-01-18 on Github. Not yet on CRAN, but coming soon.

3. Credits

(c) 2019, Emmanuel Blondel

Package distributed under MIT license.

If you use zen4R, i would be very grateful if you can add a citation in your published work. By citing zen4R, beyond acknowledging the work, you contribute to make it more visible and guarantee its growing and sustainability. You can get the preferred citation by running citation("zen4R) in R.

DOI: coming soon

4. User guide

4.1 How to install zen4R in R

For now, the package can be installed from Github

install.packages("devtools")

Once the devtools package loaded, you can use the install_github to install zen4R. By default, package will be installed from master which is the current version in development (likely to be unstable).

require("devtools")
install_github("eblondel/zen4R")

4.2 Connect to Zenodo REST API

The main entry point of zen4R is the ZenodoManager. Some basic methods, such as listing licenses known by Zenodo, do not require the access_token.

zenodo <- ZenodoManager$new()

To use deposit functions of zen4R, you will need to specify the access_token. This token can be created here.

zenodo <- ZenodoManager$new(
   access_token = <your_token>, 
   logger = "INFO" # use "DEBUG" to see detailed API operation logs, use NULL if you don't want logs at all
)

By default, the zen4R logger is deactivated. To enable the logger, specify the level of log you wish as parameter of the above R code. Two logging levels are available:

  • INFO: will print the zen4R logs. Three types of messages can be distinguished: INFO, WARN, ERROR. The latter is generally associated with a stop and indicate an blocking error for the R method executed.
  • DEBUG will print the above zen4R logs, and report all logs from HTTP requests performed with cURL

4.3 Manage Zenodo record depositions

4.3.1 Create an empty record

It is possible to create and deposit an empty record, ready for editing. For that, run the following R code:

myrec <- zenodo$createEmptyRecord()

This method will return an object of class ZenodoRecord for which a DOI has been pre-defined by Zenodo. An alternate method is to create a local empty record (not deposited on Zenodo) doing:

myrec <- ZenodoRecord$new()

The next section explains how to fill the record with metadata elements.

4.3.2 Fill a record

Zenodo records can be described a set of multiple metadata elements. For a full documentation of these metadata elements, please consult the zen4R documentation with ?ZenodoRecord. The online Zenodo API documentation can be consulted as well here.

Example of record filling with metadata elements:

myrec <- ZenodoRecord$new()
myrec$setTitle("my R package")
myrec$setDescription("A description of my R package")
myrec$setUploadType("software")
myrec$addCreator(firstname = "John", lastname = "Doe", affiliation = "Independent", orcid = "0000-0000-0000-0000")
myrec$setLicense("mit")
myrec$setAccessRight("open")
myrec$setDOI("mydoi") #use this method if your DOI has been assigned elsewhere, outside Zenodo
4.3.3 Deposit/update a record

Once the record is edited/updated, you can deposit it on Zenodo with the following code:

zenodo$depositRecord(myrec)
4.3.4 Delete a record

A record deposited on Zenodo but not yet published remains in the Upload area of Zenodo (a kind of staging area where draft records are in edition). As long as it is not published, a record can be deleted from the Zenodo Upload area using:

zenodo$deleteRecord(myrec$id)
4.3.5 Publish a record

To publish a deposited record and make it available publicly online on Zenodo, the following method can be run:

zenodo$publishRecord(myrec$id)

A shortcut to publish a record is also available through the method depositRecord, specifying publish = TRUE. This method should be used with cautious giving the fact the record will go straight online on Zenodo if published. By default the parameter publish will be set to FALSE:

zenodo$depositRecord(myrec, publish = TRUE)

4.4 Manage Zenodo record deposition files

4.4.1 Upload file

With zen4R, it is very easy to upload a file to a record deposition. The record should first deposited on Zenodo. To upload a file, the following single line can be used, where the file path is specified and the record deposition id to which the file should be uploaded:

zenodo$uploadFile("path/to/your/file", myrec$id)
4.4.2 Get files

To get the list of files attached to a record, you can specify the following method adding the record id:

zen_files <- zenodo$getFiles(myrec$id)

This retrieves a list of files. Each file has a unique id, that can be used to for file deletion.

4.4.3 Delete file

The following example shows how to delete the first file attached to the record defined earlier. To delete a file, we need to specify both the record and file identifiers:

zenodo$deleteFile(myrec$id, zen_files[[1]]$id)

5. Issue reporting

Issues can be reported at https://github.com/eblondel/zen4R/issues

Clone this wiki locally