If the content of a nexml object is modified, this function can add a provenance record documenting the modification. The provenance documentation is added to the toplevel metadata (i.e., at the "nexml" level).

add_provenance_record(nexml, cmd = NA, creator = Sys.getenv("USER"))

Arguments

nexml

the nexml object to which to add provenance documentation

cmd

character, the command (such as a function invocation) to document in the provenance record. If NA (the default), the invocation of the function calling this one will be used as the command.

creator

character, a value identifying the person running the software. The default is the system's USER environment variable.

Value

A nexml object with provenance records added.

Details

At present, for each invocation this implementation will do the following:

  1. If the top-level metadata for the nexml object contains dc:description annotations(s), they are moved to being nested within a dcterms:provenance annotation, and prefixed with "Original description:".

  2. A dcterms:provenance annotation is added, with nested properties dc:creator (see parameter creator), dcterms:modified (current time), and dc:description. The latter gives the command to document, see parameter cmd.

  3. A provenance record using Prov-O (a W3C recommendation) nested within prov:wasGeneratedBy is added. In RDF Turtle representation, the record would have the following structure (cf. obo:IAO_0000591):

    :nexml prov:wasGeneratedBy [
      prov:endedAtTime "2019-06-20 15:09:08 GMT" ;
      prov:wasAssociatedWith [
        a obo:IAO_0000591 ;
        dc:title "rphenoscape" ;
        dcterms:hasVersion "<rphenoscape version>" ;
      ] ;
      prov:wasAssociatedWith [
        a prov:Person ;
        foaf:name "<creator>" ;
      ] ;
      prov:used [
        prov:value "<modifying command>" ;
      ] ;
    ] .