Version:	2.2.2
Date:	2022-06-08
Title:	R Interface to the DataONE REST API
Description:	Provides read and write access to data and metadata from the DataONE network https://www.dataone.org of data repositories. Each DataONE repository implements a consistent repository application programming interface. Users call methods in R to access these remote repository functions, such as methods to query the metadata catalog, get access to metadata for particular data packages, and read the data objects from the data repository. Users can also insert and update data objects on repositories that support these methods.
Depends:	R (≥ 3.1.1)
Suggests:	knitr, rmarkdown, testthat, digest, openssl (≥ 0.9.3), xml2
Imports:	XML (≥ 3.95-0.1), httr, methods, stringi, stringr, datapack (≥ 1.4.0), plyr, parsedate, uuid, base64enc, jsonlite
License:	Apache License 2.0
URL:	https://github.com/DataONEorg/rdataone
BugReports:	https://github.com/DataONEorg/rdataone/issues
Collate:	'AbstractTableDescriber.R' 'auth_request.R' 'D1Node.R' 'AuthenticationManager.R' 'CNode.R' 'CertificateManager.R' 'D1Object.R' 'MNode.R' 'D1Client.R' 'EMLParser.R' 'dataone-defunct.R' 'dataone-deprecated.R' 'dataone-package.R'
Encoding:	UTF-8
VignetteBuilder:	knitr
RoxygenNote:	7.1.2
NeedsCompilation:	no
Packaged:	2022-06-10 18:48:18 UTC; sjclark
Author:	Matthew B. Jones [aut, cre], Peter Slaughter [aut], Rob Nahf [aut], Carl Boettiger [aut], Chris Jones [aut], Bryce Mecum [aut], Jeanette Clark [aut], Jordan Read [ctb], Lauren Walker [aut], Edmund Hart [ctb], Scott Chamberlain [ctb], Regents of the University of California [cph]
Maintainer:	Matthew B. Jones <jones@nceas.ucsb.edu>
Repository:	CRAN
Date/Publication:	2022-06-10 19:30:02 UTC

Base Class for Specific Metadata Parsers

Description

Classes that inherit from this class provide the format-specific ways to provide read.csv with parsing instructions.

Details

This class defines the generic methods metadata parser classes need to implement to allow proper parsing of tabular data objects. Subclasses should: 1. provide method implementations for all generics 2. register the class to the tableDescriber.registry for the formats they claim to parse. 3. provide a 'constructor' method that accepts a D1Object as the first argument - the D1Object will be the metadata object to be parsed

For example, the EMLParser registers itself as a handler for eml v2.0.0 - v2.1.1 with the following.

if (!exists("tableDescriber.registry")) tableDescriber.registry <- list() tableDescriber.registry[[ "eml://ecoinformatics.org/eml-2.0.0" ]] <- "EMLParser" tableDescriber.registry[[ "eml://ecoinformatics.org/eml-2.0.1" ]] <- "EMLParser" tableDescriber.registry[[ "eml://ecoinformatics.org/eml-2.1.0" ]] <- "EMLParser" tableDescriber.registry[[ "eml://ecoinformatics.org/eml-2.1.1" ]] <- "EMLParser"

Note that the key in the list is the DataONE formatIdentifier that can be found at "https://cn.dataone.org/cn/v2/formats".

Subclass implementers should conform their methods to the behavior defined in the generic.

Author(s)

rnahf

Create an AuthenticationManager object

Description

Construct an instance of AuthenticationManager to provide mechanisms to load, verify, and display DataONE authentication information.

Usage

AuthenticationManager(...)

## S4 method for signature 'ANY'
AuthenticationManager()

Arguments

Value

the AuthenticationManager object

Manage DataONE authentication.

Description

AuthenticationManager provides mechanisms to validate DataONE authentication, when either a DataONE authentication token or X.509 Certificate is used.

Details

Understanding how your identity is managed is important for working with DataONE, especially to avoid unexpected results. For example, depending your authorization status, searches may return only public records, or the full set of public and private records. Object and package retrievals might fail if some or all of the objects being retrieved are private. Creating or updating objects on DataONE nodes and reserving identifiers might fail if your authorization credentials are missing or expired.

DataONE version 1.0 identifies you using CILogon-provided x509 certificates. DataONE has partnered with CILogon to provide a widely-accessible certificate issuing mechanism that allows DataONE users to use existing trusted institutional and public accounts.

DataONE version 2.0 provides an addition authentication mechanism known as authentication tokens. For information about tokens and instructions for generating a token for use with the dataone R package, view the overview document by entering the command: 'vignette("dataone-overview")'. DataONE authentication tokens can be obtained by signing in to your DataONE account at https://search.dataone.org.

CILogon recognizes many identity providers, including many universities as well as Google, so most times users new to DataONE can get certificates using one of their existing accounts. For more information about the CILogon service, see https://cilogon.org/?skin=DataONE .

Slots

obscured

Value of type "character" Is authentication disabled (obscured)?

Methods

• AuthenticationManager: Create an AuthenticationManager object.

• isAuthValid: Verify authentication for a member node.

• getToken: Get the value of the DataONE Authentication Token, if one exists.

• getCert: Get the DataONE X.509 Certificate location.

• getAuthMethod: Get the current valid authentication mechanism.

• getAuthSubject: Get the authentication subject.

• getAuthExpires: Get the expiration date of the current authentication method.

• isAuthExpired: Check if the currently valid authentication method has reached the expiration time.

• obscureAuth: Temporarily disable DataONE authentication.

• restoreAuth: Restore authentication (after being disabled with obscureAuth).

• showAuth: Display all authentication information.

• getTokenInfo: Display all authentication token information.

• getCertInfo: Display all X.509 certificate information.

See Also

dataone package description.

Create a CNode object.

Description

Create a CNode object.

Usage

CNode(x, ...)

## S4 method for signature 'ANY'
CNode()

## S4 method for signature 'character'
CNode(x)

Arguments

Details

For an explanation of DataONE Coordinating Nodes, see the section "DataONE Environments" in the overview vignette by entering the R command: vignette("dataone-overview").

Value

the CNode object representing the DataONE environment

See Also

CNode class description.

Examples

## Not run: 
cn <- CNode("PROD")

## End(Not run)

Provides R API to DataONE Coordinating Node services.

Description

The CNode class provides methods that interact with a DataONE Coordinating Node.

Slots

endpoint

A character vector containing URL service endpoint for the Coordinating Node

services

A data.frame containing the supported service tiers for a CN

serviceUrls

A data.frame contains URL endpoints for certain services

Methods

• CNode: Construct a CNode object.

• listFormats: List all object formats registered in DataONE.

• getFormat: Get information for a single DataONE object format

• getChecksum: Get the checksum for the data object associated with the specified pid.

• listNodes: Get the list of nodes associated with a CN.

• reserveIdentifier: Reserve a identifier that is unique in the DataONE network.

• hasReservation: Checks to determine if the supplied subject is the owner of the reservation of id.

• setObsoletedBy: Set a pid as being obsoleted by another pid

• getObject: Get the bytes associated with an object on this Coordinating Node.

• getSystemMetadata: Get the bytes associated with an object on this Coordinating Node.

• describeObject: Get a list of coordinating nodes holding a given pid.

• resolve: Get a list of coordinating nodes holding a given pid.

• getMNode: Get a reference to a node based on its identifier.

• echoCredentials: Echo the credentials used to make the call.

• isAuthorized: Check if an action is authorized for the specified identifier.

See Also

dataone package description.

Create a CertificateManager object

Description

Construct an instance of CertficateManager to provide mechanisms to obtain, load, verify, and display X509 certificates. If the 'location' field is provided, then that location is interpreted as the fully qualified path to a certificate on the local filesystem, and the default locations will not be searched. If 'location' is missing, then the default Globus Grid Security Infrastructure (GSI) location is searched, which is '/tmp/x509up_u${UID}' on Unix or '${tmpdir}/x509up_u${UID}' on Windows or '${tmpdir}/x509up_u${user.name}' if '${UID}' is not defined.

Usage

CertificateManager(...)

## S4 method for signature 'ANY'
CertificateManager()

Arguments

Value

the CertificateManager object

CertficateManager provides mechanisms to obtain, load, verify, and display X509 certificates.

Description

CertficateManager provides management functions for X.509 certificates that are used to authenticate connections to DataONE nodes over SSL. The X.509 certificates are issued by a recognized Certificate Authority, typically CILogon, and include fields that provide information about the authenticated party, including the distinguished name of the subject, the dates of validity of the certificate, and other information needed for authorization decisions. Certificate validity is determined by examining the validity of the certificate signatures for each certificate in a chain leading to a trusted root certificate. Within DataONE, the current trusted root certificate authorities are CILogon and DataONE itself.

Details

Understanding how your identity is managed is important for working with DataONE, especially to avoid unexpected results. For example, depending your authorization status, searches may or may return only public records, or the full set of public and private records. Object and package retrievals might fail if some or all of the objects being retrieved are private. Creating or updating objects on DataONE nodes and reserving identifiers reservations might fail if your authorization certificate is missing or expired.

DataONE identifies you using CILogon-provided x509 certificates. DataONE has partnered with CILogon to provide a widely-accessible certificate issuing mechanism that allows DataONE users to use existing trusted institutional and public accounts.

CILogon recognizes many identity providers, including many universities as well as Google, so most times users new to DataONE can get certificates using one of their existing accounts. For more information about the CILogon service, see "https://cilogon.org/?skin=DataONE" .

X509 Certificates differ from typical username-password login schemes in that certificates can be used by more than one application, which is very useful when using more than one DataONE-enabled application. The certificates CILogon issues for DataONE are so-called "short-lived" certificates that currently expire 18 hours from the time of issuing. Typically you will want to download a fresh certificate the first time you interact with DataONE each day.

Slots

location

value of type "character", containing a path to a custom certificate location

obscuredpath

value of type "character", containing the path used to temporarily obscure a certificate

Methods

• CertificateManager: Create a CertificateManager object.

• getCertLocation: Get the file path on disk of the client certificate file.

• showClientSubject: Get DataONE Identity as Stored in the CILogon Certificate.

• isCertExpired: Determine if an X.509 certificate has expired.

• getCertExpires: Show the date and time when an X.509 certificate expires.

• downloadCert: Open the CILogon Certificate download page in the default browser.

• obscureCert: Obscure the CILogon Client Certificate.

• restoreCert: Restore the CILogon client certificate by renaming it to its original location

Author(s)

Matthew Jones, Rob Nahf

See Also

dataone package description.

Examples

## Not run: 
cm <- suppressWarnings(CertificateManager())
cert <- getCertLocation(cm)
subject <- showClientSubject(cm)
expires <- getCertExpires(cm)
isExpired <- isCertExpired(cm)
cm <- obscureCert(cm)
cm <- restoreCert(cm)

## End(Not run)

The DataONE client class used to download, update and search for data in the DataONE network.

Description

The DataONE client class used to download, update and search for data in the DataONE network.

