Provides an Interface to Zenodo REST API, including management of depositions, attribution of DOIs by ‘Zenodo’ and upload of files.
For zen4R sponsoring/funding new developments, enhancements, support requests, please contact me by e-mail
Many thanks to the following organizations that have provided
fundings for strenghtening the zen4R
package:
The following projects have contributed to strenghten
zen4R
:
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 Query Zenodo deposited records
4.3.1 Get
Depositions
4.3.2 Get Deposition By
Concept DOI
4.3.3 Get Deposition By
DOI
4.3.4 Get
Deposition By Zenodo record ID
4.3.5 Get Deposition versions
4.4 Manage Zenodo record
depositions
4.4.1
Create an empty record
4.4.2 Fill a record
4.4.3 Deposit/Update a record
4.4.4 Delete a record
4.4.5 Publish a record
4.4.6 Edit/Update a published
record
4.4.7 Discard
changes of a draft record
4.4.8 Create a new record version
4.5 Manage Zenodo record deposition
files
4.5.1 Upload
file
4.5.2 Get
files
4.5.3 Delete
file
4.6 Manage Zenodo
record communities
4.6.1 Submit a published
record to communities
4.6.2 Submit a draft record to a
community
4.7 Export Zenodo
record metadata
4.7.1 Export Zenodo record
metadata by format
4.7.2 Export Zenodo record
metadata - all formats
4.8
Browse Zenodo controlled vocabularies
4.8.1 Communities
4.8.2 Licenses
4.8.3 Funders
4.8.4 Grants
4.9 Query Zenodo published records
4.9.1 Get Records
4.9.2 Get Record By
Concept DOI
4.9.3
Get Record By DOI
4.9.4 Get Record By ID
4.10 Download files from Zenodo
records
4.11 Manage
requests
5. Issue
reporting
6. User
support
The zen4R package offers an R interface to the Zenodo e-infrastructure. It supports most of the Zenodo features including the management of metadata records (including versioning), upload/download of files, and assignment of Digital Object Identifier(s) (DOIs), statistics, community management.
zen4R is jointly developed together with the geoflow which intends to facilitate and automate the production of geographic metadata documents and their associated datasources, where zen4R is used to assign DOIs and cross-reference these DOIs in other metadata documents such as geographic metadata (ISO 19115/19139) hosted in metadata catalogues and open data portals.
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. For citation, please use
the DOI:
For now, the package can be installed from Github
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).
For Linux/OSX, make sure to install the sodium
package
as follows:
sudo apt-get install -y libsodium-dev
The main entry point of zen4R
is the
ZenodoManager
. Some basic methods, such as listing licenses
known by Zenodo, do not require the token.
To use deposit functions of zen4R
, you will need to
specify the token
. This token can be created here.
zenodo <- ZenodoManager$new(
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
If you want to use the Zenodo
sandbox to test record management before going with the production
Zenodo e-infrastructure, you can specify sandbox = TRUE
in
the ZenodoManager
.
Important: To use the Zenodo sandbox, you need to set up a sandbox account separately from Zenodo, create a separate personal access token to the sandbox API, and you must confirm via the confirmation link this account separately in order to be able to test your record management on this clone of Zenodo.
The below code instructs how to connect to the Sandbox Zenodo e-infrastructure:
zen4R offers several methods to query Zenodo 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()
It is also possible to specify an ElasticSearch query using the
q
parameter. For helpers and query examples, please consult
this Zenodo Search
guide.
Since the Zenodo API is paginated, an extra parameter
size
can be specified to indicate the number of records to
be queried by page (default value is 10).
By default, the Zenodo API will return only the latest versions of a
record. It is possible to retrieve all versions of records by specifying
all_versions = FALSE
.
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>")
It is possible to interrogate and get a Zenodo record with its DOI (record version-specific DOI):
my_rec <- zenodo$getDepositionByDOI("<my_doi>")
It is possible to interrogate and get a Zenodo record with its internal ID:
my_rec <- zenodo$getDepositionById(id)
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.
Note: This function is not provided through the Zenodo API, but exploits to Zenodo website and has been added to zen4R to facilitate the browsing of record versions.
It is possible to create and deposit an empty record, ready for editing. For that, run the following R code:
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:
The next section explains how to fill the record with metadata elements.
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("zen4R")
myrec$addAdditionalTitle("This is an alternative title", type = "alternative-title")
myrec$setDescription("Interface to 'Zenodo' REST API")
myrec$addAdditionalDescription("This is an abstract", type = "abstract")
myrec$setPublicationDate(Sys.Date())
myrec$setResourceType("software")
myrec$addCreator(firstname = "Emmanuel", lastname = "Blondel", role = "datamanager", orcid = "0000-0002-5870-5762")
myrec$addContributor(firstname = "Peter", lastname = "Lead", role = "workpackageleader")
myrec$addContributor(firstname = "Frank", "Super", role = "supervisor")
myrec$setLicense("mit", sandbox = TRUE)
myrec$setKeywords(c("R","package","software"))
myrec$addReference("Author et al., 2019. Title")
myrec$addReference("Fulano et al., 2018. Título")
myrec$setPublisher("CRAN")
myrec$setVersion("0.10")
myrec$addGrant("00k4n6c32::862409", sandbox = TRUE)
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#41-how-to-install-zen4r-in-r", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#42-connect-to-zenodo-rest-api", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#43-query-zenodo-deposited-records", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#44-manage-zenodo-record-depositions", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#45-manage-zenodo-record-deposition-files", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#46-export-zenodo-record-metadata", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#47-browse-zenodo-controlled-vocabularies", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#48-query-zenodo-published-records", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#49-download-files-from-zenodo-records", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#user_guide", scheme = "url", "ispartof", "publication-book")
Once the record is edited/updated, you can deposit it on Zenodo with the following code:
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.
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:
To publish a deposited record and make it available publicly online on Zenodo, the following method can be run:
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
:
The publication of a record requires at least to have uploaded at least one file for this record. See section 4.4.1 Upload file.
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.
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)
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.
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:
To get the list of files attached to a record, you can specify the
following method adding the record id
:
This retrieves a list of files. Each file has a unique
id
, that can be used to for file deletion.
With the move to Invenio, the addition of a record to a community is not anymore managed as part of the metadata. The way to manage communities will differ depending on the status of the record you want to add to a community.
For a record already published (with a DOI), it is very
straighforward to submit it to communities (whether or not you are the
manager of these communities). To do so, run the following code over
your record
:
In case a community name doesn’t match an existing community, some warning wil be raised without any blocking error.
As submitter of a record to a community, you have privileges to cancel this request. As manager of a community, you have privileges either to accept or decline a request to add a record to a community. If you want to learn about requests management, please see section 4.11.
Adding a draft record to a community is possible with the new Zenodo platform. This method is ‘kind of’ analog of what was possible with the legacy Zenodo and zen4R version < 0.10. Before, the addition of a draft record to a community was part of the metadata elements. With the new Zenodo, thi action is done with 2 different methods:
Indeed, adding a draft deposit/record to a community means now that
you are requesting a record to be reviewed for publication in a
community. The latter submitRecordForReview
adds a review
step before the record publication. This is materialized by a request
for addition to the community (as above), but with a review to be
performed by the manager. This action has several implications:
Note that:
For a given Zenodo record, zen4R let you export
the metadata in a metadata file, with a series of exportAs*
methods.
The metadata formats supported are: BibTeX
,
CSL
, DataCite
, DublinCore
,
DCAT
, JSON
, JSON-LD
,
GeoJSON
, MARCXML
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.
funders <- zenodo$getFunders()
some_funders <- ZENODO$getFundersByName("EU")
some_funder <-ZENODO$getFunderById("04facnr46")
zen4R offers several methods to query Zenodo records.
The generic way to query records is to use the method
getRecords
my_zenodo_records <- zenodo$getRecords(q = "<my_elastic_search_query>")
The q
parameter should be an ElasticSearch query. For
helpers and query examples, please consult this Zenodo Search
guide.
Since the Zenodo API is paginated, an extra parameter
size
can be specified to indicate the number of records to
be queried by page (default value is 10).
By default, the Zenodo API will return only the latest versions of a
record. It is possible to retrieve all versions of records by specifying
all_versions = FALSE
.
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>")
It is possible to interrogate and get a Zenodo record with its DOI (record version-specific DOI):
my_rec <- zenodo$getRecordByDOI("<my_doi>")
zen4R offers methods to download files Zenodo published records.
Being published records, the latter and their files are accessible
without any user token using
zenodo <- ZenodoManager$new(logger = "INFO")
. Files can
be then downloaded either from a Zenodo record
object
(fetched with getRecordByDOI
):
rec <- zenodo$getRecordByDOI("10.5281/zenodo.3378733")
files <- rec$listFiles(pretty = TRUE)
#create a folder where to download my files
dir.create("download_zenodo")
#download files
rec$downloadFiles(path = "download_zenodo")
downloaded_files <- list.files("download_zenodo")
or using the shortcut function download_zenodo
:
#create a folder where to download my files
dir.create("download_zenodo")
#download files with shortcut function 'download_zenodo'
download_zenodo(path = "download_zenodo", "10.5281/zenodo.3378733")
downloaded_files <- list.files("download_zenodo")
Download can be also be done in parallel with parallel
package, depending on the plateform. See below examples:
library(parallel)
#download files as parallel using a cluster approach (for both Unix/Win systems)
download_zenodo("10.5281/zenodo.2547036", parallel = TRUE, parallel_handler = parLapply, cl = makeCluster(2))
mclapply
)In Zenodo, requests refer essentially to requests made to add records to a community. Depending on your privileges, you will be able to perform different kind of operations over requests:
The operations on requests (cancel
, accept
,
decline
) require to get the request ID. To get such ID, you
first need to search over requests.
zen_com = zenodo$getCommunityById("openfair)
reqs = zenodo$getRequests(q = sprintf("status:submitted AND receiver.community:%s AND topic.record:%s", zen_com$id, record$id))
The above query returned only one request, that you can now cancel:
zen_com = zenodo$getCommunityById("openfair)
reqs = zenodo$getRequests(q = sprintf("status:submitted AND receiver.community:%s", zen_com$id))
and then decided whether you want to accept or decline the requests. The code below assumes we got 2 requests, let’s accept the first, and decline the second:
ZENODO$acceptRequest(reqs[[1]]$id, message = "Thank you for your request, your record has been added to 'openfair' community")
ZENODO$deleteRequest(reqs[[2]]$id, message = "Unfortunately your record doesn't fulfill our community standards")
In the case of a request to community made on a draft record (see
section 4.6.2), if the community manager accepts the request, the record
will be published. If the request is declined , you may want to
review/edit the record and resubmit it again (see section 4.6.2 with
method submitRecordForReview
).
Do not hesitate to ask your question at https://github.com/eblondel/zen4R/discussions