Merge pull request #114 from RobLBaker/main

PR to v0.1.3, "Single Pen"

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: EMLeditor
 Title: View and Edit EML Metadata
-Version: 0.1.2
+Version: 0.1.3
 Authors@R: c(
     person(given="Robert", family="Baker", email="robert_baker@nps.gov",
            role = c("aut", "cre"),
@@ -13,7 +13,7 @@ Authors@R: c(
     person(given="Amy", family="Sherman", role = "ctb",
            comment = c(ORCID = "0000-0002-9276-0087"))
   )
-Maintainer: Rob Baker <robert.baker@nps.gov>
+Maintainer: Rob Baker <robert_baker@nps.gov>
 Description: This package will be of most use to the U.S. National Park Service data scientists and managers seeking to generate EML-formatted metadata for datapackages. EML-formatted .xml files are typically constructed using EDI's EMLassemblyline package and then imported as an R-object using the EML package. EMLeditor allows the user to view the contents of the R object and add/edit aspects of metadata crucial for publication in the U.S. National Park Service DataStore repository. For instance, a user can view and edit a DOI, a link to a DRR, Park Unit connections, information about Confidential Unclassified Information (CUI), and more. EMLeditor allows the user to write a mockup of a README.txt to preview what the README automatically generated by DataStore upon upload will look like.
 License: MIT + file LICENSE
 BugReports: https://github.com/nationalparkservice/EMLeditor/issues

NEWS.md

@@ -1,8 +1,18 @@
+# EMLeditor v0.1.3 "Single Pen"
+
+## 2023-11-07
+  * Updated EML template script to fix typos, remove the write_readme section, and add more explanation of the personnel.txt file.
+  * Updated `set_datastore_doi()` to use the correct doi prefix when dev = TRUE and display the correct URL upon draft reference creation.
+  * Ported over most of the documentation on the EML Creation Script from the NPS_EML_Script repo to all be held under this repo.
+  * Updated documentation on making EML; updated the Readme to reflect the fact that all EML creation documentation/instructions are now included in the EMLeditor package
+  * Removed the "Get Started" (EMLeditor.rmd) file as it was pretty redundant with the readme.md file.
+  * Updated the template script in R studio to include package provenance for function calls.
+
 # EMLeditor v0.1.2 "Mukooda Trail"
 
 ## 06 October 2023
-  Updated `set_datastore_doi()` and `upload_data_package()` functions to allow them to work with IRMA dev for testing and training purposes.
-  Updated `upload_data_package()` to prevent file upload if the reference already has files associated with it.
+  * Updated `set_datastore_doi()` and `upload_data_package()` functions to allow them to work with IRMA dev for testing and training purposes.
+* Updated `upload_data_package()` to prevent file upload if the reference already has files associated with it.
 
 # EMLeditor v0.1.1 "Big South Fork"
 

R/datastore_interactions.R

@@ -26,7 +26,7 @@
 #' \dontrun{
 #' eml_object <- set_datastore_doi(eml_object)
 #' }
-set_datastore_doi <- function(eml_object, force = FALSE, NPS = TRUE, dev=FALSE){
+set_datastore_doi <- function(eml_object, force = FALSE, NPS = TRUE, dev = FALSE){
   # check for existing DOI:
   doc <- utils::capture.output(get_doi(eml_object))
   #get data package title from metadata:
@@ -128,14 +128,25 @@ set_datastore_doi <- function(eml_object, force = FALSE, NPS = TRUE, dev=FALSE){
   rjson <- jsonlite::fromJSON(json)
   ds_ref <- rjson$referenceCode
   # insert/replace DOI:
+  if(dev == TRUE){
+    eml_object$dataset$alternateIdentifier <- paste0(
+      "doi: https://doi.org/10.82495/",
+      ds_ref)
+  } else {
   eml_object$dataset$alternateIdentifier <- paste0(
     "doi: https://doi.org/10.57830/",
     ds_ref)
+  }
   # update data URLs to correspond to new DOI:
   data_table <- EML::eml_get(eml_object, "dataTable")
   data_table <- within(data_table, rm("@context"))
-  data_url <- paste0("https://irma.nps.gov/DataStore/Reference/Profile/",
+  if(dev == TRUE){
+    data_url <- paste0("https://irmadev.nps.gov/DataStore/Reference/Profile/",
+                       ds_ref)
+  } else {
+    data_url <- paste0("https://irma.nps.gov/DataStore/Reference/Profile/",
                      ds_ref)
+  }
   # handle case when there is only one data table:
   if("physical" %in% names(data_table)){
     eml_object$dataset$dataTable$physical$distribution$online$url <- data_url

README.md

@@ -9,96 +9,45 @@ experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](h
 
 # EMLeditor
 
-##### v0.1.2
+##### v0.1.3
 
-##### “Mukooda Trail”
+##### “Single Pen”
 
 <!-- badges: start -->
 <!-- badges: end -->
 
 # Overview
+The goal of EMLeditor is to edit Ecological Metadata Language (EML) formatted xml files. Specifically, EMLeditor provides many functions that will be useful to the U.S. National Park Service when generating metadata for statistical data packages uploaded to DataStore. NPS affiliation is assumed as default. However, some of the functions for viewing and editing metadata may be useful to people outside the NPS. If you are not an NPS user, you will want to read the sections on [Custom Publisher/Producer](articles/a05_advanced_functionality.html#custom-publisherproducer).
 
-The goal of EMLeditor is to edit EML-formatted xml files. Specifically,
-EMLeditor provides many functions that will be useful to the U.S.
-National Park Service when generating metadata for statistical data
-packages uploaded to DataStore. NPS affiliation is assumed as default.
-However, some of the functions for viewing and editing metadata may be
-useful to people outside the NPS.
-
-# Workflow outline
-
-EMLeditor’s primary objective is to edit and view EML formatted files,
-not to generate them from scratch. A suggested workflow is:
-
-1) Use the `EMLassemblyline::make_eml()` to generate an initial EML document.
-2) Use EMLeditor functions to edit the metadata in R and evaluate whether your metadata is acceptable (don't forget to use `EML::eml_validate()` to make sure you are generating valid EML).
-3) Use the `EML::write_eml()` function to write the R object back to XML (remember the NPS naming convention for metadata files is *_metadata.xml).
-4) Check your EML and data package using `DPchecker::run_congruence_checks()`.
-5) Upload to DataStore (via web or `EMLeditor::uplad_datapackage()`).
-6) Extract metadata on DataStore.
-7) Please *DO NOT ACTIVATE* the DataStore reference: prior to activation, data packages need to be reviewed via a yet-to-be-created process.
-
-If you use EMLeditor functions to alter your metadata (e.g. “set” class
-functions) they will also silently add the National Park Service as a
-publisher (including location, [ROR id](https://ror.org/), etc) to your
-metadata unless you set NPS=FALSE. If you leave the default setting as
-NPS=TRUE, EMLeditor will also assume the data package is being created
-“by or for the NPS” and add that information to the metadata.
-
-EMLeditor will also add information about the version of EMLeditor you
-used to edit your metadata (for instance if you used “set” class
-functions).
-
-# Installation
-
-You can install the development version of EMLeditor from
-[GitHub](https://github.com/) with:
-
-``` r
-# install.packages("devtools")
-devtools::install_github("nationalparkservice/EMLeditor")
-```
+EMLeditor itself cannot be used to generate EML, only to edit EML. The web pages and documentation associated with the EMLeditor R package, however cover the entire process of generating and editing EML, checking, and uploading metadata (and data) to [DataStore](https://irma.nps.gov/DataStore/) (the National Park Service digital repository). The documentation therefore relies on more than just the functions in the EMLeditor R package. Specifically, the documentation refers to functions included in the following packages: [EML](https://www.cran-e.com/package/EML), [EMLassemblyline](https://ediorg.github.io/EMLassemblyline/), [QCkit](https://nationalparkservice.github.io/QCkit/), EMLeditor, [DPchecker](https://nationalparkservice.github.io/DPchecker/), and [tidyverse](https://www.tidyverse.org/).
+
+All of the required packages except tidyverse can be accessed through the [NPSdataverse](https://nationalparkservice.github.io/NPSdataverse/).
+
+A quick note on function provenance: The package name followed by a double colon is used to indicate the function provenance (e.g. `EML::write_eml()` indicates that the function `write_eml()` comes from the package EML). This level of documentation is a work in progress.
 
+# Install and update 
 To install all the packages in the
-[NPSdataverse](https://github.com/nationalparkservice/NPSdataverse)
-(including EMLeditor):
+[NPSdataverse](https://github.com/nationalparkservice/NPSdataverse) (including EMLeditor):
 
-``` r
-devtools::install_github("nationalparkservice/NPSdataverse")
+```r 
+install.packages(c("devtools", "tidyverse") # only required once
+
+# install or update NPSdataverse:
+devtools::install_github("nationalparkservice/NPSdataverse") # typically only required once
 ```
 
-It is recommended to always load EMLeditor via 
+It is recommended to always load EMLeditor and all the necessary packages for generating EML: 
 ```r
+library(tidyverse)
 library(NPSdataverse)
 ```
-loading the entire NPSdataverse library is the preferred method as it will check whether all of your NPSdataverse packages are up to date (including EMLeditor) and provide instructions on how to update them if you are not working with the latest version.
-
-# Details
+Loading the entire NPSdataverse library is the preferred method as it will check whether all of your NPSdataverse packages are up to date (including EMLeditor) and provide instructions on how to update them if you are not working with the latest version.
 
-For a detailed description of how to use EML editor functions and a
-guide on which functions are required to complete EML metadata creation
-to construct an NPS data package for uploading to DataStore, see the
-complete guide.
+Upon loading the NPSdataverse, you should see a list of all the packages that have been loaded along with the NPSdataverse and their version numbers. If you see the message, "All NPSdataverse packages are up to date", you should be ready to start.  If you see the message, "The following packages are out of date" follow the on-screen instructions to update the indicated packages. If you see neither of those two messages, your version of NPSdataverse is quite old. You will need to update the NPSdataverse package itself before proceeding. 
 
-## Example:
+# Create a data package
+To create a data package including generating EML, please refer to the web pages listed under "Articles", specifically the instructions on the [EML Creation Script](articles/a02_EML_creation_script.html) page.
 
-This is a basic workflow for adding a Digital Object Identifier:
+You may also be interested in the [pre-requisites necessary](articles/a01_prereqs.html) before starting to generate EML a series of guides on how to [edit the .txt files](articles/a03_Template_edits.html) that are generated, some instructions on [editing EML](articles/a04_Editing_fixing_eml.html) after it is created, and options for [advanced users](articles/a05_advanced_functionality.html).
 
-``` r
-library(EMLeditor)
-library(EML)
 
-# load a pre-existing EML-formated xml file:
-my_eml <- EML::read_eml("EML_metadata.xml", from = "xml")
-
-# the 7-digit number is your DataStore Reference number.
-# It is automatically generated when you initiate a draft Reference.
-# Your DOI is reserved but will not be registered/activated until publication.
-my_eml2 <- set_doi(my_eml, "1234567")
-
-# make sure your EML is valid.
-EML::eml_validate(my_eml2)
-
-# write the new R object back to XML:
-write_eml(my_eml2, "EML_metadata.xml")
-```