Usage

D1Client(x, y, ...)

## S4 method for signature 'ANY,ANY'
D1Client()

## S4 method for signature 'character,ANY'
D1Client(x, y, ...)

## S4 method for signature 'character,character'
D1Client(x, y)

## S4 method for signature 'CNode,MNode'
D1Client(x, y, ...)

## S4 method for signature 'character,MNode'
D1Client(x, y, ...)

Arguments

Value

the D1Client object representing the DataONE environment

See Also

D1Client class description.

Examples

## Not run: 
cli <- D1Client("PROD", "urn:node:KNB")
cn <- CNode('STAGING2')
mn <- getMNode(cn,'urn:node:mnTestKNB')
cli <- D1Client(cn,mn)

## End(Not run)

The D1Client class contains methods that perform high level DataONE tasks

Description

The methods in the D1Client class call the low level DataONE API to perform involved tasks such as uploading all the packages in a DataPackage (i.e uploadDataPackage)

Slots

cn

The Coordinating Node associated with the D1Client object

mn

The Member Node associated with this D1Client object

Methods

• D1Client: Construct a D1Client object.

• convert.csv: Convert a DataFrame to Standard CSV.

• createDataPackage: Create a DataPackage on a DataONE Member Node.

• encodeUrlPath: Encode the Input for a URL Path Segment.

• encodeUrlQuery: Encode the Input for a URL Query Segment.

• getDataObject: Download a single data object from a DataONE Federation member node.

• getDataPackage: Download a collection of data object from the DataONE Federation member node as a DataPackage.

• getEndpoint: Return the URL endpoint for the DataONE Coordinating Node.

• getMetadataMember: Get the DataObject containing package metadata.

• getMNodeId: Get the member node identifier associated with this D1Client object.

• listMemberNodes: List DataONE Member Nodes.

• reserveIdentifier: Reserve a unique identifier in the DataONE Network.

• uploadDataObject: Upload a DataObject to a DataONE member node.

• uploadDataPackage: Upload a DataPackage to a DataONE member node.

See Also

dataone package description.

Create a D1Node object.

Description

Create a D1Node object.

Usage

D1Node(xml, ...)

## S4 method for signature 'XMLInternalElementNode'
D1Node(xml)

Arguments

Value

the Node object representing the DataONE environment

A base class for CNode and MNode.

Description

D1Node is a base class for CNode and MNode classes and contains class slots and methods that are common between these two child classes.

Slots

identifier

A character string containing a URN that uniquely identifiers the node

name

A character string containing a plain text name for the node

description

A character string describing the node

baseURL

A character string of the registered baseURL for the node, which does not include the version string

subject

A character string containing the Distinguished Name of this node, used for authentication

contactSubject

The Distinguished Name of contact person for this node

replicate

A logical flag indicating whether the node accepts replicas

type

The node type, either 'mn' or 'cn'

state

A character string that indicates whether or not the node is accessible, either 'up' or 'down'

services

A data.frame containing the service tiers supported by this node.

serviceUrls

A data.frame that contains DataONE service Urls

APIversion

A character string indicating version of the DataONE API for this node, e.g. "v2"

env

A character string, either 'prod' if this node is in the production environment, otherwise 'test'

Methods

• D1Node-initialize{initialize}: Initialize a D1Node

• D1Node: Create a MNode object representing a DataONE Member Node repository.

• archive: Change the state of an object so that it is hidden from searches.

• describeObject: Get header information for a given pid.

• getChecksum: Get the checksum for the data object associated with the specified pid.

• getObject: Get the bytes associated with an object on a node.

• getQueryEngineDescription: Query a node for the list of query engines available on the node.

• getSystemMetadata: Get the metadata describing system properties associated with an object on the Node.

• listObjects: Retrieve the list of objects that match the search parameters.

• listQueryEngines: Query a node for the list of query engines available on the node.

• ping: Test if a node is online and accepting DataONE requests.

• encodeSolr: Encode the input for Solr Queries.

• query: Search DataONE for data and metadata objects.

• isAuthorized: Check if an action is authorized for the specified identifier.

Create a D1Object instance.

Description

Create a D1Object instance.

Usage

D1Object(...)

Arguments

Value

the D1Object instance

See Also

D1Object class description.

D1Object (Defunct) is a representation of a DataObject.

Description

D1Object has been defunct in favor of datapack::DataObject, which provides a wrapper for data and associated SystemMetadata.

Slots

dataObject

A backing instance of a DataObject, to which all methods and state are proxied

Methods

• D1Object-initialize: Initialize a D1Object

• getData: Get the data content of a specified D1Object.

• getIdentifier: Get the identifier of the D1Object.

• getFormatId: Get the formatId of the D1Object

• setPublicAccess: Add a Rule to the AccessPolicy to make the object publicly readable.

• canRead: Test whether the provided subject can read an object.

• asDataFrame: Return the D1Object as a data.frame.

See Also

dataone package description.

Construct an EML parser object.

Description

Construct an EML parser object.

Usage

EMLParser(d1Object, ...)

## S4 method for signature 'D1Object'
EMLParser(d1Object)

Arguments

Handler for Parsing Table Format Details from Metadata

Description

#' Implements methods to provide parsing instructions for asDataFrame.

Details

#' handles eml formats 2.0.0 through 2.1.1

Slots

d1Object

the metadata object

xmlDocRoot

the xml representation of the metadata

Author(s)

rnahf

Create a MNode object representing a DataONE Member Node repository.

Description

Construct an instance of MNode to provide mechanisms to access, create, and update data and metadata objects on the associated Member Node.

Usage

MNode(x)

## S4 method for signature 'character'
MNode(x)

## S4 method for signature 'D1Node'
MNode(x)

Arguments

Details

If the 'x' is a string, it is treated as a URI and an attempt to find an associated Member Node at that base URL is attempted. If 'x' is a Node reference, then it is cast to a MNode instance. This typically is used from the getMNode() function from the CNode class, which is the preferred way to retrieve an instance of an MNode.

Value

the MNode object-

See Also

MNode class description.

Examples

## Not run: 
mn <- MNode("https://knb.ecoinformatics.org/knb/d1/mn/v2")

## End(Not run)

Provides R API to DataONE Member Node services.

Description

MNode provides functions that interact with a DataONE Member Node (MN). A MN is a repository that provides access for reading and writing data and metadata using the DataONE MN service API. The MN API includes functions for retrieving data and metadata based on its unique persistent identifier (pid), as well as for creating, updating, and archiving these data and metadata objects.

Details

