1. Overview and vision

2. Development status

• January 2019: Inception. Code source managed on GitHub.
• June 2019: Published on CRAN.

3. Credits

© 2019, Emmanuel Blondel

Package distributed under MIT license.

4. User guide

4.1 How to install zen4R in R

For now, the package can be installed from Github

install.packages("remotes")

Once the remotes 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("remotes")
install_github("eblondel/zen4R")

For Linux/OSX, make sure to install the sodium package as follows:

sudo apt-get install -y libsodium-dev

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 token.

zenodo <- ZenodoManager$new()

4.3 Query Zenodo deposited records

4.3.1 Get Depositions

The generic way to query depositions is to use the method getDepositions. If specified with no parameter, all depositions will be returned:

my_zenodo_records <- zenodo$getDepositions()

4.3.2 Get Deposition By Concept DOI

It is possible to interrogate and get a Zenodo record with its concept DOI (generic DOI common to all versions of a record):

my_rec <- zenodo$getDepositionByConceptDOI("<my_concept_doi>")

4.3.3 Get Deposition By DOI

It is possible to interrogate and get a Zenodo record with its DOI (record version-specific DOI):

my_rec <- zenodo$getDepositionByDOI("<my_doi>")

4.3.4 Get Deposition By Zenodo ID

It is possible to interrogate and get a Zenodo record with its internal ID:

my_rec <- zenodo$getDepositionById(id)

4.3.4 Get versions of a Zenodo record

For a given record, it’s possible to get the list of versions of this record:

my_rec <- zenodo$getDepositionByConceptDOI("<some_concept_doi>")
my_rec$getVersions()

The list of versions is provided as data.frame given the date of publication, version number, and DOI of each version.

4.4 Manage Zenodo record depositions

4.4.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 an internal id and a DOI have 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.4.2 Fill a record

4.4.3 Deposit/update a record

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

myrec <- zenodo$depositRecord(myrec)

In order to apply further methods on this record (e.g. upload a file, publish/delete a record), you need to get the output of the function depositRecord (see example above) since after the deposition Zenodo will return the record that now contains an internal id required to identify and apply further actions. This id can be inspected with myrec$id.

Instead, if you don’t get the output of depositRecord and try to upload files or publish/delete the record based on the local record you handle (built upon ZenodoRecord$new()), this will not work. Because it is a local record, the id of the record will still be NULL, with no value assigned by Zenodo, and Zenodo will be unable to identify which record needs to be handled.

4.4.4 Delete a record

4.4.5 Publish a record

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

myrec <- 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:

myrec <- zenodo$depositRecord(myrec, publish = TRUE)

4.4.6 Edit/Update a published record

It is possible to update metadata of a published record, but not to modify the files associated to it. In order to update metadata of a published record, the state of this record has to be modified to make it editable. For that, use the editRecord function giving the id of the record to edit:

myrec <- zenodo$editRecord(myrec$id)

Next, perform your metadata updates, and re-deposit the record

myrec$setTitle("newtitle")
myrec <- zenodo$depositRecord(myrec, publish = FALSE)

Since the record has been switched back to draft state, the record has to be re-published otherwise it will remain a draft record in your Zenodo user session.

4.4.7 Discard changes of a draft record

In case you started editing a record and you want to discard changes on it, it is possible to do it with the discardChanges.

zenodo$discardChanges(myrec$id)

4.4.8 Create a new version record

To create a new record version, you should first retrieve the record for which you want to create a new version. You can retrieve this record with methods based on DOI such as getDepositionByConceptDOI (to get a record based on concept DOI) or getDepositionByDOI; or by Zenodo id with getDepositionById :

#get record by DOI
myrec <- zenodo$getDepositionByDOI("<some doi>")

#edit myrec with updated metadata for the new version
#...

#create new version
myrec <- zenodo$depositRecordVersion(myrec, delete_latest_files = TRUE, files = "newversion.csv", publish = FALSE)

The function depositRecordVersion will create a new version for the published record. The parameter delete_latest_files (default = TRUE) allows to delete latest files (knowing that a new record version expect to have different file(s) than the latest version). The files parameter allows to list the files to be uploaded. As for the depositRecord, it is possible to publish the record with the publish paramater.

4.5 Manage Zenodo record deposition files

4.5.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 deposit to which the file should be uploaded:

zenodo$uploadFile("path/to/your/file", record = myrec)

4.5.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.5.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)

4.6 Export Zenodo record metadata

4.6.1 Export Zenodo record metadata by format

To export a record in a given format, they are two ways:

#using the generic exportAs
myrec$exportAs("BibTeX", filename = "myfilename")

#using the format-specific wrapper
myrec$exportAsBibTeX(filename = "myfilename")

The filename provided should not include the file extension that is managed by zen4R, depending on the chosen format.

4.6.2 Export Zenodo record metadata - all formats

To export a record in all above metadata formats:

myrec$exportAsAllFormats(filename = "myfilename")

The filename provided should not include the file extension that is managed by zen4R, depending on the format.

4.7 Browse Zenodo controlled vocabularies

4.7.1 Communities

communities <- zenodo$getCommunities()

4.7.2 Licenses

licenses <- zenodo$getLicenses()

4.7.3 Funders

funders <- zenodo$getFunders()

4.7.4 Grants

grants <- zenodo$getGrants()

4.8 Query Zenodo published records

4.8.1 Get Records

The generic way to query records is to use the method getRecords

my_zenodo_records <- zenodo$getRecords(q = "<my_elastic_search_query>")

4.8.2 Get Record By Concept DOI

It is possible to interrogate and get a Zenodo record with its concept DOI (generic DOI common to all versions of a record):

my_rec <- zenodo$getRecordByConceptDOI("<my_concept_doi>")

4.8.3 Get Record By DOI

It is possible to interrogate and get a Zenodo record with its DOI (record version-specific DOI):

my_rec <- zenodo$getRecordByDOI("<my_doi>")

4.8.4 Get Record By Zenodo ID

It is possible to interrogate and get a Zenodo record with its internal ID:

my_rec <- zenodo$getRecordById(id)

4.9 Download files from Zenodo records

5. Issue reporting