Methods that perform write operations (such as createObject and updateObject) on the MN generally require authentication. For MNs that have implemented the DataONE API version 2.0 and higher, these operations can utilize an authentication token to provide credentials for write operations in DataONE. The authentication token is obtained from DataONE (see your account profile on https://search.dataone.org). See the vignette("dataone-overview") for details. Alternatively, the version 1.0 approach of using an X.509 certificate in a default location of the file system can also be used. This certificate provides authentication credentials from CILogon https://cilogon.org/?skin=DataONE.

Slots

endpoint

The url to access node services, which is the baseURL plus the version string

Methods

• MNode: Create a MNode object representing a DataONE Member Node repository.

• createObject: Create an object on a Member Node.

• getObject: Get the bytes associated with an object on the Member Node

• getCapabilities: Get the node capabilities description, and store the information in the MNode.

• generateIdentifier: Get a unique identifier that is generated by the Member Node repository and guaranteed to be unique.

• getPackage: Download a data package from a member node.

• updateObject: Update an object to a Member Node, by creating a new object that replaces an original.

• updateSystemMetadata: Update the system metadata associated with an object.

See Also

dataone package description.

Examples

## Not run: 
library(dataone)
library(uuid)
library(digest)
cn <- CNode("STAGING")
mn <- getMNode(cn, "urn:node:mnStageUCSB2")
mnid <- mn@identifier
# Have Dataone create an identifier for you (requires authentication)
\dontrun{
newid <- generateIdentifier(mn, "UUID")
}
# Create an identifier manually
newid <- paste("urn:uuid:", UUIDgenerate(), sep="")
testdf <- data.frame(x=1:10,y=11:20)
csvfile <- paste(tempfile(), ".csv", sep="")
write.csv(testdf, csvfile, row.names=FALSE)
f <- "text/csv"
size <- file.info(csvfile)$size
sha256 <- digest(csvfile, algo="sha256", serialize=FALSE, file=TRUE)
sysmeta <- new("SystemMetadata", identifier=newid, formatId=f, size=size,
    checksum=sha256, originMemberNode=mnid, authoritativeMemberNode=mnid)
# Upload data to DataONE (requires authentication)
\dontrun{
response <- createObject(mn, newid, csvfile, sysmeta)
}

## End(Not run)

Add a D1Object containing a data object to a DataPackage

Description

The D1Object do is added to the data package x.

Usage

## S4 method for signature 'DataPackage,D1Object'
addData(x, do, mo = as.character(NA))

Arguments

Details

If the optional mo parameter is specified, then it is assumed that this DataObject is a metadata object that describes the data object that is being added. The DataObject specified in the mo parameter will also be added to the DataPackage, if it has not already been added. Then the addData function will add a relationship to the resource map that indicates that the metadata object describes the science object, using CiTO, the Citation Typing Ontology, documents and isDocumentedBy relationships.

Examples

## Not run: 
library(dataone)
library(datapack)
library(uuid)
dp <- new("DataPackage")
d1c <- D1Client("STAGING", "urn:node:mnStageUCSB2")
# Create metadata object that describes science data
newId <- sprintf("urn:uuid:%s", UUIDgenerate())
csvfile <- system.file("extdata/sample.csv", package="dataone")
sciObj <- new("DataObject", id=newId, format="text/csv",filename=csvfile)
dp <- addData(dp, do = sciObj)

## End(Not run)

Archive an object on a Member Node or Coordinating Node, which hides it from casual searches.

Description

This method provides the ability to archive a data or metadata object on the Member Node provided in the 'mnode' parameter. Archiving removes the object from DataONE search functions, thereby making it more difficult to find without completely removing the object. Archive is intended for objects that should not be used by current researchers, but for which there is a desire to maintain a historical record, such as when journal articles might cite the object. Users can still obtain the contents of archived objects if they have the identifier, but will not discover it through searches.

Usage

archive(x, ...)

## S4 method for signature 'D1Node'
archive(x, pid)

Arguments

Details

This operation requires an X.509 certificate to be present in the default location of the file system. This certificate provides authentication credentials from CILogon https://cilogon.org/?skin=DataONE. See CertificateManager for details. For DataONE Version 2.0, an authentication token can also be used for authentication. Also, administrator privilege is required to run archive() on a DataONE Coordinating Node.

Value

The pid that was archived if successful, otherwise NULL

See Also

D1Node class description.

Examples

## Not run: 
library(dataone)
library(uuid)
library(digest)
library(datapack)
# First create a new object
cn <- CNode("STAGING")
mn <- getMNode(cn, "urn:node:mnStageUCSB2")
testdf <- data.frame(x=1:10,y=11:20)
csvfile <- paste(tempfile(), ".csv", sep="")
write.csv(testdf, csvfile, row.names=FALSE)
\dontrun{
newid <- generateIdentifier(mn, "UUID")
}
# Create an identifier manually
newid <- paste("urn:uuid:", UUIDgenerate(), sep="") 
format <- "text/csv"
size <- file.info(csvfile)$size
sha256 <- digest(csvfile, algo="sha256", serialize=FALSE, file=TRUE)
sysmeta <- new("SystemMetadata", identifier=newid, formatId=format, size=size, checksum=sha256)
sysmeta <- addAccessRule(sysmeta, "public", "read")
# Create (upload) the object to DataONE (requires authentication)
\dontrun{
create(mn, newid, csvfile, sysmeta)
# Now for demonstration purposes, archive the object
# Archive the object (requires authentication)
archivedId <- archive(mn, newid)
}

## End(Not run)

return the D1Object data as a data.frame.

Description

This method uses the provided metadata reference object for instructions on how to parse the data table (which parameters to set) 'reference' is the metadata D1Object that gives instruction on how to read the data into the dataFrame

Usage

asDataFrame(x, reference, ...)

## S4 method for signature 'D1Object,D1Object'
asDataFrame(x, reference, ...)

## S4 method for signature 'D1Object,AbstractTableDescriber'
asDataFrame(x, reference, ...)

Arguments

DELETE a resource with authenticated credentials.

Description

DELETE data at a URL using an HTTP DELETE request using authentication credentials provided in a client certificate. Authenticated access depends on the suggested openssl package. If the openssl package is not installed, then the request fails.

Usage

auth_delete(url, encode = "multipart", body = as.list(NA), node)

Arguments

Value

the HTTP response from the request

GET a resource with authenticated credentials if available.

Description

Retrieve the data at a URL using an HTTP GET request using authentication credentials provided in a client certificate. Authenticated access depends on the suggested openssl package. If the openssl package is not installed, then the request falls back to an unauthenticated request, which may fail due to insufficient permissions. Configuration options for httr/RCurl can be passed using the normal config() mechanisms to generate a config option. Use httr_options() to see a complete list of available options.

Usage

auth_get(url, nconfig = config(), node, path = NULL)

Arguments

Value

the response object from the method

Send a http HEAD request for a resource with authenticated credentials if available.

Description

Retrieve http header information for a URL using an HTTP HEAD request using authentication credentials provided in a client certificate or token. Authenticated access depends on the suggested openssl package. If the openssl package is not installed, then the request falls back to an unauthenticated request, which may fail due to insufficient permissions. Configuration options for httr/RCurl can be passed using the normal config() mechanisms to generate a config option. Use httr_options() to see a complete list of available options. Note: The HEAD method is identical to GET except that the server MUST NOT return a message-body in the response.

Usage

auth_head(url, nconfig = config(), node)

Arguments

Value

the response object from the method

POST a resource with authenticated credentials.

Description

POST data to a URL using an HTTP POST request using authentication credentials provided in a client certificate. Authenticated access depends on the suggested openssl package. If the openssl package is not installed, then the request fails.

Usage

auth_post(url, encode = "multipart", body = NULL, node)

Arguments

Value

the HTTP response from the request

PUT a resource with authenticated credentials.

Description

PUT data to a URL using an HTTP PUT request using authentication credentials provided in a client certificate. Authenticated access depends on the suggested openssl package. If the openssl package is not installed, then the request fails.

Usage

auth_put(url, encode = "multipart", body = NULL, node)

Arguments

Value

the HTTP response from the request

POST, PUT, or DELETE a resource with authenticated credentials.

Description

POST, PUT, or DELETE data to a URL using an HTTP request using authentication credentials provided in a client authentication, either via authentication token or certificate. If the user does not have a valid token or certificate, request fails.

Usage

auth_put_post_delete(method, url, encode = "multipart", body = NULL, node)

Arguments

Value

the response object from the method

Test whether the provided subject can read an object.

Description

Using the AccessPolicy, tests whether the subject has read permission for the object. This method is meant work prior to submission to a repository, and will show the permissions that would be enforced by the repository on submission. Currently it only uses the AccessPolicy to determine who can read (and not the rightsHolder field, which always can read an object). If an object has been granted read access by the special "public" subject, then all subjects have read access.

Usage

## S4 method for signature 'D1Object'
canRead(x, subject)

Arguments

Details

The subject name used in both the AccessPolicy and in the 'subject' argument to this method is a string value, but is generally formatted as an X.509 name formatted according to RFC 2253.

Value

logical TRUE if the subject has read permission, or FALSE otherwise

Convert a DataFrame to Standard CSV.

Description

Convert a DataFrame to Standard CSV.

Usage

convert.csv(x, ...)

## S4 method for signature 'D1Client'
convert.csv(x, df, ...)

Arguments

Value

the dataframe serialized as a .csv

See Also

D1Client class description.

Examples

## Not run:  
d1c <- D1Client("STAGING", "urn:node:mnStageUCSB2")
testdf <- data.frame(x=1:10,y=11:20)
sdf <- convert.csv(d1c, testdf)  

## End(Not run)

Create the Object in the DataONE System

Description

Create the Object in the DataONE System

Usage

createD1Object(x, d1Object, ...)

## S4 method for signature 'D1Client,D1Object'
createD1Object(x, d1Object)

Arguments

Value

TRUE if the object was successfully uploaded, FALSE if not.

Examples

## Not run: 
library(dataone)
library(uuid)
d1c <- D1Client("STAGING", "urn:node:mnStageUCSB2")
data <- readLines(system.file("extdata/strix-pacific-northwest.xml", package="dataone"))
dataRaw <- charToRaw(paste(data, collapse="\n"))
newid <- sprintf("urn:node:%s", UUIDgenerate())
d1o <- new("D1Object", id=newid, data=dataRaw, format="text/plain")
d1o <- setPublicAccess(d1o)
# Upload the object to DataONE (requires authentication)
uploaded <- createD1Object(d1c, d1o)

## End(Not run)

Create a DataPackage on a DataONE Member Node

Description

Upload all members of a DataPackage to DataONE.

Usage

createDataPackage(x, dataPackage, ...)

## S4 method for signature 'D1Client,DataPackage'
createDataPackage(x, dataPackage, ...)

Arguments

Value

The identifier of the uploaded package.

See Also

D1Client class description.

Examples

## Not run: 
library(dataone)
testdf <- data.frame(x=1:10,y=11:20)
csvfile <- tempfile(pattern = "file", tmpdir = tempdir(), fileext = ".csv")
write.csv(testdf, csvfile, row.names=FALSE)
d1c <- D1Client("STAGING", "urn:node:mnStageUCSB2")
dp <- new("DataPackage")
emlFile <- system.file("extdata/strix-pacific-northwest.xml", package="dataone")
emlChar <- readLines(emlFile)
emlRaw <- charToRaw(paste(emlChar, collapse="\n"))
emlId <- sprintf("urn:uuid:%s", UUIDgenerate())
metadataObj <- new("D1Object", id=emlId, format="eml://ecoinformatics.org/eml-2.1.1", data=emlRaw, 
  mnNodeId=getMNodeId(d1c))
sdf <- read.csv(csvfile)
stf <- charToRaw(convert.csv(d1c, sdf))
sciId <- sprintf("urn:uuid:%s", UUIDgenerate())
sciObj <- new("D1Object", id=sciId, format="text/csv", data=stf, mnNodeId=getMNodeId(d1c))
dp <- addMember(dp, do=sciObj, mo=metadataObj)
expect_true(is.element(sciObj@dataObject@sysmeta@identifier, getIdentifiers(dp)))
resourceMapId <- createDataPackage(d1c, dp, replicate=TRUE, public=TRUE)

## End(Not run)

Create an object on a Member Node.

Description

This method provides the ability to upload a data or metadata object to the Member Node provided in the 'mnode' parameter.

Usage

createObject(x, ...)

## S4 method for signature 'MNode'
createObject(x, pid, file = as.character(NA), sysmeta, dataobj = NULL, ...)

Arguments

Details

In the version 2.0 library and higher, this operation can utilize an 'dataone_token' option to provide credentials for write operations in DataONE. The authentication token is obtained from DataONE (see your profile on https://search.dataone.org). See the vignette("dataone-overview") for details. Alternatively, the version 1.0 approach of using an X.509 certificate in a default location of the file system can also be used. This certificate provides authentication credentials from CILogon https://cilogon.org/?skin=DataONE. See vignette("dataone-overview") for details.

Value

a character containing the identifier that was created.

See Also

https://purl.dataone.org/architecture/apis/MN_APIs.html#MNStorage.create

Examples

## Not run: 
# Create an object in the DataONE "STAGING" environment
library(dataone)
library(uuid)
library(digest)
library(datapack)
cn <- CNode("STAGING")
mn <- getMNode(cn, "urn:node:mnStageUCSB2")
# Have Dataone create an identifier for you (requires authentication)
\dontrun{
newid <- generateIdentifier(mn, "UUID")
}
# Create an identifier manually
newid <- paste("urn:uuid:", UUIDgenerate(), sep="") 
testdf <- data.frame(x=1:10,y=11:20)
csvfile <- paste(tempfile(), ".csv", sep="")
write.csv(testdf, csvfile, row.names=FALSE)
format <- "text/csv"
size <- file.info(csvfile)$size
sha256 <- digest(csvfile, algo="sha256", serialize=FALSE, file=TRUE)
sysmeta <- new("SystemMetadata", identifier=newid, formatId=format, size=size, checksum=sha256)
sysmeta <- addAccessRule(sysmeta, "public", "read")
# Upload the data to DataONE (requires authentication)
\dontrun{
createObject(mn, newid, csvfile, sysmeta)
}

## End(Not run)

Query the DataONE Solr endpoint of the Coordinating Node.

Description

The DataONE CN Solr query engine is searched using the provided query string.

Usage

d1IdentifierSearch(x, ...)

## S4 method for signature 'D1Client'
d1IdentifierSearch(x, solrQuery)

Arguments

Value

a vector of identifiers found

See Also

D1Client class description.

Examples

## Not run: 
library(dataone)
client <- new("D1Client")
result <- d1IdentifierSearch(client,solrQuery="species population diversity")

## End(Not run)

A method to query the DataONE solr endpoint of the Coordinating Node.

Description

It expects any lucene reserved characters to already be escaped with backslash. If solrQuery is a list, it is expected to have field names as attributes and search values as the values in the list.

Usage

d1SolrQuery(x, solrQuery)

## S4 method for signature 'D1Client,list'
d1SolrQuery(x, solrQuery)

## S4 method for signature 'D1Client,character'
d1SolrQuery(x, solrQuery)

Arguments

Value

the solr response (XML)

See Also

D1Client class description.

Examples

## Not run:  
library(dataone)
d1c <- D1Client("PROD", "urn:node:KNB")
queryParams <- list(q="id:doi*", rows="5", 
    fq="(abstract:chlorophyll AND dateUploaded:[2000-01-01T00:00:00Z TO NOW])", 
    fl="title,id,abstract,size,dateUploaded,attributeName")
result <- d1SolrQuery(d1c, queryParams)

## End(Not run)

This function parses a DataONE service response message for errors, and extracts and prints error information.

Description

This function parses a DataONE service response message for errors, and extracts and prints error information.

Usage

d1_errors(x)

Arguments

CharacterEncoding

Description

The character encoding used, for example "UTF-8"

Usage

data.characterEncoding(x, index, ...)

## S4 method for signature 'EMLParser,numeric'
data.characterEncoding(x, index)

Arguments

Value

the encoding used when serializing the data

Author(s)

rnahf

Data Format

Description

Get the table format family.

Usage

data.formatFamily(x, index, ...)

## S4 method for signature 'EMLParser,numeric'
data.formatFamily(x, index)

Arguments

Value

the format of the data object being described

Author(s)

rnahf

returns the attribute names

Description

THe attribute names are defined in the metadata document for the specified data table

Usage

data.tableAttributeNames(x, index, ...)

## S4 method for signature 'EMLParser,numeric'
data.tableAttributeNames(x, index)

Arguments

Value

the attribute (column) names of the data

Author(s)

rnahf

The Attribute (Header) Orientation

Description

Which way to the attribute headers run? Most data has a header row where the attribute names go across "columns", in row in which case, the return value for this method should be "columns."

Usage

data.tableAttributeOrientation(x, index, ...)

## S4 method for signature 'EMLParser,numeric'
data.tableAttributeOrientation(x, index)

Arguments

Value

legal values are "columns" | "rows"

Note

this is the opposite question from how records are organized!!

Author(s)

rnahf

returns the attributes' data storage types

Description

The attributes' data storage types are defined in the metadata document for the specified data table

Usage

data.tableAttributeStorageTypes(x, index, ...)

## S4 method for signature 'EMLParser,numeric'
data.tableAttributeStorageTypes(x, index)

Arguments

Value

the data storage types of the attributes

Author(s)

rnahf

returns the attributes' data types

Description

The attributes' data types are defined in the metadata document for the specified data table

Usage

data.tableAttributeTypes(x, index, ...)

## S4 method for signature 'EMLParser,numeric'
data.tableAttributeTypes(x, index)

Arguments

Value

the data types of the attributes

Author(s)

rnahf

Field Delimiter

Description

Get the table field delimiter.

Usage

data.tableFieldDelimiter(x, index, ...)

## S4 method for signature 'EMLParser,numeric'
data.tableFieldDelimiter(x, index)

Arguments

Value

the field delimiter(s) of the data object being described

Author(s)

rnahf

returns missing value codes

Description

the missing value codes are defined in the metadata document for the specified data table

Usage

data.tableMissingValueCodes(x, index, ...)

## S4 method for signature 'EMLParser,numeric'
data.tableMissingValueCodes(x, index)

Arguments

Value

vector of missing value codes

Author(s)

rnahf

Quote Character

Description

Get the table quote character.

Usage

data.tableQuoteCharacter(x, index, ...)

## S4 method for signature 'EMLParser,numeric'
data.tableQuoteCharacter(x, index)

Arguments

Value

the quote characters(s) for the data object being described

Author(s)

rnahf

Number of lines to skip before reading data

Description

The specified number of lines are skipped.

Usage

data.tableSkipLinesHeader(x, index, ...)

## S4 method for signature 'EMLParser,numeric'
data.tableSkipLinesHeader(x, index)

Arguments

Value

the number of lines to skip

Author(s)

rnahf

See Also

help(read.table)

Search, download and upload data to the DataONE network.

Description

The R package dataone provides read/write access to data and metadata from the DataONE network of Member Node data repositories. Member Nodes in DataONE are independent data repositories that have adopted the DataONE services for interoperability, making each of the repositories accessible to client tools such as the DataONE R Client using a standard interface. The DataONE R Client can be used to access data files and to write new data and metadata files to nodes in the DataONE network.

Classes

• AuthenticationManager: AuthenticationManager provides methods to validate DataONE authentication.

• CNode: A CNode represents a DataONE Coordinating Node and can be used to access its services.

• D1Client: The D1Client class contains methods that perform high level dataone tasks.

• D1Node: A base class for CNode and MNode.

• MNode: MNode provides functions interacting with the a DataONE Member Node repository.

Author(s)

Matthew B. Jones (NCEAS) and Peter Slaughter (NCEAS)

See Also

A description of the dataone R package is available with the command: 'vignette("dataone-overview")'.

Defunct

Description

The following items are defunct in this release of dataone and are no longer supported.

These S4 methods are defunct

• D1Object: A representation of a DataObject

  • D1Object-initialize: Initialize a D1Object

  • getData: Get the data content of a specified D1Object.

  • getIdentifier: Get the identifier of the D1Object.

  • getFormatId: Get the formatId of the D1Object

  • setPublicAccess: Add a Rule to the AccessPolicy to make the object publicly readable.

  • canRead: Test whether the provided subject can read an object.

  • asDataFrame: Return the D1Object as a data.frame.

  • setObsoletedBy: Set a pid as being obsoleted by another pid.

• D1Client: The DataONE client class used to download, update and search for data in the DataONE network

  • d1SolrQuery: A method to query the DataONE solr endpoint of the Coordinating Node.

  • d1IdentifierSearch: Query the DataONE Solr endpoint of the Coordinating Node.

  • createDataPackage: Create a DataPackage on a DataONE Member Node

  • getMN: Get a member node client based on its node identifier.

  • convert.csv: Convert a DataFrame to Standard CSV.

  • addData: Add a D1Object containing a data object to a DataPackage

  • createD1Object: Create the Object in the DataONE System

  • getD1Object: Download a data object from the DataONE Federation.

• EMLParser: A representation of a DataObject

  • documented.entityNames: The entity names associated with each table are returned.

  • documented.d1Identifiers: Get the DataONE identifier associated with each table.

  • documented.sizes: Get the table size.

• AbstractTableDescriber: Base Class for Specific Metadata Parsers

  • data.formatFamily: Get the table format family.

  • data.tableFieldDelimiter: Get the table field delimiter.

  • data.tableQuoteCharacter: Get the table quote character.

  • data.characterEncoding: The character encoding used, for example "UTF-8"

  • data.tableAttributeOrientation: Which way to the attribute headers run? Most data has a header row

  • data.tableSkipLinesHeader: The specified number of lines are skipped.

  • data.tableMissingValueCodes: the missing value codes are defined in the metadata document for

  • data.tableAttributeNames: The attribute names are defined in the metadata document for

  • data.tableAttributeTypes: The attributes' data types are defined in the metadata document for

  • data.tableAttributeStorageTypes: The attributes' data storage types are defined in the metadata document for

Deprecated

Description

The following items are deprecated in this release of dataone and will be removed in a future release

These S4 methods are deprecated

• setObsoletedBy: Set a pid as being obsoleted by another pid.

• CertificateManager: Create a CertificateManager object.

• getCertLocation: Get the file path on disk of the client certificate file.

• showClientSubject: Get DataONE Identity as Stored in the CILogon Certificate.

• isCertExpired: Determine if an X.509 certificate has expired.

• getCertExpires: Show the date and time when an X.509 certificate expires.

• downloadCert: Open the CILogon Certificate download page in the default browser.

• obscureCert: Obscure the CILogon Client Certificate.

• restoreCert: Restore the CILogon client certificate by renaming it to its original location

Efficiently get systemmetadata for an object.

Description

This method provides a lighter weight mechanism than getSystemMetadata() for a client to determine basic properties of the referenced object. This operation requires read privileges for the object specified by 'pid', as is granted with a DataONE authentication token or X.509 certificate.

Usage

describeObject(x, ...)

## S4 method for signature 'D1Node'
describeObject(x, pid)

Arguments

Value

A list of header elements

See Also

https://purl.dataone.org/architecture/apis/MN_APIs.html#MNRead.describe

Examples

## Not run: 
library(dataone)
mn_uri <- "https://knb.ecoinformatics.org/knb/d1/mn/v1"
mn <- MNode(mn_uri)
pid <- "knb.473.1"
describeObject(mn, pid)
describeObject(mn, "adfadf") # warning message when wrong pid

## End(Not run)

Get DataONE identifiers

Description

Get the DataONE identifier associated with each table

Usage

documented.d1Identifiers(x, ...)

## S4 method for signature 'EMLParser'
documented.d1Identifiers(x)

Arguments

Value

vector of dataONE identifiers

Author(s)

rnahf

Get the entity names associated with each table

Description

The entity names associated with each table are returned.

Usage

documented.entityNames(x, ...)

## S4 method for signature 'EMLParser'
documented.entityNames(x)

Arguments

Value

vector of entity names

Author(s)

rnahf

Get the sizes of the described data tables.

Description

Get the table size.

Usage

documented.sizes(x, ...)

## S4 method for signature 'EMLParser'
documented.sizes(x)

Arguments

Value

vector of data table sizes (in bytes)

Author(s)

rnahf

Open the CILogon Certificate download page in the default browser.

Description

A convenience method to take you to the CILogon download page: "https://cilogon.org/?skin=DataONE. Logging into CILogon will allow you to download your X.509 certificate to your local computer. Typically, the certificate is saved in the default Globus location for certificates (getCertLocation) and once it is there, the 'dataone' package will use the certificate for all authenticated operations. Deleting the certificate file is the equivalent of logging out.

Usage

downloadCert(x, ...)

## S4 method for signature 'CertificateManager'
downloadCert(x)

Arguments

Download an object from the DataONE Federation to Disk.

Description

A convenience method to download an object to disk.

Usage

downloadObject(x, identifier, ...)

## S4 method for signature 'D1Client'
downloadObject(x, identifier, path = getwd(), check = as.logical(TRUE))

Arguments

Details

This method performs multiple underlying calls to the DataONE repository network. CN.resolve() is called to locate the object on one or more repositories, and then each of these is accessed until success at downloading the associated SystemMetadata for the object. The SystemMetadata is used to assign a name to the file that is output to disk. If a fileName is specified in the SystemMetadata, then the file output to disk will be named according to the SystemMetadata fileName. If there is not a specified SystemMetadata fileName, the identifier will be used as the file name output to disk. If the identifier is used as the file name, a file name extension will be determined using the SystemMetadata formatID along with information from CNCore.listFormats(). If the SystemMetadata formatID is "application/octet-stream" no extension will be written.

Value

A path where the ouput file is written to.

See Also

D1Client class description.

Examples

## Not run: 
library(dataone)
d1c <- D1Client("PROD", "urn:node:KNB")
pid <- "solson.5.1"
path <- downloadObject(d1c, pid)

## End(Not run)

Echo the credentials used to make the call.

Description

This method can be used to verify the client certificate is valid and contains the expected information.

Usage

echoCredentials(x, ...)

## S4 method for signature 'CNode'
echoCredentials(x)

Arguments

Details

The authentication credentials contained in the X.509 certificate or authentication token are send with the request.

Value

A list containing authentication info.

Examples

## Not run: 
cn <- CNode("STAGING")
creds <- echoCredentials(cn)
print(creds$person$subject)

## End(Not run)

Encode the input for Solr Queries

Description

Treating all special characters and spaces as literals, backslash escape special characters, and double-quote if necessary.

Usage

encodeSolr(x, ...)

## S4 method for signature 'character'
encodeSolr(x, ...)

Arguments

Value

the encoded form of the input

Examples

encodeSolr("this & that")

Encode the Input for a URL Path Segment.

Description

Encodes the characters of the input so they are not interpreted as reserved characters in url strings. Will also encode non-ASCII unicode characters.

Usage

encodeUrlPath(x, ...)

## S4 method for signature 'D1Client'
encodeUrlPath(x, pathSegment, ...)

Arguments

Value

the encoded form of the input

See Also

D1Client class description.

Examples

## Not run: 
d1c <- D1Client("STAGING", "urn:node:mnStageUCSB2")
fullyEncodedPath <- paste0("cn/v1/object/", 
    encodeUrlPath(d1c, "doi:10.6085/AA/YBHX00_XXXITBDXMMR01_20040720.50.5"))

## End(Not run)

Encode the Input for a URL Query Segment.

Description

Encodes the characters of the input so they are not interpreted as reserved characters in url strings. Will also encode non-ASCII unicode characters.

Usage

encodeUrlQuery(x, ...)

## S4 method for signature 'D1Client'
encodeUrlQuery(x, querySegment, ...)

Arguments

Value

the encoded form of the input

See Also

D1Client class description.

Examples

## Not run: 
d1c <- D1Client("STAGING", "urn:node:mnStageUCSB2")
fullyEncodedQuery <- paste0("q=id:",
    encodeUrlQuery(d1c, encodeSolr("doi:10.6085/AA/YBHX00_XXXITBDXMMR01_20040720.50.5")))

## End(Not run)

Evaluate DataONE authentication.

Description

A valid DataONE authentication method is looked for and all authentication information is retrieved from it.

Usage

evaluateAuth(.Object, ...)

## S4 method for signature 'AuthenticationManager'
evaluateAuth(.Object, node)

Arguments

Details

If the node specified in the 'node' parameter is a DataONE v2 node or higher, then an authentication token is checked if one exists. If it is readable and not expired, then information for the token is returned. If a valid token does not exist, then the X.509 certificate is checked, if it exists. If it is valid then information is returned for the certificate.

Value

A table containing authentication information.

Get a unique identifier that is generated by the Member Node repository and guaranteed to be unique.

Description

Creating objects requires use of a unique persistent identifier (pid) when calling the create function. Member Nodes may optionally provide the generateIdentifier service to issue such identifiers, ensuring that they are unique. Each identifier conforms to an identifier scheme, which determines the syntax and rules for how the identifier that is generated is formatted. All Member Nodes that implement this method must support the UUID scheme, but may also support other schemes such as DOI and others.

Usage

generateIdentifier(x, ...)

## S4 method for signature 'MNode'
generateIdentifier(x, scheme = "UUID", fragment = NULL)

Arguments

Details

In the version 2.0 library and higher, this operation can utilize an 'dataone_token' option to provide credentials for write operations in DataONE. The authentication token is obtained from DataONE (see your profile on https://search.dataone.org). See the vignette("dataone-overview") for details. Alternatively, the version 1.0 approach of using an X.509 certificate in a default location of the file system can also be used. This certificate provides authentication credentials from CILogon https://cilogon.org/?skin=DataONE. See vignette("dataone-overview") for details.

Value

the character string of the generated unique identifier

See Also

https://purl.dataone.org/architecture/apis/MN_APIs.html#MNStorage.generateIdentifier

Examples

## Not run: 
library(dataone)
cn <- CNode("STAGING")
mn <- getMNode(cn, "urn:node:mnStageUCSB2")
newid <- generateIdentifier(mn, "UUID")

## End(Not run)

Get the expiration date of the current authentication method.

Description

The expiration date of the current authentication method, either authentication token or X.509 certificate, is returned as a Greenwich Mean Time (GMT) value.

Usage

getAuthExpires(.Object, node)

## S4 method for signature 'AuthenticationManager'
getAuthExpires(.Object, node)

Arguments

Value

The expiration date for the current authentication mechanism being used.

Get the current valid authentication mechanism.

Description

Get the current valid authentication mechanism.

Usage

getAuthMethod(.Object, ...)

## S4 method for signature 'AuthenticationManager'
getAuthMethod(.Object, node)

Arguments

Details

The current authentication method being used, either an authentication token or an X.509 certificate. The 'node' argument is used to determine the authentication mechanism that is appropriate for the specified 'node'. For example, authentication tokens are supported on DataONE nodes that use the DataONE V2.0 API or higher, so if the node uses the V1 API, then only an X.509 certificate can be used.

Value

The current authentication mechanism as a character string, either "token" or "cert".

Get the authentication subject.

Description

Get the authentication subject.

Usage

getAuthSubject(.Object, ...)

## S4 method for signature 'AuthenticationManager'
getAuthSubject(.Object, node)

Arguments

Details

The authenticated user, aka 'subject' is retrieved from the authentication mechanism currently being used, either an authentication token or an X.509 certificate. The 'node' argument is used to determine the authentication mechanism that is appropriate for the specified 'node'. For example, authentication tokens are supported on DataONE nodes that use the DataONE V2.0 API or higher, so if the node uses the V1 API, then only an X.509 certificate can be used.

Value

the DataONE Subject that is your client's identity

Get the coordinating node associated with this D1Client object.

Description

Get the coordinating node associated with this D1Client object.

Usage

getCN(x)

## S4 method for signature 'D1Client'
getCN(x)

Arguments

Note

The method getCN has been deprecated.

See Also

D1Client class description.

Examples

## Not run: 
cli <- D1Client("STAGING2", "urn:node:mnTestKNB")
testCN <- getCN(cli)

## End(Not run)

Get the node capabilities description, and store the information in the MNode.

Description

Access the DataONE getCapabilities() service for the Member Node, which returns an XML description of the repository and the services it offers.

Usage

getCapabilities(x, ...)

## S4 method for signature 'MNode'
getCapabilities(x)

Arguments

Value

an XMLInternalDocument object representing the DataONE environment

See Also

https://purl.dataone.org/architecture/apis/MN_APIs.html#MN_core.getCapabilities

Examples

## Not run: 
library(dataone)
cn <- CNode()
mn <- getMNode(cn, "urn:node:KNB")
xml <- getCapabilities(mn)

## End(Not run)

Get the DataONE X.509 Certificate location.

Description

Get the DataONE X.509 Certificate location.

Usage

getCert(.Object, ...)

## S4 method for signature 'AuthenticationManager'
getCert(.Object)

Arguments

Value

The filename of the current DataONE X.509 Certificate if it is available.

Show the date and time when an X.509 certificate expires.

Description

Each X.509 has a range of certificate validity times. This method returns the X.509 'notAfter' field formatted as a 'POSIXct' date value.

Usage

getCertExpires(x, ...)

## S4 method for signature 'CertificateManager'
getCertExpires(x)

Arguments

Value

POSIXct value

Get X.509 Certificate information

Description

The DataONE X.509 certificate is read, if it is present and the information contained in the certificate is returned as a data.frame.

Usage

getCertInfo(.Object)

## S4 method for signature 'AuthenticationManager'
getCertInfo(.Object)

Arguments

Value

A data.frame containing information about the X.509 certificate.

Get the file path on disk of the client certificate file.

Description

Find the location of the client certificate, which is typically in a default location on disk, unless the 'location' slot has been set with a custom location for the certificate.

Usage

getCertLocation(x, ...)

## S4 method for signature 'CertificateManager'
getCertLocation(x)

Arguments

Details

The default Globus Grid Security Infrastructure (GSI) location is '/tmp/x509up_u${UID}' on Unix or '${tmpdir}/x509up_u${UID}' on Windows or '${tmpdir}/x509up_u${user.name}' if '${UID}' is not defined.

Value

character the path to the certificate

Get the checksum for the data object associated with the specified pid.

Description

A checksum is calculated for an object when it is uploaded to DataONE and is submitted with the object's system metadata. The 'getChecksum' method retrieves the checksum from the specified coordinating node

Usage

getChecksum(x, ...)

## S4 method for signature 'CNode'
getChecksum(x, pid, ...)

## S4 method for signature 'MNode'
getChecksum(x, pid, checksumAlgorithm = "SHA-256")

Arguments

Value

character the checksum value, with the checksum algorithm as the attribute "algorithm"

See Also

D1Node-class{D1Node} class description.

Examples

## Not run:  
library(dataone)
cn <- CNode()
mn <- getMNode(cn, "urn:node:KNB")
pid <- "doi:10.5063/F1QN64NZ"
chksum <- getChecksum(mn, pid)

## End(Not run)
## Not run: 
pid <- "doi:10.5063/F1QN64NZ"
cn <- CNode()
pid <- "doi:10.5063/F1QN64NZ"
chksum <- getChecksum(cn, pid)

## End(Not run)

Download a data object from the DataONE Federation.

Description

An object is download from the DataONE network for the identifier that is provided.

Usage

getD1Object(x, identifier, ...)

## S4 method for signature 'D1Client'
getD1Object(x, identifier)

Arguments

Value

A datapack:DataObject

See Also

D1Client class description.

Examples

## Not run:  
library(dataone)
d1c <- D1Client("PROD", "urn:node:KNB")
pid <- "solson.5.1"
dataObj <- getD1Object(d1c, pid)
data <- getData(dataObj)

## End(Not run)

Get the data content of a D1Object.

Description

Get the data content of a D1Object.

Usage

## S4 method for signature 'D1Object'
getData(x)

Arguments

Download a file (and it's associated system metadata) from the DataONE Federation as a DataObject.

Description

A convenience method to download a data object and its associated SystemMetadata, wrapped in a DataObject class.

Usage

getDataObject(x, identifier, ...)

## S4 method for signature 'D1Client'
getDataObject(
  x,
  identifier,
  lazyLoad = FALSE,
  limit = "1MB",
  quiet = TRUE,
  checksumAlgorithm = as.character(NA)
)

Arguments

Details

This method performs multiple underlying calls to the DataONE repository network. CN.resolve() is called to locate the object on one or more repositories, and then each of these is accessed until the associated SystemMetadata and data bytes are successfully downloaded. This data is then used to construct the returned DataObject. This function replaces the previous getD1Object() method in the version 1 dataone library.

The lazyLoad parameter controls whether the data byes for a DataONE item are downloaded (the system metadata is always downloaded). When lazyLoad=FALSE,the limit parameter can be used to specify the maximum size of a data file that will be downloaded. If lazyLoad is TRUE, then limit is ignored. The lazyLoad and limit can be used together in the following ways:

Note that DataONE system metadata is always downloaded and populated into the resulting DataObject, regardless of the 'lazyLoad' and 'limit' values specified in the call to 'getDataObject()'.

Value

A DataObject or NULL if the object was not found in DataONE

See Also

D1Client class description.

Examples

## Not run: 
library(dataone)
d1c <- D1Client("PROD", "urn:node:KNB")
pid <- "solson.5.1"
obj <- getDataObject(d1c, pid)
data <- getData(obj)

## End(Not run)

Download data from the DataONE Federation as a DataPackage.

Description

This is convenience method that will download all the members in a DataONE data package and insert them into a DataPackage, including associated SystemMetadata for each package member.

Usage

getDataPackage(x, identifier, ...)

## S4 method for signature 'D1Client'
getDataPackage(
  x,
  identifier,
  lazyLoad = FALSE,
  limit = "1MB",
  quiet = TRUE,
  checksumAlgorithm = as.character(NA)
)

Arguments

Details

A 'data package' that resides on a DataONE member node is defined as a collection of digital objects that are described by a metadata document.

The lazyLoad parameter controls whether the data bytes for a DataONE package member are downloaded (the system metadata is always downloaded). When lazyLoad=FALSE, the limit parameter can be used to specify the maximum size of a data file that will be downloaded. If lazyLoad is TRUE, then limit is ignored. The lazyLoad and limit parameters can be used together in the following ways:

Value

A DataPackage or NULL if the package was not found in DataONE

See Also

D1Client class description.

Examples

## Not run: 
library(dataone)
d1c <- D1Client("PROD", "urn:node:KNB")
pid <- "solson.5.1"
pkg <- getDataPackage(d1c, pid)

## End(Not run)

Return the URL endpoint for the DataONE Coordinating Node.

Description

A D1Client object is associated with a DataONE Coordinating Node. This CN is either the production CN (from the "PROD" environment, the default), or a CN from one of the development environments ("STAGING", "SANDBOX", "DEV"). The base URL for the CN is returned.

Usage

getEndpoint(x, ...)

## S4 method for signature 'D1Client'
getEndpoint(x)

Arguments

Value

A character vector containing the URL of the Coordinating Node

See Also

D1Client class description.

Examples

## Not run: 
cli <- D1Client("STAGING2", "urn:node:mnTestKNB")
cnUrl <- getEndpoint(cli)

## End(Not run)

Extract an error message from an http response.

Description

Http requests can fail for a variety of reasons, so getErrorDescription first tries to determine what type of response was sent.

Usage

getErrorDescription(response)

Arguments

Details

The return types handled by this function are: o An incorrect url is sent to DataONE and an error is returned by the web server, not a specified DataONE service url. In this case, a generic error message may be returned, e.g. status=404, URL not found o A DataONE service was called, and returned an error message. In this case the DataONE response is parsed in an attempt to retrieve a meaningful error message.

Get information for a single DataONE object format

Description

Get information for a single DataONE object format

Usage

getFormat(x, ...)

## S4 method for signature 'CNode'
getFormat(x, formatId)

Arguments

Value

A dataframe of all object formats registered in the DataONE Object Format Vocabulary.

See Also

CNode class description.

Examples

## Not run: 
library(dataone)
cn <- CNode()
fmt <- getFormat(cn, "eml://ecoinformatics.org/eml-2.1.0")
cat(sprintf("format name: %s\n", fmt$name))
cat(sprintf("format type: %s\n", fmt$type))
cat(sprintf("format Id: %s\n", fmt$id))

## End(Not run)

Get the FormatId of the D1Object

Description

Get the FormatId of the D1Object

Usage

## S4 method for signature 'D1Object'
getFormatId(x)

Arguments

Value

the formatId

Get the Identifier of the D1Object

Description

Get the Identifier of the D1Object

Usage

## S4 method for signature 'D1Object'
getIdentifier(x)

Arguments

Value

the identifier

Get a member node client based on its node identifier.

Description

Get a member node client based on its node identifier.

Usage

getMN(x, nodeid, ...)

## S4 method for signature 'D1Client,ANY'
getMN(x, nodeid, ...)

## S4 method for signature 'D1Client,character'
getMN(x, nodeid)

Arguments

Note

This method has been superceded by getMNodeId

See Also

D1Client class description.

Examples

## Not run: 
cli <- D1Client("STAGING2", "urn:node:mnTestKNB")
testMN <- getMN(cli)

## End(Not run)

Get a reference to a node based on its identifier

Description

Get a reference to a node based on its identifier

Usage

getMNode(x, ...)

## S4 method for signature 'CNode'
getMNode(x, nodeid)

Arguments

Details

For an explanation of DataONE Coordinating Nodes and Member Node identifiers, see the section "DataONE Environments" in the overview vignette by entering the R command: vignette("dataone-overview").

Value

the Member Node as an MNode reference, or NULL if not found

See Also

CNode class description.

Examples

## Not run: 
cn <- CNode()
mn <- getMNode(cn, "urn:node:KNB")

## End(Not run)

Get the member node identifier associated with this D1Client object..

Description

One Member Node can be associated with the client as the default to which data and metadata are written.

Usage

getMNodeId(x)

## S4 method for signature 'D1Client'
getMNodeId(x)

Arguments

Value

The Member Node identifier as a character vector

See Also

D1Client class description.

Examples

## Not run: 
cli <- D1Client("STAGING2", "urn:node:mnTestKNB")
mn <- getMNodeId(cli)

## End(Not run)

Get the DataObject containing package metadata

Description

Each DataObject in the DataPackage is inspected to see if it matches one of the formats supported by DataONE for metadata. If a package member's format matches one of the supported formats, the identifier for that member is returned.

Usage

getMetadataMember(x, dp, ...)

## S4 method for signature 'D1Client,DataPackage'
getMetadataMember(x, dp, as = "character", ...)

Arguments

Details

This method calls the DataONE CN 'format' service to obtain the current format list.

Value

The identifier of the metadata object

Get the bytes associated with an object on this Node.

Description

Get the bytes associated with an object on this Node.

Usage

getObject(x, ...)

## S4 method for signature 'CNode'
getObject(x, pid)

## S4 method for signature 'MNode'
getObject(x, pid, check = as.logical(FALSE))

Arguments

Details

This operation acts as the 'public' anonymous user unless an X.509 certificate is present in the default location of the file system, in which case the access will be authenticated.

Value

the bytes of the object

See Also

D1Node-class{D1Node} class description.

Examples

## Not run: 
library(dataone)
cn <- CNode()
mn <- getMNode(cn, "urn:node:KNB")
pid <- "solson.5.1"
obj <- getObject(mn, pid)
df <- read.csv(text=rawToChar(obj))

## End(Not run)

Download a data package from a member node.

Description

Given a valid identifier, download a file containing all of the package members of the corresponding DataONE data package.

Usage

getPackage(x, ...)

## S4 method for signature 'MNode'
getPackage(
  x,
  identifier,
  format = "application/bagit-097",
  dirPath = NULL,
  unzip = FALSE
)

Arguments

Details

The default data package file format is a Bagit file (https://tools.ietf.org/html/draft-kunze-bagit-09). The downloaded package file is compressed using the ZIP format and will be located in an R session temporary file. Other packaging formats can be requested if they have been implemented by the requested member node.

Value

The location of the package file downloaded from the member node.

See Also

MNode class description.

Examples

## Not run: 
cn <- CNode()
mn <- getMNode(cn, "urn:node:KNB")
packageFileName <- getPackage(mn, id="resourceMap_Blandy.76.2")

## End(Not run)

Query a node for the list of query engines available on the node

Description

Query a node for the list of query engines available on the node

Usage

getQueryEngineDescription(x, ...)

## S4 method for signature 'D1Node'
getQueryEngineDescription(x, queryEngineName)

Arguments

Value

list The query engine description

Examples

## Not run: 
library(dataone)
cn <- CNode("PROD")
engineDesc <- getQueryEngineDescription(cn, "solr")
cat(sprintf("Query engine version: %s\n", engineDesc$queryEngineVersion))
cat(sprintf("Query engine name: %s\n", engineDesc$name))
engineDesc <- getQueryEngineDescription(cn, "solr")
head(engineDesc$queryFields, n=3L)

## End(Not run)

Get the metadata describing system properties associated with an object on this Node.

Description

The SystemMetadata includes information about the identity, type, access control, and other system level details about the object.

The SystemMetadata includes information about the identity, type, access control, and other system level details about the object.

Usage

getSystemMetadata(x, ...)

## S4 method for signature 'CNode'
getSystemMetadata(x, pid)

## S4 method for signature 'MNode'
getSystemMetadata(x, pid)

Arguments

Details

This operation acts as the 'public' anonymous user unless an X.509 certificate is present in the default location of the file system, in which case the access will be authenticated.

This operation acts as the 'public' anonymous user unless an X.509 certificate is present in the default location of the file system, in which case the access will be authenticated.

Value

SystemMetadata for the object

SystemMetadata for the object

See Also

CNode class description.

Examples

## Not run:  
library(dataone)
cn <- CNode()
mn <- getMNode(cn, "urn:node:KNB")
pid <- "doi:10.5063/F1QN64NZ"
sysmeta <- getSystemMetadata(mn, pid)

## End(Not run)
## Not run: 
library(dataone)
cn <- CNode()
pid <- "aceasdata.3.2"
sysmeta <- getSystemMetadata(cn, pid)

## End(Not run)

Get the value of the DataONE Authentication Token, if one exists.

Description

Get the value of the DataONE Authentication Token, if one exists.

Usage

getToken(.Object, ...)

## S4 method for signature 'AuthenticationManager'
getToken(.Object, node = as.character(NA))

Arguments

Details

A token value is retrieved based on the DataONE environment that the specified node is located in, either the production environment or a test environment.

Value

The current authentication token.

Get authentication token information

Description

The DataONE authentication token is read, if it has been set, and the information it contains is returned as a data.frame.

Usage

getTokenInfo(.Object)

## S4 method for signature 'AuthenticationManager'
getTokenInfo(.Object)

Arguments

Value

A data.frame containing information about the authentication token.

User agent string

Description

Get a string representation of the user agent to be sent to the server along with other request details.

Usage

get_user_agent()

Checks to determine if the supplied subject is the owner of the reservation of id.

Description

The hasReservation method checks the reservation of an identifier that has previously been reserved with the reserveIdentifier method. The identifier must have been reserved by the specified DataONE user identity (subject).

Usage

hasReservation(x, ...)

## S4 method for signature 'CNode'
hasReservation(x, pid, subject = as.character(NA))

Arguments

Details

To determine the DataONE identity that is currently being used for DataONE authentication, use the echoCredentials method.

Value

A logical value where TRUE means a reservation exists for the specified pid by the subject.

See Also

CNode class description.

Examples

## Not run: 
library(dataone)
cn <- CNode("STAGING")
creds <- echoCredentials(cn)
subject <- creds$person$subject
# Previously reserved pid (using reserveIdentifeir()), e.g. DOI or uuid
pid <- "urn:node:e27bb4f3-96bb-4af4-8902-f5914def077c"
hasRes <- hasReservation(cn, pid, subject=subject)

## End(Not run)

Initialize a D1Client object

Description

Initialize a D1Client object

Usage

## S4 method for signature 'D1Client'
initialize(
  .Object,
  cn = NA,
  mn = NA,
  env = as.character(NA),
  mNodeid = as.character(NA)
)

Arguments

See Also

dataone class description.

Examples

## Not run: 
library(dataone)
d1c <- D1Client("PROD", "urn:node:KNB")

## End(Not run)

Initialize a D1Node

Description

Initialize a D1Node

Usage

## S4 method for signature 'D1Node'
initialize(.Object)

Arguments

Initialize a D1Object

Description

Initialize a D1Object

Usage

## S4 method for signature 'D1Object'
initialize(.Object, id, data, format, mnNodeId = as.character(NA))

Arguments

See Also

D1Object class description.

Check if the currently valid authentication method has reached the expiration time.

Description

Check if the currently valid authentication method has reached the expiration time.

Usage

isAuthExpired(.Object, ...)

## S4 method for signature 'AuthenticationManager'
isAuthExpired(.Object, node)

Arguments

Value

A logical value: TRUE if authentication has expired, FALSE if not.

Verify authentication for a member node.

Description

The currently used DataONE client authentication method (either tokens or X.509 certificates) is checked and verified for the specified node (either CN or MN). If an authentication token is available via the R options facility, it will be used i.e. available via getOption("dataone_token"). However, authentication tokens can only be used for DataONE v2 or higher nodes. X.509 certificates can be used with DataONE v1 or higher nodes. See the "dataone" vignette "dataone-overview" for more information on authentication.

Usage

isAuthValid(.Object, ...)

## S4 method for signature 'AuthenticationManager'
isAuthValid(.Object, node)

Arguments

Value

A logical value: TRUE if authentication is valid, false if not.

Check if an action is authorized for the specified identifier

Description

Test if the user identified by the provided token has authorization for operation on the specified object.

Usage

isAuthorized(x, ...)

## S4 method for signature 'D1Node'
isAuthorized(x, id, action)

Arguments

Details

The identifier parameter may be either a DataONE persistent identifier (pid) or series identifier (sid).

Value

a logical, TRUE if the action is authorized, false if not.

See Also

CNode class description.

Examples

## Not run: 
# Send an authorization check to the D1 production CN.
cn <- CNode("PROD")
pid <- "doi:10.6073/pasta/7fcb8fea57843fae65f63094472f502d"
canRead <- isAuthorized(cn, pid, "read")
canWrite <- isAuthorized(cn, pid, "write")
canChange <- isAuthorized(cn, pid, "changePermission")

# Now send a check to a member node.
mn <- getMNode(cn, "urn:node:KNB")
pid <- "doi:10.6085/AA/pisco_recruitment.149.1"
canRead <- isAuthorized(mn, pid, "read")
canWrite <- isAuthorized(mn, pid, "write")
canChange <- isAuthorized(mn, pid, "changePermission")

## End(Not run)

Determine if an X.509 certificate has expired.

Description

Returns 'TRUE' if the certificate associated with a CertificateManager instance is expired. A certificate is expired if any of the following conditions hold: 1) the current time is before or after the certificate validity dates, 2) the certificate is not valid according to a trusted Certificate Authority, or 3) no certificate can be found.

Usage

isCertExpired(x, ...)

## S4 method for signature 'CertificateManager'
isCertExpired(x)

Arguments

Value

TRUE if the certificate is expired

List all object formats registered in DataONE.

Description

The listFormats method queries a DataONE Coordinating Node for a list of all entries in the Object Format Vocabulary.

Usage

listFormats(x, ...)

## S4 method for signature 'CNode'
listFormats(x)

Arguments

Value

Returns a dataframe of all object formats registered in the DataONE Object Format Vocabulary.

See Also

CNode class description.

Examples

## Not run: 
library(dataone)
cn <- CNode()
formats <- listFormats(cn)

## End(Not run)

List DataONE Member Nodes.

Description

A D1Client object is associated with a DataONE Coordinating Node. The listMemberNodes method lists all member nodes associated with a CN.

Usage

listMemberNodes(x)

## S4 method for signature 'D1Client'
listMemberNodes(x)

Arguments

See Also

D1Client class description.

Examples

## Not run: 
d1c <- D1Client("PROD")
nodelist <- listMemberNodes(d1c)

## End(Not run)

Get the list of nodes associated with a CN

Description

Get the list of nodes associated with a CN

Usage

listNodes(x, ...)

## S4 method for signature 'CNode'
listNodes(x, url = as.character(NA), ...)

Arguments

Value

the list of nodes in the DataONE CN environment

See Also

CNode class description.

Examples

## Not run: 
cn <- CNode()
nodelist <- listNodes(cn)
nodeid <- nodelist[[2]]@identifier

## End(Not run)

Retrieve the list of objects that match the search parameters

Description

Retrieve the list of objects that match the search parameters

Usage

listObjects(x, ...)

## S4 method for signature 'D1Node'
listObjects(
  x,
  fromDate = as.character(NA),
  toDate = as.character(NA),
  formatId = as.character(NA),
  replicaStatus = as.logical(TRUE),
  start = as.integer(0),
  count = as.integer(1000)
)

Arguments

Details

The list of objects that is returned is paged according to the 'start' and 'count' values, so that large result sets can be returned over multiple calls.

Value

list Objects that met the search criteria

list Objects that met the search criteria

See Also

https://purl.dataone.org/architecture/apis/MN_APIs.html#MN_read.listObjects

Examples

## Not run: 
library(dataone)
cn <- CNode("STAGING")
fromDate <- "2013-01-01T01:01:01.000+00:00"
toDate <- "2015-12-31T01:01:01.000+00:00"
formatId <- "eml://ecoinformatics.org/eml-2.1.0"
start <- 0
count <- 5
objects <- listObjects(cn, fromDate=fromDate, toDate=toDate, 
    formatId=formatId, start=start, count=count)
# Inspect id of first object 
objects[1]$objectInfo$identifier

## End(Not run)

Query a node for the list of query engines available on the node

Description

Query a node for the list of query engines available on the node

Usage

listQueryEngines(x, ...)

## S4 method for signature 'D1Node'
listQueryEngines(x)

Arguments

Value

list The list of query engines.

Examples

## Not run: 
cn <- CNode("STAGING")
engines <- listQueryEngines(cn)

## End(Not run)

Temporarily disable DataONE authentication.

Description

Calling obscureAuth temporarily disables authentication so that

Usage

obscureAuth(.Object)

## S4 method for signature 'AuthenticationManager'
obscureAuth(.Object)

Arguments

Details

This method is intended to be used for authentication testing. isAuthValid will return FALSE. Authentication can be re-enabled by calling restoreAuth.

Value

The expiration date for the current authentication mechanism being used.

Obscure the CILogon Client Certificate

Description

Obscures the x509 certificate that CILogon installs, effectively making future interactions with the DataONE services public/anonymous. This function simple renames an existing certificate file to a known location, allowing 'public' operations. Note, when the client certificate is obscured via the renaming, you will not be able to create objects in DataONE, or utilize any other methods that require authentication.

Usage

obscureCert(x, ...)

## S4 method for signature 'CertificateManager'
obscureCert(x)

Arguments

Value

the modified CertificateManager instance

See Also

restoreCert is this method's inverse operation

Construct a Node, using a passed in capabilities XML

Description

Construct a Node, using a passed in capabilities XML

Usage

parseCapabilities(x, ...)

## S4 method for signature 'D1Node'
parseCapabilities(x, xml)

Arguments

Value

The Node object with modified capabilities properties from the XML

Parse Solr output into an R list

Description

Solr output that is specified with a writer type of XML '&wt="xml"'

Usage

parseSolrResult(doc, ...)

## S4 method for signature 'XMLInternalDocument'
parseSolrResult(doc, parse, ...)

Arguments

Value

resultList The Solr result as an R list

Test if a node is online and accepting DataONE requests

Description

Test if a node is online and accepting DataONE requests

Usage

ping(x, ...)

## S4 method for signature 'D1Node'
ping(x)

Arguments

Value

logical A logical value set to TRUE if the node is up and FALSE if it is not

logical A logical value set to TRUE if the node is up and FALSE if it is not

Examples

## Not run: 
cn <- CNode()
mn <- getMNode(cn, "urn:node:KNB")
isAlive <- ping(mn)

## End(Not run)

Search DataONE for data and metadata objects

Description

The DataONE search index is searched for data that matches the specified query parameters.

Usage

query(x, ...)

## S4 method for signature 'D1Node'
query(
  x,
  solrQuery = as.character(NA),
  encode = TRUE,
  as = "list",
  parse = TRUE,
  searchTerms = as.character(NA),
  encodeReserved = FALSE,
  ...
)

Arguments

Details

The "query" method sends a query to a DataONE search index that uses the Apache Solr search engine https://solr.apache.org/. This same Solr search engine is the underlying mechanism used by the DataONE online search tool available at https://search.dataone.org/.

The "solrQuery" argument is used to specify search terms that data of interest must match. This parameter uses Solr query terms, so some familiarity with Solr is helpful, however, fairly simple queries can be effective. This argument can be created as either a single character string containing the Solr query, for example: solrQuery = "q=id:doi*&rows=2&wt=json", or as a list of key value pairs: solrQuery = list(q = "id:doi*", rows = "2", wt = "json"). These two queries produce the same result.

As an alternative to specifying the Solr query terms using the "solrquery" argument, the "searchTerms" argument can be specified, which does not require any Solr syntax. This parameter is a list with query field / value pairs, i.e. searchTerms=list(abstract=kelp, attribute=biomass). The query fields can be listed for a DataONE node using getQueryEngineDescription. Either "searchTerms" or "solrQuery" must be specified.

The "as" argument is used to specify the query result to be returned as: "json", xml", "list", "data.frame".

The "parsed" argument, if specified as TRUE, causes the query result to be converted to appropriate R data types. For example, if ar = "xml" and parsed = TRUE, then the query result is returned as an R XMLInternalDocument, or If 'parsed = FALSE' then a character variable with the XML string is returned. Specify as = "list" to have the result parsed to an R list, with each list element containing one Solr query result of the total result set.

Value

search results as a list, data.frame or XML document

Examples

## Not run: 
library(dataone)
cn <- CNode("PROD")
queryParams <- list(q="id:doi*", rows="5", 
    fq="(abstract:chlorophyll AND dateUploaded:[2000-01-01T00:00:00Z TO NOW])", 
    fl="title,id,abstract,size,dateUploaded,attributeName")
# Return result as a list.
result <- query(cn, queryParams, as="list")

# Query and return the result as a data.frame of character values.
queryParams <- list(q="id:doi*", rows="3", 
    fq="(abstract:chlorophyll AND dateUploaded:[2000-01-01T00:00:00Z TO NOW])", 
    fl="title,id,abstract,size,dateUploaded,attributeName")
result <- query(cn, queryParams, as="data.frame", parse=FALSE)

# Return the result as JSON
queryParams <- "q=id:doi*&rows=2&wt=json"
result <- query(cn, queryParams, as="json")

# The following query shows how to embed quotes
cn <- CNode("SANDBOX2")
queryParamList <- list(q="(attribute:lake) and (attribute:\"Percent Nitrogen\")", rows="1000",
                       fl="title,id,abstract,size,dateUploaded,attributeName", wt="xml")
result <- query(cn, queryParamList, as="data.frame")

# The following query uses the searchTerms parameter
cn <- CNode()
mn <- getMNode(cn, "urn:node:KNB")
mySearchTerms <- list(abstract="kelp", attribute="biomass")
result <- query(mn, searchTerms=mySearchTerms, as="data.frame")

## End(Not run)

Reserve a identifier that is unique in the DataONE network.

Description

The reserveIdentifier method contains the DataONE CN and reserves the specified identifier that the user has provided. Once a an identifier has been reserved, it and can not be used by any other user.

Usage

reserveIdentifier(x, ...)

## S4 method for signature 'CNode'
reserveIdentifier(x, id)

## S4 method for signature 'D1Client'
reserveIdentifier(x, id)

Arguments

Details

This method requires a DataONE authentication token or X.509 Certificate. The reservation is made for the DataONE user identity that created the current authentication token or X.509 certificate.

Value

The reserved pid if it was successfully reserved, otherwise NULL

See Also

CNode class description.

Examples

## Not run: 
library(dataone)
library(uuid)
cn <- CNode("STAGING")
myId <- sprintf("urn:uuid:%s", UUIDgenerate())
newId <- reserveIdentifier(cn, myId)

## End(Not run)

Get a list of coordinating nodes holding a given pid.

Description

Returns a list of nodes (MNs or CNs) known to hold copies of the object identified by id.

Usage

resolve(x, ...)

## S4 method for signature 'CNode'
resolve(x, pid)

Arguments

Value

A list of URLs that the object can be downloaded from, or NULL if the object is not found.

Examples

## Not run: 
library(dataone)
cn <- CNode("STAGING")
id <- "doi:10.6073/pasta/9a27a1615e8e4c366ad09fefbfa2fced"
locations <- resolve(cn,id)

## End(Not run)

Restore authentication (after being disabled with obscureAuth).

Description

Restore authentication (after being disabled with obscureAuth).

Usage

restoreAuth(.Object)

## S4 method for signature 'AuthenticationManager'
restoreAuth(.Object)

Arguments

Value

The expiration date for the current authentication mechanism being used.

Restore the CILogon client certificate by renaming it to its original location

Description

Restores the x509 certificate that CILogon installs, which allows future interactions with nodes to be authenticated with the certificate. This function simply renames an obscured certificate file to its original location, allowing authenticated operations.

Usage

restoreCert(x, ...)

## S4 method for signature 'CertificateManager'
restoreCert(x)

Arguments

Value

the modified CertificateManager instance

See Also

obscureCert is this method's inverse operation

Set the member node identifier to be associated with the D1Client object.

Description

The member node identifier is the URN identifier used by DataONE to uniquely identifier a node, for example "urn:node:KNB" specifies the "Knowledge Network for Biodiversity" member node.

Usage

setMNodeId(x, id)

## S4 method for signature 'D1Client,character'
setMNodeId(x, id)

Arguments

Details

One Member Node can be associated with the client as the default to which data and metadata are written.

Author(s)

setMNodeId

See Also

D1Client class description.

Set a pid as being obsoleted by another pid

Description

Updates the SystemMetadata 'obsoletedBy' property for an object, indicating that the object specified by pid has been obsoleted by the identifier in obsoletedByPid. CILogon https://cilogon.org/?skin=DataONE. See CertificateManager for details. In DataONE version 2.0, authentication tokens can also be used.

Usage

setObsoletedBy(x, pid, obsoletedByPid, ...)

## S4 method for signature 'CNode,character'
setObsoletedBy(x, pid, obsoletedByPid, serialVersion)

Arguments

Value

TRUE if the pid was obsoleted, otherwise FALSE is returned

See Also

CNode class description.

Make the object publicly readable.

Description

This method should be called prior to creating the object in DataONE. When called before creating the object, adds a rule to the access policy that makes this object publicly readable. If called after creation, it will only change the system metadata locally, and will not have any effect on remotely uploaded copies of the D1Object.

Usage

## S4 method for signature 'D1Object'
setPublicAccess(x)

Arguments

Value

D1Object with modified access rules

See Also

DataObject class description.

Display all authentication information

Description

Display all authentication information

Usage

showAuth(.Object, ...)

## S4 method for signature 'AuthenticationManager'
showAuth(.Object, node)

Arguments

Get DataONE Identity as Stored in the CILogon Certificate.

Description

Returns Your Identity according to DataONE (and CILogon) as provided in the Subject field of the X.509 certificate. The value is a Distinguished Name, and can be used in all fields that require a user identity for access control authorization. If the certificate is missing on expired, then the subject 'public' is returned.

Usage

showClientSubject(x, ...)

## S4 method for signature 'CertificateManager'
showClientSubject(x)

Arguments

Value

the DataONE Subject that is your client's identity

Update an object on a Member Node, by creating a new object that replaces an original.

Description

This method provides the ability to update a data or metadata object to the Member Node provided in the 'x' parameter. In DataONE, both the original object and the new object are maintained, each with its own persistent identifier, and the 'obsoletes' field in the SystemMetadata is used to reflect the fact that the new object replaces the old. Both objects remain accessible.

Usage

updateObject(x, ...)

## S4 method for signature 'MNode'
updateObject(x, pid, file = as.character(NA), newpid, sysmeta, dataobj = NULL)

Arguments

Details

In the version 2.0 library and higher, this operation can utilize an 'dataone_token' option to provide credentials for write operations in DataONE. The authentication token is obtained from DataONE (see your profile on https://search.dataone.org). See the vignette("dataone-overview") for details. Alternatively, the version 1.0 approach of using an X.509 certificate in a default location of the file system can also be used. This certificate provides authentication credentials from CILogon https://cilogon.org/?skin=DataONE. See vignette("dataone-overview") for details.

Value

A character containing the identifier if successful.

Note

Please see the vignette *upload-data* for an example: vignette("upload-data")

See Also

https://purl.dataone.org/architecture/apis/MN_APIs.html#MNStorage.update

Update the system metadata associated with an object.

Description

A modified SytemMetadata object can be sent to DataONE that contains updated information. This function allow updating of the system metadata without updating the object that it describes, so that mutable attributes such as accessPolicy can be updated easily.

Usage

updateSystemMetadata(x, ...)

## S4 method for signature 'MNode'
updateSystemMetadata(x, pid, sysmeta)

Arguments

Details

In the version 2.0 library and higher, this operation can utilize an 'dataone_token' option to provide credentials for write operations in DataONE. The authentication token is obtained from DataONE (see your profile on https://search.dataone.org). See the vignette("dataone-overview") for details. Alternatively, the version 1.0 approach of using an X.509 certificate in a default location of the file system can also be used. This certificate provides authentication credentials from CILogon https://cilogon.org/?skin=DataONE. See vignette("dataone-overview") for details.

Value

A logical value, TRUE if the operation was successful, FALSE if there was an error.

Note

Please see the vignette *upload-data* for an example: vignette("upload-data")

See Also

https://purl.dataone.org/architecture/apis/MN_APIs.html#MNStorage.updateSystemMetadata

Upload a DataObject to a DataONE member node.

Description

Upload a DataObject to a DataONE member node.

Usage

uploadDataObject(x, ...)

## S4 method for signature 'D1Client'
uploadDataObject(
  x,
  do,
  replicate = as.logical(FALSE),
  numberReplicas = NA,
  preferredNodes = NA,
  public = as.logical(FALSE),
  accessRules = NA,
  quiet = TRUE,
  ...
)

Arguments

Value

id The id of the DataObject that was uploaded

See Also

D1Client class description.

Examples

## Not run: 
library(dataone)
library(datapack)
testdf <- data.frame(x=1:10,y=11:20)
csvfile <- tempfile(pattern = "file", tmpdir = tempdir(), fileext = ".csv")
write.csv(testdf, csvfile, row.names=FALSE)
d1c <- D1Client("STAGING", "urn:node:mnStageUCSB2")
do <- new("DataObject", format="text/csv", mnNodeId=getMNodeId(d1c), filename=csvfile)
# Upload a single DataObject to DataONE (requires authentication)
newId <- uploadDataObject(d1c, do, replicate=FALSE, preferredNodes=NA ,  public=TRUE)

## End(Not run)

Upload a DataPackage to a DataONE member node.

Description

Upload all DataObjects contained in the DataPackage by calling uploadDataObject on each of the members. Also a resourceMap object is created from the recorded relationships between DataObjects, and this is uploaded as well.

Usage

uploadDataPackage(x, ...)

## S4 method for signature 'D1Client'
uploadDataPackage(
  x,
  dp,
  replicate = NA,
  numberReplicas = NA,
  preferredNodes = NA,
  public = as.logical(FALSE),
  accessRules = NA,
  quiet = as.logical(TRUE),
  resolveURI = as.character(NA),
  packageId = as.character(NA),
  as = "character",
  ...
)

Arguments

Details

The DataPackage describes the collection of data object and their associated metadata object, with the relationships and members serialized into a document stored under, and retrievable with, the packageId as it's own distinct object. Any objects in the data map that have a dateUploaded value are assumed to be pre-existing in the system, and skipped.

Value

id The identifier of the resource map for this data package

Note

Member objects are created serially, and most errors in creating one object will interrupt the create process for the whole, with the result that some members will be created, and the remainder not.

See Also

D1Client class description.

Examples

## Not run: 
library(dataone)
library(datapack)
dp <- new("DataPackage")
sampleData <- system.file("extdata/sample.csv", package="dataone")
dataObj <- new("DataObject", format="text/csv", file=sampleData)
dataObj <- setPublicAccess(dataObj)
sampleEML <- system.file("extdata/strix-pacific-northwest.xml", package="dataone")
metadataObj <- new("DataObject", format="eml://ecoinformatics.org/eml-2.1.1", file=sampleEML)
metadataObj <- setPublicAccess(metadataObj)
dp <- addMember(dp, do = dataObj, mo = metadataObj)
d1c <- D1Client("STAGING", "urn:node:mnStageUCSB2")
# Upload all members of the DataPackage to DataONE (requires authentication)
packageId <- uploadDataPackage(d1c, dp, replicate=TRUE, public=TRUE, numberReplicas=2)

## End(Not run)