diff --git a/.Rbuildignore b/.Rbuildignore index e7d7f12..ddf043e 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -1,3 +1,4 @@ ^EMLeditor\.Rproj$ ^\.Rproj\.user$ ^README\.Rmd$ +^LICENSE\.md$ diff --git a/DESCRIPTION b/DESCRIPTION index 1f2f1ba..37600f0 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,12 +1,11 @@ Package: EMLeditor Title: View and Edit EML -Version: 0.0.0.9000 +Version: 0.0.1.0 Authors@R: person("Robert", "Baker", , "robert_baker@nps.gov", role = c("aut", "cre"), comment = c(ORCID = "0000-0001-7591-5035")) 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 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: `use_mit_license()`, `use_gpl3_license()` or friends to pick a - license +License: MIT + file LICENSE Encoding: UTF-8 Roxygen: list(markdown = TRUE) RoxygenNote: 7.2.1 @@ -20,3 +19,7 @@ Depends: lubridate, reader Remotes: NCEAS/arcticdatautils +Imports: + httr, + readr, + sf diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..fd84368 --- /dev/null +++ b/LICENSE @@ -0,0 +1,2 @@ +YEAR: 2022 +COPYRIGHT HOLDER: EMLeditor authors diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..4ca93f9 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,21 @@ +# MIT License + +Copyright (c) 2022 EMLeditor authors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/NAMESPACE b/NAMESPACE index 06da40c..f36b60f 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,8 +1,5 @@ # Generated by roxygen2: do not edit by hand -S3method(edit,DOI) -export(eml_getNPS) -export(eml_get_simpleNPS) export(get.CUI) export(get.DOI) export(get.DRRdoi) @@ -16,12 +13,16 @@ export(get.fileInfo) export(get.lit) export(get.parkUnits) export(get.title) +export(get.unitPolygon) +export(new.DOI) export(set.CUI) export(set.DOI) export(set.DRRdoi) export(set.NPSpublisher) export(set.abstract) +export(set.forByNPS) export(set.lit) export(set.parkUnits) +export(set.title) export(set.version) export(write.readMe) diff --git a/R/editEMLfunctions.R b/R/editEMLfunctions.R index d75dd56..d50d6ec 100644 --- a/R/editEMLfunctions.R +++ b/R/editEMLfunctions.R @@ -1,3 +1,47 @@ +#' Edit data package title +#' +#' @details The set.Title function checks to see if there is an existing title and then asks the user if they would like to change the title. Some work is still needed on this function as get_eml() automatically returns all instances of a given tag. Specifying which title will be important for this function to work well. +#' +#' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EML::read_eml(, from="xml"). +#' @param DataPackageTitle is a character string that will become the new title for the data package. It can be specified directly in the function call or it can be a previously defined object that holds a character string. +#' @param NPS is a logical that defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE +#' +#' @return an EML-formatted R object +#' @export +#' +#' @examples +#' DataPackageTitle<-"New Title. Must match DataStore Reference title." +#' set.title(emlObject, DataPackageTitle) +set.title<-function(emlObject, DataPackageTitle, NPS=TRUE){ + doc<-arcticdatautils::eml_get_simple(emlObject, "title") + if(is.null(doc)){ + emlObject$eml$dataset$title<-paste0(DataPackageTitle) + print("No previous title was detected. Your new title has been added. View the current title using get.title.") + } + else{ + var1<-readline(prompt="Your EML already has an title. Are you sure you want to replace it? \n\n 1: Yes\n 2: No\n") + #if User opts to retain DOI, retain it + if(var1==1){ + #print the existing DOI to the screen: + emlObject$eml$dataset$title<-paste0(DataPackageTitle) + print("You have replaced your title. View the current title using get.title.") + } + #if User opts to change DOI, change it: + if(var1==2){ + print("Your original title was retained. View the current abstract using get.title.") + } + } + #Set NPS publisher, if it doesn't already exist + if(NPS==TRUE){ + emlObject<-set.NPSpublisher(emlObject) + } + #add/update EMLeditor and version to metadata: + emlObject<-set.version(emlObject) + return(emlObject) + } + + + #' Check & set a DOI #' #' @details @@ -5,7 +49,7 @@ #' #' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(, from="xml"). #' @param DSref is the same as the 7-digit reference code generated on DataStore when a draft reference is initiated. -#' @param NPS defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE +#' @param NPS is a logical that defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE #' @returns an EML-formatted R object #' @export set.DOI<-function(emlObject, DSref, NPS=TRUE){ @@ -27,7 +71,7 @@ set.DOI<-function(emlObject, DSref, NPS=TRUE){ #hopefully deals with case when there are multiple DOIs specified under alternateIdentifier tags. Haven't run into this yet and so this remains untested. if(length(doc)>1){ - for(i in 1:length(doc)){ + for(i in seq_along(doc)){ if(stringr::str_detect(doc[i], "doi:" )){ mylist<-append(mylist, doc[i]) } @@ -68,17 +112,24 @@ set.DOI<-function(emlObject, DSref, NPS=TRUE){ #' Force-edits an existing DOI #' -#' @description edit.DOI forces changes to an existing DOI +#' @description new.DOI forces changes to an existing DOI #' #' @details #' If a DOI already exists in the tag (get.DOI() to check), this allows the user to over-write the existing DOI. WARNING: will cause loss of the system="https://doi.org" setting. So only use this if you really don't already have a DOI. #' #' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(, from="xml"). -#' @param DSref is the same as the 7-digit reference code generated on DataStore when the draft reference is initiated. Don't worry about the https://wwww.doi.org and thedata package prefix - those will all automatically be added in by the function. -#' @param NPS defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE +#' +#' @param DSref is the same as the 7-digit reference code generated on DataStore when the draft reference is initiated. Don't worry about the https://wwww.doi.org and the data package prefix - those will all automatically be added in by the function. +#' +#' @param NPS defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE. +#' #' @returns an EML-formatted R object +#' #' @export -edit.DOI<-function(emlObject, DSref, NPS=TRUE){ +#' +#' @example +#' new.DOI(emlObject, "1111111") +new.DOI<-function(emlObject, DSref, NPS=TRUE){ emlObject$dataset$alternateIdentifier<-paste0("doi: https://doi.org/10.57830/", DSref) #Set NPS publisher, if it doesn't already exist @@ -93,17 +144,15 @@ edit.DOI<-function(emlObject, DSref, NPS=TRUE){ } -# Add Park Unit Connections to metadata -#if geographic coverage exists, add to it. -#if geographic coverage exists, doesn't yet add in id= attribute. Grr. -#' Adds Park Unit Connections to metadata +#' Add Park Unit Connections to metadata #' -#' @details -#' Add the Park Unit Connection(s) to a tag under . Park Unit Connection(s) are the (typically) four-letter codes describing the park unit(s) where data were collected (e.g. ROMO, not ROMN). If there are already =items listed under geographicCoverage, Park Unit Connections will be inserted as the first item in the list of geographicCoverages and will be prefaced by the string "NPS Unit Connections:". +#' @description adds all specified park unit connections and their N, E, S, W bounding boxes to . +#' +#' @details Adds the Park Unit Connection(s) to a . Park Unit Connection(s) are the (typically) four-letter codes describing the park unit(s) where data were collected (e.g. ROMO, not ROMN). Each park unit connection is given a separate element. For each park unit connection, the unit name will be listed under and prefaced with "NPS Unit Connections:". Required child elements (bounding coordinates) are auto populated. If other elements exist, set.parkUnits will add to them, not overwrite them. If not other elements exist, set.parkUnits will create a new set of elements. #' #' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(, from="xml"). -#' @param ParkUnits a string of comma-separated park unit codes +#' @param ParkUnits a list of comma-separated strings where each string is a park unit code. #' @param NPS defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE #' @returns an EML-formatted R object #' @export @@ -111,35 +160,49 @@ edit.DOI<-function(emlObject, DSref, NPS=TRUE){ #' ParkUnits<-("ROMO, GRSD, TRYME") #' set.parkUnits(emlObject, ParkUnits) set.parkUnits<-function(emlObject, ParkUnits, NPS=TRUE){ + #add text to indicate that these are park unit connections. Note that bounding coordinates are DUMMY COORDINATES + units<-paste0("NPS Unit Connections: ", ParkUnits) + + unit_list<-NULL + for(i in seq_along(ParkUnits)){ + poly<-get.unitPolygon(ParkUnits[i]) + poly<-as.data.frame(poly[[1]][1]) + N<-max(poly[,2]) + S<-min(poly[,2]) + W<-max(poly[,1]) + E<-min(poly[,1]) + geocov<- EML::eml$geographicCoverage(geographicDescription = + paste0("NPS Unit Connections: ", ParkUnits[i]), + boundingCoordinates = EML::eml$boundingCoordinates( + northBoundingCoordinate = N, + eastBoundingCoordinate = E, + southBoundingCoordinate = S, + westBoundingCoordinate = W)) + unit_list<-append(unit_list, list(geocov)) + } + #get geographic coverage from emlObject doc<-EML::eml_get(emlObject, "geographicCoverage") #if there is no geo coverage, add it directly to emlObject if(is.null(doc)){ - emlObject$dataset$coverage$geographicCoverage$id<-"UnitConnections" - emlObject$dataset$coverage$geographicCoverage$geographicDescription<-paste0("NPS Unit Connections: ",ParkUnits) + emlObject$dataset$coverage$geographicCoverage<-unit_list } #if there are already geographicCoverage(s) - #(unfortunately currently there is no way to add id="UnitConnections" in this case) else{ mylist<-NULL - #ditch the '@context' list from the goeCoverage: - for(i in 1:length(names(doc))){ - if(!names(doc)[i]=='@context') + #ditch the '@context' list from the geographicCoverage: + for(i in seq_along(names(doc))){ + if(!names(doc)[i]=='@context'){ mylist<-append(mylist, doc[i]) + } } #remove names from list (critical for writing back to xml) names(mylist)<-NULL - #add text to indicate that these are park unit connections: - units<-paste0("NPS Unit Connections: ", ParkUnits) - - #generate the new geographic coverage elements: - geocov2<-list(geographicDescription=units) - #combine new and old geo coverages (new always at the top!) - mylist<-append(list(geocov2), mylist) + mylist<-append(unit_list, mylist) #write over the existing geographic coverage emlObject$dataset$coverage$geographicCoverage<-mylist @@ -163,28 +226,68 @@ set.parkUnits<-function(emlObject, ParkUnits, NPS=TRUE){ #' @details set.CUI adds a CUI code to the tag under . #' #' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(, from="xml"). -#' @param CUI a string consisting of one of 5 potential CUI codes. Pay attention to the spaces: +#' @param CUIcode a string consisting of one of 7 potential CUI codes (defaults to "PUBFUL"). Pay attention to the spaces: #' FED ONLY - Contains CUI. Only federal employees should have access (similar to "internal only" in DataStore) #' FEDCON - Contains CUI. Only federal employees and federal contractors should have access (also very much like current "internal only" setting in DataStore) #' DL ONLY - Contains CUI. Should only be available to a names list of individuals (where and how to list those individuals TBD) #' NOCON - Contains CUI. Federal, state, local, or tribal employees may have access, but contractors cannot. -#' PUBVER - Does NOT contain CUI. The original data contained CUI, but in thisdata package CUI have been obscured so that it no longer contains CUI. -#' PUBFUL - Does NOT contain CUI. The original data contained no CUI. No data were obscured or altered to generate the data package +#' PUBVER - Does NOT contain CUI. The original data contained CUI, but in this data package CUI have been obscured so that it no longer contains CUI. +#' PUBFUL - Does NOT contain CUI. The original data contained no CUI. No data were obscured or altered to generate the data package. +#' NPSONLY - Contains CUI. For NPS access only. #' @param NPS defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE #' @returns an EML-formatted R object #' @export #' @examples #' set.CUI(emlObject, "PUBFUL") -set.CUI<-function(emlObject, CUI, NPS=TRUE){ - #add those random spaces in case people forget - if(CUI=="FEDONLY"){ - CUI=="FED ONLY" +set.CUI<-function(emlObject, CUIcode=c("PUBFUL", "PUBVER", "NOCON", "DL ONLY", "FEDCON", "FED ONLY", "NPSONLY"), NPS=TRUE){ + + #verify CUI code entry; stop if does not equal one of six valid codes listed above: + CUIcode<-match.arg(CUIcode) + + #Generate new CUI element for additionalMetadata + myCUI<-list(metadata=list(CUI=CUIcode), id="CUI") + + #get existing additionalMetadata elements: + doc<-EML::eml_get(emlObject, "additionalMetadata") + + #if no prior additionalMetadata elements, add CUI to additionalMetadata: + if(sum(names(doc)!="@context")==0){ + emlObject$additionalMetadata<-myCUI } - if(CUI=="DLONLY"){ - CUI=="DL ONLY" + + #if additionalMetadata already exists: + if(sum(names(doc)!="@context")>0){ + mylist<-NULL + #ditch the '@context' list from doc: + for(i in seq_along(names(doc))){ + if(!names(doc)[i]=='@context' && !names(doc)[i]=="id"){ + mylist<-append(mylist, doc[i]) + } + x<-length(mylist) + } + + #Is CUI already specified? + existCUI<-NULL + for(i in seq_along(doc)){ + if(suppressWarnings(stringr::str_detect(doc[i], "CUI"))){ + existCUI<-"CUI" + } + } + + #If existing CUI, stop. + if(!is.null(existCUI)){ + stop("CUI has already been specified") + } + #If no existing CUI, add it in: + if(is.null(existCUI)){ + if(x==1){ + emlObject$additionalMetadata<-list(myCUI, emlObject$additionalMetadata) + } + if(x>1){ + emlObject$additionalMetadata[[x+1]]<-myCUI + } + } } - #add CUI to EML - emlObject$additionalMetadata$metadata$CUI<-CUI #Set NPS publisher, if it doesn't already exist if(NPS==TRUE){ @@ -203,22 +306,35 @@ set.CUI<-function(emlObject, CUI, NPS=TRUE){ #' #' @description set.DRRdoi adds the DOI of an associated DRR #' -#' @details adds uses the DataStore Reference ID for an associate DRR to the as a properly formatted DOI (prefaced with "DRR: ") to the tag. ####CAUTION: in the current implimentation this may overwrite any other useageCitation info. +#' @details adds uses the DataStore Reference ID for an associate DRR to the as a properly formatted DOI (prefaced with "DRR: ") to the element. Creates and populates required children elements for usageCitation including the DRR title, creator organization name, and report number. Note the default NPS=TRUE sets the DRR creator organization to NPS. If you do NOT want the organization name for the DRR to be NPS, set NPS="Your Favorite Organization". sets the id flag for this usageCitation to "associatedDRR". #' #' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(, from="xml"). #' @param DRRrefID a 7-digit string that is the DataStore Reference ID for the DRR associated with the data package. -#' @param NPS defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE +#' @param DRRtitle the title of the DRR as it appears in the DataStore Reference. +#' @param NPS defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. Also fills in organizationName for the DRR creator. If you are NOT publishing with NPS/for, set NPS="your organization name". #' @returns an EML-formatted R object #' @export #' @examples -#' set.DRRdoi(emlObject, "2293234") -set.DRRdoi<-function(emlObject, DRRrefID, NPS=TRUE){ - doi<-paste0("DRR: https://doi.org/10.36967", DRRdoi) - emlObject$dataset$useageCitation<-doi +#' DRRtitle<-"Data Release Report for Data Package 1234" +#' set.DRRdoi(emlObject, "2293234", DRRtitle) +set.DRRdoi<-function(emlObject, DRRrefID, DRRtitle, NPS=TRUE){ + if(NPS==TRUE){org<-"NPS"} + else{org<-NPS} + + doi<-paste0("DRR: https://doi.org/10.36967/", DRRrefID) + + cite<-EML::eml$usageCitation(alternateIdentifier = doi, + title = DRRtitle, + creator = EML::eml$creator( + organizationName = org), + report = EML::eml$report(reportNumber = DRRrefID), + id = "associatedDRR") + + emlObject$dataset$usageCitation<-cite #Set NPS publisher, if it doesn't already exist if(NPS==TRUE){ emlObject<-set.NPSpublisher(emlObject) - } + } #add/update EMLeditor and version to metadata: emlObject<-set.version(emlObject) return(emlObject) @@ -228,7 +344,7 @@ set.DRRdoi<-function(emlObject, DRRrefID, NPS=TRUE){ #' #' @description set.abstract adds (or replaces) a simple abstract. #' -#' @details checks for an abstract. If no abstract is found, it inserts the abstract given in @param abstract. If an existing abstract is found, the user is asked whether they want to replace it or not and the appropriate action is taken. Currently set.abstract does not allow for paragraphs or complex formatting. You are strongly encouraged to open your abstract in a text editor such as notepad and make sure there are no stray characers. If you need multiple paragraphs, you will need to do that via EMLassemblyline (for now). +#' @details checks for an abstract. If no abstract is found, it inserts the abstract given in @param abstract. If an existing abstract is found, the user is asked whether they want to replace it or not and the appropriate action is taken. Currently set.abstract does not allow for paragraphs or complex formatting. You are strongly encouraged to open your abstract in a text editor such as notepad and make sure there are no stray characters. If you need multiple paragraphs, you will need to do that via EMLassemblyline (for now). #' #' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EML::read_eml(, from="xml"). #' @param abstract is a text string that is your abstract. You can generate this directly in R or import a .txt file. @@ -236,7 +352,7 @@ set.DRRdoi<-function(emlObject, DRRrefID, NPS=TRUE){ #' @returns an EML-formatted R object #' @export #' @examples -#' set.abstract(emlObject "This is a very short abstract") +#' set.abstract(emlObject, "This is a very short abstract") set.abstract<-function(emlObject, abstract, NPS=TRUE){ doc<-arcticdatautils::eml_get_simple(emlObject, "abstract") if(is.null(doc)){ @@ -271,7 +387,7 @@ set.abstract<-function(emlObject, abstract, NPS=TRUE){ #' #' @details looks for literature cited in the tag and if it finds none, inserts bibtex-formatted literature cited from a the supplied *.bib file. If literature cited exists it asks to either do nothing, replace the existing literature cited with the supplied .bib file or append additional references from the supplied .bib file. #' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(, from="xml"). -#' @param bibtex is a text file with one or more bib-formatted references with the extension .bib. Make sure the .bib file is in your working directory, or supply the path to the file. +#' @param bibtex_file is a text file with one or more bib-formatted references with the extension .bib. Make sure the .bib file is in your working directory, or supply the path to the file. #' @param NPS defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE #' @return an EML object #' @export diff --git a/R/getEMLfunctions.R b/R/getEMLfunctions.R index 81e53a3..1021da7 100644 --- a/R/getEMLfunctions.R +++ b/R/getEMLfunctions.R @@ -5,9 +5,10 @@ #' @details returns the date from the tag. Although dates should be formatted according to ISO-8601 (YYYY-MM-DD) it will also check for a few other common formats and return the date as a text string: "DD Month YYYY" #' #' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(, from="xml"). +#' #' @return a text string #' @export -#' @examples +#' @example #' get.beginDate(emlObject) get.beginDate<-function(emlObject){ begin<-arcticdatautils::eml_get_simple(emlObject, "beginDate") @@ -26,10 +27,10 @@ get.beginDate<-function(emlObject){ #' #' @details returns the date from the tag. Although dates should be formatted according to ISO-8601 (YYYY-MM-DD) it will also check a few other common formats and return the date as a text string: "DD Month YYYY" #' -#' #' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(, from="xml"). +#' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(, from="xml"). #' @return a text sting #' @export -#' @examples +#' @example #' get.endDate(emlObject) get.endDate<-function(emlObject){ end<-arcticdatautils::eml_get_simple(emlObject, "endDate") @@ -64,7 +65,7 @@ get.abstract<-function(emlObject){ else{ Encoding(doc)<-"UTF-8" #helps with weird characters txt<-NULL - for(i in 1:length(doc)){ + for(i in seq_along(doc)){ if(nchar(doc[i])>0){ mypara <- gsub("[\r?\n|\r]", "", doc[i]) #get rid of line breaks and carriage returns mypara <- gsub(" ", " ", mypara) #get rid of carriage symbols @@ -86,7 +87,7 @@ get.abstract<-function(emlObject){ #' #' @details accesses all of the tags (there can be several, if each file was given a separate title). Assumes that the first instance of <title> referes to the entire data package and returns it as a text string, ignoring the contents of all other <title> tags. #' -#' #' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml"). +#' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml"). #' @return a text string #' @export #' @example @@ -117,7 +118,7 @@ get.DSRefID<-function(emlObject){ RefID<-NA # to do: check write.readMe whether NA needs to be in quotes. } else{ - for(i in 1:length(pid)){ + for(i in seq_along(pid)){ if(stringr::str_detect(pid[i], "doi: ")){ doi<-pid[i] } @@ -137,7 +138,7 @@ get.DSRefID<-function(emlObject){ #' #' @details allows the user to preview the what the citation will look like. The Harper's Ferry Style Guide recommends using the Chicago Manual of Style for formatting citations. The citation is formatted according to to a modified version of the Chicago Manual of Style's Author-Date journal article format because currently there is no Chicago Manual of Style format specified for datasets or data packages. In compliance wiht DataCite's recommendations regarding including DOIs in citations, the citation displays the entire DOI as https://www.doi.org/10.58370/xxxxxx". #' -#' #' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml"). +#' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml"). #' @return a text string #' @export #' @example @@ -189,7 +190,8 @@ get.citation<-function(emlObject){ #' #' @details get.authorList assumes every author has at least 1 first name (either <givenName> or <givenName1>) and only one last name (<surName>). Middle names (<givenName2>) are optional. The author List is formatted with the last name, comma, first name for the first author and the fist name, last name for all subsequent authors. The last author's name is preceeded by an 'and'. #' -#' #' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml"). +#' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml"). +#' #' @return a text string #' @export #' @example @@ -210,7 +212,7 @@ get.authorList<-function(emlObject){ #extract givenName; should handle middle names too! FirstName<-NULL first<-NULL - for(i in 1:length(authors)){ + for(i in seq_along(authors)){ if(stringr::str_detect(names(authors)[i], "givenName\\b")){ FirstName<-append(FirstName, authors[i][[1]]) } @@ -226,7 +228,7 @@ get.authorList<-function(emlObject){ #extract surName LastName<-NULL - for(i in 1:length(authors)){ + for(i in seq_along(authors)){ if(stringr::str_detect(names(authors)[i], "surName")){ LastName<-append(LastName, authors[i][[1]]) } @@ -244,7 +246,7 @@ get.authorList<-function(emlObject){ #multi-author: else{ - for(i in 1:length(LastName)){ + for(i in seq_along(LastName)){ if(i==1){ } if(i>1 && i<length(LastName)){ @@ -269,6 +271,7 @@ get.authorList<-function(emlObject){ #' @details accesses the contents of the<alternateIdentifier> tag and does some text manipulation to return a string with the DOI including the URL and prefaced by 'doi: '. #' #' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml"). +#' #' @return a text string #' @export #' @example @@ -283,7 +286,7 @@ get.DOI<-function(emlObject){ else{ mylist<-NULL if(length(pid)>=1){ - for(i in 1:length(pid)){ + for(i in seq_along(pid)){ if(stringr::str_detect(pid[i], "doi:" )){ mylist<-append(mylist, pid[i]) } @@ -313,18 +316,32 @@ get.parkUnits<-function(emlObject){ punits<-NA #to do: test whether NA needs quotes for write.README. } else{ - punits<-NULL - for(i in 1:length(units)){ + #pull out just geographic description for unit connections: + unitcons<-NULL + for(i in seq_along(units)){ if(stringr::str_detect(units[i], "NPS Unit Connections:")){ - punits<-units[i] + unitcons<-append(unitcons, units[i]) } } - if(is.null(punits)){ - warning("No Park Unit Connections specified. Use the set.parkUnits() function to add Park Unit Connections.") - punits<-NA #to do: test whether NA needs quotes for write.README. + + #make a string that is just comma separated unit connection codes: + punits<-NULL + for(i in seq_along(unitcons)){ + if(unitcons[i]== tail(unitcons, 1)){ + remtext<-sub('NPS Unit Connections: ', '', unitcons[i]) + punits<-append(punits, remtext) + } + else{ + remtext<-sub('NPS Unit Connections: ', '', unitcons[i]) + punits<-append(punits, paste0(remtext, ", ")) + } } + list.units<-paste(unlist(punits), collapse="", sep=",") + + #add "NPS Unit Connections: " prefix back in to the sting: + list.units<-paste0("NPS Unit Connections: ", list.units) } - return(punits[[1]]) + return(list.units) } #' returns a CUI statement @@ -377,6 +394,7 @@ get.CUI<-function(emlObject){ #' @details returns the file names (listed in the <objectName> tag), the size of the files (listed in the <size> tag) and converts it from bytes (B) to a more easily interpretable unit (KB, MB, GB, etc). Technically this uses powers of 2^10 so that KB is actually a kibibyte (1024 bytes) and not a kilobyte (1000 bytes). Similarly MB is a mebibyte not a megabyte, GB is a gibibyte not a gigabyte, etc. But for most practical purposes this is probably irrelevant. Finally, a short description is provided for each file (from the <entityDescription> tag). #' #' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml"). +#' #' @return a text string #' @export #' @example @@ -415,21 +433,22 @@ get.fileInfo<-function(emlObject){ #' #' @description get.DRRdoi returns a text string with the associated Data Release Report (DRR)'s DOI. #' -#' @details get.DRRdoi accesses the <useageCitation> tag(s) and searches for the string "DRR: https://doi.org/". If that string is found, the contents of that tag are returned. If the <useageCitation> tag is empty or not present, the user is informed and pointed to the set.DRRdoi() function to add the DOI of an associated DRR. +#' @details get.DRRdoi accesses the <usageCitation> tag(s) and searches for the string "DRR: https://doi.org/". If that string is found, the contents of that tag are returned. If the <usageCitation> tag is empty or not present, the user is informed and pointed to the set.DRRdoi() function to add the DOI of an associated DRR. #' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml"). +#' #' @return a text string #' @export #' @example #' get.DRRdoi(emlObject) get.DRRdoi<-function(emlObject){ - doi<-arcticdatautils::eml_get_simple(emlObject, "useageCitation") + doi<-arcticdatautils::eml_get_simple(emlObject, "usageCitation") if(is.null(doi)){ warning("You have not specified a DRR associated with this data package. If you have an associated DRR, specify its DOI using set.DRRdoi.") DRRdoi<-NA #to do: test whether NA needs quotes for write.README. } else{ DRRdoi<-NULL - for(i in 1:length(doi)){ + for(i in seq_along(doi)){ if(stringr::str_detect(doi[i], "DRR: https://doi.org/")){ DRRdoi<-doi[i] } @@ -443,15 +462,15 @@ get.DRRdoi<-function(emlObject){ #' #' @description get.lit prints bibtex fromated literature cited to the screen. #' -#' @details get.lit currently only supports bibtex formated references. get.lit gets items from the <literatureCited> tag and prints them to the screen. +#' @details get.lit currently only supports bibtex formatted references. get.lit gets items from the <literatureCited> tag and prints them to the screen. #' #' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml"). #' #' @return character string #' @export #' -#' @examples lit<-get.lit(emLObject); writeLines(lit) -#' +#' @examples +#' get.lit(emlObject) get.lit<-function(emlObject){ - lit<-eml_get_simple(emlObject, "literatureCited") + lit<-arcticdatautils::eml_get_simple(emlObject, "literatureCited") } diff --git a/R/utils.R b/R/utils.R index dcb630e..3758c0b 100644 --- a/R/utils.R +++ b/R/utils.R @@ -1,129 +1,181 @@ -#' alias for eml_get_simple +#' inject NPS Publisher info into metadata #' -#' @decription eml_get_simpleNPS is an alias for arcticdatautils eml_get_simple function +#' @description injects static NPS-specific publisher info into eml documents. Calls the sub-function set.forOrByNPS, which adds an additionalMetadata element with for or by NPS = TRUE. #' -#' @details eml_get_simpleNPS serves as an alias for the arcticdatautils function eml_get_simple. This means the eml_get_simple() function will be called using current local version of arcticdatautils on the users's machine rather than whatever version was available when the package was built. +#' @details checks to see if the publisher element exists, and if not injects NPS-specific info into EML such as publisher, publication location, and ROR id - the types of things that will be the same for all NPS data or non-data publications and do not require user input. This function will be embedded in all set. and write. class functions (and get. functions?). #' #' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml"). -#' @param elment is the name of the element to be extracted. If multiple occurances are found, will extract all. +#' +#' @return emlObject #' @export -eml_get_simpleNPS<-function(...)arcticdatautils::eml_get_simple() +#' +#' @examples +#' set.NPSpublisher(emlObject) +set.NPSpublisher<-function(emlObject){ + #get existing publisher info for the data package: + publish<-emlObject$dataset$publisher + + #create desired publisher info: + pubset<- list(organizationName = + "National Park Service", + address = list(deliveryPoint = "1201 Oakridge Drive, Suite 150", + city = "Fort Collins", + administrativeArea="CO", + postalCode="80525", + country="USA"), + onlineUrl = "http://www.nps.gov", + electronicMailAddress = "irma@nps.gov", + userId = list(directory="https://ror.org/", userId="https://ror.org/044zqqy65")) + + #if existing and desired publisher don't match, replace existing with desired. + if(!identical(publish, pubset)){ + emlObject$dataset$publisher<-pubset + } + + #since the publisher is NPS, sets an additionalMetadata field for For or By NPS to TRUE. + set.forByNPS(emlObject) -#' alias for eml_get + return(emlObject) +} + +#' Add/update EMLeditor version #' -#' @decription eml_getNPS is an alias for the EML get_simple function +#' @description set.version adds the current version of EMLeditor to the EML document. #' -#' @details eml_getNPS serves as an alias for the EML function eml_get. This means the eml_get() function will be called using current local version of EML on the users's machine rather than whatever version was available when the package was built. +#' @details set.version adds the current version of EMLeditor to the metadata, specifically in the "additionalMetadata" element #' -#' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml"). -#' @param elment is the name of the element to be extracted. If multiple occurrences are found, will extract all. +#' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EML::read_eml(<filename>, from="xml"). +#' +#' @return emlObject #' @export -eml_getNPS<-function(...)EML::eml_get() +#' +#' @examples +#' set.version(emlObject) +#' +set.version<-function(emlObject){ + #get current EMLeditor package version: + currentvers<-as.character(packageVersion("EMLeditor")) + + #set up additionalMetadata elements for EMLeditor: + EMLed<-list(metadata=list(emlEditor= + list(app="EMLeditor", + release=currentvers)), + id="emlEditor") + + #access additionalMetadata elements: + addMeta<-EML::eml_get(emlObject, "additionalMetadata") + + #if no additionalMetadata, add in EMLeditor and current version: + if(sum(names(addMeta)!="@context")==0){ + emlObject$additionalMetadata<-EMLed + } + + #if there are existing additionalMetadata elements: + if(sum(names(addMeta)!="@context")>0){ + + mylist<-NULL + #ditch the '@context' list from the goeCoverage: + for(i in seq_along(names(addMeta))){ + if(!names(addMeta)[i]=='@context' && !names(addMeta)[i]=="id"){ + mylist<-append(mylist, addMeta[i]) + } + } + x<-length(mylist) + + #does it include EMLeditor? + app<-NULL + for(i in seq_along(addMeta)){ + if(suppressWarnings(stringr::str_detect(addMeta[i], "EMLeditor"))){ + app<-"EMLeditor" + } + } + #if no info on EMLeditor, add EMLeditor to additionalMetadata + if(is.null(app)){ + if(x==1){ + emlObject$additionalMetadata<-list(EMLed, emlObject$additionalMetadata) + } + if(x>1){ + emlObject$additionalMetadata[[x+1]]<-EMLed + } + } + } + return(emlObject) +} -#' inject NPS info into metadata +#' Get Park Unit Polygon #' -#' @description injects static NPS-specific info into eml documents +#' @description get.unitPolygon gets the polygon for a given park unit. #' -#' @details checks to see if it exists, and if not injects NPS-specific info into EML such as publisher, publication location, and ROR id - the types of things that will be the same for all NPS data or non-data publications and do not require user input. This function will be embedded in all set. and write. class functions (and get. functions?) - -#' @param emlObject +#' @details retrieves a geoJSON string for a polygon of a park unit from NPS Rest services. Note: This is not the official boundary (erm... ok then what is it?!?). +#' +#' @param Unit_Code a string (typically 4 characters) that is the park unit code. #' #' @return #' @export #' #' @examples -set.NPSpublisher<-function(emlObject){ - #check for and isert publisher information: - publish<-arcticdatautils::eml_get_simple(emlObject, "publisher") - if(is.null(publish)){ - emlObject$dataset$publisher <-list(organizationName = "U.S. National Park Service", - onlineUrl = "http://www.nps.gov", - userId = "https://ror.org/044zqqy65", - electronicMailAddress = "irma@nps.gov") - #note: oddly defaults to alphabetical order in .xml. Not sure why or how to stop this not sure it matters. - emlObject$dataset$publisher$address<-list(deliveryPoint = "1201 Oakridge Drive, Suite 150", - city = "Fort Collins", - administrativeArea = "CO", - postalCode = "80525", - country = "USA") - } - return(emlObject) +#' poly<-get.unitPolygon("BICY") +get.unitPolygon <- function(Unit_Code) { + # get geography from NPS Rest Services + UnitsURL <- paste0("https://irmaservices.nps.gov/v2/rest/unit/", Unit_Code, "/geography") + xml <- httr::content(httr::GET(UnitsURL)) + + # Create spatial feature from polygon info returned from NPS + parkpolygon <- sf::st_as_sfc(xml[[1]]$Geography, geoJSON = TRUE) + + return(parkpolygon) } -#' Add EMLeditory version +#' Set "For or By" NPS #' -#' @description set.version adds the current version of EMLeditor to the metadata +#' @description set.forByNPS adds an element to additionalMetadata with For or By NPS set to TRUE and a second element agencyOriginated set to "NPS" with the understanding that all data products created for or by the NPS have NPS as the originating agency. #' -#' @details set.version adds the current version of EMLeditor to the metadata, specifically in the -#' @param emlObject +#' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EML::read_eml(<filename>, from="xml"). +#' +#' @return emlObject #' -#' @return #' @export #' #' @examples -#' set.version(emlObject) -set.version<-function(emlObject){ - currentvers<-"v0.1.0-beta" #hard coding needs updating with each new release - #access additionalMetadata elements about emlEditor(s): - release<-EML::eml_get(emlObject, "emlEditor") +#' set.forByNPS(emlObject) +set.forByNPS<-function(emlObject){ + + #set up additionalMetadata elements for EMLeditor: + forby<-list(metadata=list(For_or_by_NPS="TRUE", + agencyOriginated="NPS"), + id="agencyOriginated") - #if no info on EMLeditors, add in EMLeditor and version: - if(sum(names(release)!="@context")==0){ - emlObject$additionalMetadata$metadata$emlEditor<-list(app="EMLeditor", release=currentvers) + #access additionalMetadata elements: + addMeta<-EML::eml_get(emlObject, "additionalMetadata") + addMeta<-within(addMeta, rm('@context')) + + #if no additionalMetadata, add in EMLeditor and current version: + if(seq_along(names(addMeta))==0){ + emlObject$additionalMetadata<-forby } - #if there is info about emlEditors: - if(sum(names(release)!="@context")>0){ + #if there are existing additionalMetadata elements: + if(seq_along(names(addMeta))>0){ + x<-length(addMeta) #does it include EMLeditor? - app<-NULL - for(i in 1:length(release)){ - if(suppressWarnings(stringr::str_detect(release[i], "EMLeditor"))){ - app<-"EMLeditor" + For_or_by_NPS<-NULL + for(i in seq_along(addMeta)){ + if(suppressWarnings(stringr::str_detect(addMeta[i], "For_or_by_NPS"))){ + For_or_by_NPS<-"TRUE" } } - #if no info, add EMLeditor to additionalMetadata - if(is.null(app)){ - existlist<-NULL - for(i in 1:length(names(release))){ - if(!names(release)[i]=='@context'){ - existlist<-append(existlist, release[i]) - } + #if no info on ForOrByNPS, add ForOrByNPS to additionalMetadata + if(is.null(For_or_by_NPS)){ + if(x==1){ + emlObject$additionalMetadata<-list(forby, emlObject$additionalMetadata) } - #construct new additionalMetadata list: - existlist<-list(existlist) - emleds<-list(app="EMLeditor", release=currentvers) - existlist<-append(existlist, list(emleds)) - #overwrite existing additionalMetadata: - emlObject$additionalMetadata$metadata$emlEditor<-existlist - } - - #if EMLeditor is included, but the version is wrong, update version - if(!is.null(app)){ - for(i in 1:length(release)){ - if(suppressWarnings(stringr::str_detect(release[i], "EMLeditor"))){ - #could prob remove if statement and just sub it in no matter what - if(release[[i]][2]!=currentvers){ - #sub old version with new version: - release[[i]][2]<-currentvers - } - } + if(x>1){ + emlObject$additionalMetadata[[x+1]]<-forby } - mylist<-NULL - for(i in 1:length(names(release))){ - if(!names(release)[i]=='@context'){ - mylist<-append(mylist, release[i]) - } - } - #names to null critical for writing to xml - names(mylist)<-NULL - #overwrite existing additionalMetadata with new version info - emlObject$additionalMetadata$metadata$emlEditor<-mylist } } return(emlObject) } - - diff --git a/README.Rmd b/README.Rmd index 6d012a7..78a350e 100644 --- a/README.Rmd +++ b/README.Rmd @@ -14,7 +14,7 @@ knitr::opts_chunk$set( ``` # EMLeditor -##### v0.1.0-beta +##### v0.0.1.0 ##### "Lilly Lake Loop" @@ -27,12 +27,12 @@ EMLeditor's primary objective is to edit and view EML formatted files, not to ge 1) Use the EMLassemblyline::make_eml() to generate an initial EML document and save it as a .xml file (NPS naming convention is: *_metadata.xml) 2) Use the EML::read_eml() function to load your EML file into R as an R object. -3) Use EMLeditor functions to edit the metadata in R and evaluate whether your metadata is acceptable. +3) 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). 4) 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). -If you use EMLeditor functions they will silently add the National Park Service as a publisher to your metadata unless you set NPS=FALSE. +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, 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 your 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 @@ -54,10 +54,14 @@ 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 automatically generated when you initiate a draft Reference. +#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") @@ -78,6 +82,9 @@ my_eml<-EML::read_eml("my_EML_metadata.xml", from="xml") #If NPS is the publisher, this defaults to TRUE and need not be specified. my_eml2<-set.lit(my_eml, bibtex_file, NPS=FALSE) +#make sure your EML is valid: +EML::eml_validate(my_eml2) + #writes a .txt file to your working directory. #(FYI Lit cited doesn't show up in the mock readme) write.readMe(my_eml2, "MockReadMe.txt") diff --git a/README.md b/README.md index 96ddfd1..6c6d3af 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ # EMLeditor -##### v0.1.0-beta +##### v0.0.1.0 ##### “Lilly Lake Loop” @@ -26,16 +26,22 @@ not to generate them from scratch. A suggested workflow is: 2) Use the EML::read_eml() function to load your EML file into R as an R object. 3) Use EMLeditor functions to edit the metadata in R and evaluate - whether your metadata is acceptable. + whether your metadata is acceptable (don’t forget to use + EML::eml_validate() to make sure you are generating valid EML). 4) 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). -If you use EMLeditor functions they will silently add the National Park -Service as a publisher to your metadata unless you set NPS=FALSE. +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, 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 your metadata. +used to edit your metadata (for instance if you used “set” class +functions). ## Installation @@ -58,10 +64,14 @@ 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 automatically generated when you initiate a draft Reference. +#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") ``` @@ -87,6 +97,9 @@ my_eml<-EML::read_eml("my_EML_metadata.xml", from="xml") #If NPS is the publisher, this defaults to TRUE and need not be specified. my_eml2<-set.lit(my_eml, bibtex_file, NPS=FALSE) +#make sure your EML is valid: +EML::eml_validate(my_eml2) + #writes a .txt file to your working directory. #(FYI Lit cited doesn't show up in the mock readme) write.readMe(my_eml2, "MockReadMe.txt") diff --git a/man/eml_getNPS.Rd b/man/eml_getNPS.Rd deleted file mode 100644 index fa654d6..0000000 --- a/man/eml_getNPS.Rd +++ /dev/null @@ -1,19 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utils.R -\name{eml_getNPS} -\alias{eml_getNPS} -\title{alias for eml_get} -\usage{ -eml_getNPS(...) -} -\arguments{ -\item{emlObject}{is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml").} - -\item{elment}{is the name of the element to be extracted. If multiple occurrences are found, will extract all.} -} -\description{ -alias for eml_get -} -\details{ -eml_getNPS serves as an alias for the EML function eml_get. This means the eml_get() function will be called using current local version of EML on the users's machine rather than whatever version was available when the package was built. -} diff --git a/man/eml_get_simpleNPS.Rd b/man/eml_get_simpleNPS.Rd deleted file mode 100644 index ecf71d6..0000000 --- a/man/eml_get_simpleNPS.Rd +++ /dev/null @@ -1,19 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utils.R -\name{eml_get_simpleNPS} -\alias{eml_get_simpleNPS} -\title{alias for eml_get_simple} -\usage{ -eml_get_simpleNPS(...) -} -\arguments{ -\item{emlObject}{is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml").} - -\item{elment}{is the name of the element to be extracted. If multiple occurances are found, will extract all.} -} -\description{ -alias for eml_get_simple -} -\details{ -eml_get_simpleNPS serves as an alias for the arcticdatautils function eml_get_simple. This means the eml_get_simple() function will be called using current local version of arcticdatautils on the users's machine rather than whatever version was available when the package was built. -} diff --git a/man/get.DRRdoi.Rd b/man/get.DRRdoi.Rd index 0d9c300..bf6e350 100644 --- a/man/get.DRRdoi.Rd +++ b/man/get.DRRdoi.Rd @@ -16,5 +16,5 @@ a text string get.DRRdoi returns a text string with the associated Data Release Report (DRR)'s DOI. } \details{ -get.DRRdoi accesses the <useageCitation> tag(s) and searches for the string "DRR: https://doi.org/". If that string is found, the contents of that tag are returned. If the <useageCitation> tag is empty or not present, the user is informed and pointed to the set.DRRdoi() function to add the DOI of an associated DRR. +get.DRRdoi accesses the <usageCitation> tag(s) and searches for the string "DRR: https://doi.org/". If that string is found, the contents of that tag are returned. If the <usageCitation> tag is empty or not present, the user is informed and pointed to the set.DRRdoi() function to add the DOI of an associated DRR. } diff --git a/man/get.authorList.Rd b/man/get.authorList.Rd index 9b072fa..cfb1017 100644 --- a/man/get.authorList.Rd +++ b/man/get.authorList.Rd @@ -6,6 +6,9 @@ \usage{ get.authorList(emlObject) } +\arguments{ +\item{emlObject}{is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml").} +} \value{ a text string } @@ -14,6 +17,4 @@ get.authorList returns a text string with all of the authors listed under the <c } \details{ get.authorList assumes every author has at least 1 first name (either <givenName> or <givenName1>) and only one last name (<surName>). Middle names (<givenName2>) are optional. The author List is formatted with the last name, comma, first name for the first author and the fist name, last name for all subsequent authors. The last author's name is preceeded by an 'and'. - -#' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml"). } diff --git a/man/get.beginDate.Rd b/man/get.beginDate.Rd index ddef1a1..e198d7c 100644 --- a/man/get.beginDate.Rd +++ b/man/get.beginDate.Rd @@ -18,6 +18,3 @@ get.beginDate returns the date of the earliest data point in the data package \details{ returns the date from the <beginDate> tag. Although dates should be formatted according to ISO-8601 (YYYY-MM-DD) it will also check for a few other common formats and return the date as a text string: "DD Month YYYY" } -\examples{ -get.beginDate(emlObject) -} diff --git a/man/get.citation.Rd b/man/get.citation.Rd index 02f96a5..b1507fe 100644 --- a/man/get.citation.Rd +++ b/man/get.citation.Rd @@ -6,6 +6,9 @@ \usage{ get.citation(emlObject) } +\arguments{ +\item{emlObject}{is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml").} +} \value{ a text string } @@ -14,6 +17,4 @@ returns a Chicago manual of style citation for the data package } \details{ allows the user to preview the what the citation will look like. The Harper's Ferry Style Guide recommends using the Chicago Manual of Style for formatting citations. The citation is formatted according to to a modified version of the Chicago Manual of Style's Author-Date journal article format because currently there is no Chicago Manual of Style format specified for datasets or data packages. In compliance wiht DataCite's recommendations regarding including DOIs in citations, the citation displays the entire DOI as https://www.doi.org/10.58370/xxxxxx". - -#' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml"). } diff --git a/man/get.endDate.Rd b/man/get.endDate.Rd index d7321ea..38298d2 100644 --- a/man/get.endDate.Rd +++ b/man/get.endDate.Rd @@ -6,6 +6,9 @@ \usage{ get.endDate(emlObject) } +\arguments{ +\item{emlObject}{is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml").} +} \value{ a text sting } @@ -13,10 +16,5 @@ a text sting get.endDate returns the date of the last data point in the data package } \details{ -returns the date from the <endDate> tag. Although dates should be formatted accoriding to ISO-8601 (YYYY-MM-DD) it will also check a few other common formats and return the date as a text string: "DD Month YYYY" - -#' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml"). -} -\examples{ -get.endDate(emlObject) +returns the date from the <endDate> tag. Although dates should be formatted according to ISO-8601 (YYYY-MM-DD) it will also check a few other common formats and return the date as a text string: "DD Month YYYY" } diff --git a/man/get.lit.Rd b/man/get.lit.Rd index 295a4cf..57b6f24 100644 --- a/man/get.lit.Rd +++ b/man/get.lit.Rd @@ -16,9 +16,8 @@ character string get.lit prints bibtex fromated literature cited to the screen. } \details{ -get.lit currently only supports bibtex formated references. get.lit gets items from the <literatureCited> tag and prints them to the screen. +get.lit currently only supports bibtex formatted references. get.lit gets items from the <literatureCited> tag and prints them to the screen. } \examples{ -lit<-get.lit(emLObject); writeLines(lit) - +get.lit(emlObject) } diff --git a/man/get.parkUnits.Rd b/man/get.parkUnits.Rd index 0380dfc..a5959b8 100644 --- a/man/get.parkUnits.Rd +++ b/man/get.parkUnits.Rd @@ -16,5 +16,5 @@ a text string returns a string with the park unit codes where the data were collected } \details{ -accesses the contents of the <geographicDescription> tags and returns the contents of the tag that containst the text "NPS Unit Connections". If there is no <geographicDescription>, it alerts the user and suggests adding park unit connections using the set.parkUnits() function. +accesses the contents of the <geographicDescription> tags and returns the contents of the tag that contains the text "NPS Unit Connections". If there is no <geographicDescription>, it alerts the user and suggests adding park unit connections using the set.parkUnits() function. } diff --git a/man/get.title.Rd b/man/get.title.Rd index 2f215ca..c82917c 100644 --- a/man/get.title.Rd +++ b/man/get.title.Rd @@ -6,6 +6,9 @@ \usage{ get.title(emlObject) } +\arguments{ +\item{emlObject}{is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml").} +} \value{ a text string } @@ -14,6 +17,4 @@ returns a text string that is the title of the data package } \details{ accesses all of the <title> tags (there can be several, if each file was given a separate title). Assumes that the first instance of <title> referes to the entire data package and returns it as a text string, ignoring the contents of all other <title> tags. - -#' @param emlObject is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml"). } diff --git a/man/get.unitPolygon.Rd b/man/get.unitPolygon.Rd new file mode 100644 index 0000000..27a49eb --- /dev/null +++ b/man/get.unitPolygon.Rd @@ -0,0 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/utils.R +\name{get.unitPolygon} +\alias{get.unitPolygon} +\title{Get Park Unit Polygon} +\usage{ +get.unitPolygon(Unit_Code) +} +\arguments{ +\item{Unit_Code}{a string (typically 4 characters) that is the park unit code.} +} +\description{ +get.unitPolygon gets the polygon for a given park unit. +} +\details{ +retrieves a geoJSON string for a polygon of a park unit from NPS Rest services. Note: This is not the official boundary (erm... ok then what is it?!?). +} +\examples{ +poly<-get.unitPolygon("BICY") +} diff --git a/man/edit.DOI.Rd b/man/new.DOI.Rd similarity index 79% rename from man/edit.DOI.Rd rename to man/new.DOI.Rd index dc2e54b..8f5a276 100644 --- a/man/edit.DOI.Rd +++ b/man/new.DOI.Rd @@ -1,23 +1,23 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/editEMLfunctions.R -\name{edit.DOI} -\alias{edit.DOI} +\name{new.DOI} +\alias{new.DOI} \title{Force-edits an existing DOI} \usage{ -\method{edit}{DOI}(emlObject, DSref, NPS = TRUE) +new.DOI(emlObject, DSref, NPS = TRUE) } \arguments{ \item{emlObject}{is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml").} -\item{DSref}{is the same as the 7-digit reference code generated on DataStore when the draft reference is initiated. Don't worry about the https://wwww.doi.org and thedata package prefix - those will all automatically be added in by the function.} +\item{DSref}{is the same as the 7-digit reference code generated on DataStore when the draft reference is initiated. Don't worry about the https://wwww.doi.org and the data package prefix - those will all automatically be added in by the function.} -\item{NPS}{defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE} +\item{NPS}{defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE.} } \value{ an EML-formatted R object } \description{ -edit.DOI forces changes to an existing DOI +new.DOI forces changes to an existing DOI } \details{ If a DOI already exists in the <alternateidentifier> tag (get.DOI() to check), this allows the user to over-write the existing DOI. WARNING: will cause loss of the system="https://doi.org" setting. So only use this if you really don't already have a DOI. diff --git a/man/set.CUI.Rd b/man/set.CUI.Rd index fe55d8b..ad4b05e 100644 --- a/man/set.CUI.Rd +++ b/man/set.CUI.Rd @@ -4,18 +4,23 @@ \alias{set.CUI} \title{Adds CUI to metadata} \usage{ -set.CUI(emlObject, CUI, NPS = TRUE) +set.CUI( + emlObject, + CUIcode = c("PUBFUL", "PUBVER", "NOCON", "DL ONLY", "FEDCON", "FED ONLY", "NPSONLY"), + NPS = TRUE +) } \arguments{ \item{emlObject}{is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml").} -\item{CUI}{a string consisting of one of 5 potential CUI codes. Pay attention to the spaces: +\item{CUIcode}{a string consisting of one of 7 potential CUI codes (defaults to "PUBFUL"). Pay attention to the spaces: FED ONLY - Contains CUI. Only federal employees should have access (similar to "internal only" in DataStore) FEDCON - Contains CUI. Only federal employees and federal contractors should have access (also very much like current "internal only" setting in DataStore) DL ONLY - Contains CUI. Should only be available to a names list of individuals (where and how to list those individuals TBD) NOCON - Contains CUI. Federal, state, local, or tribal employees may have access, but contractors cannot. -PUBVER - Does NOT contain CUI. The original data contained CUI, but in thisdata package CUI have been obscured so that it no longer contains CUI. -PUBFUL - Does NOT contain CUI. The original data contained no CUI. No data were obscured or altered to generate the data package} +PUBVER - Does NOT contain CUI. The original data contained CUI, but in this data package CUI have been obscured so that it no longer contains CUI. +PUBFUL - Does NOT contain CUI. The original data contained no CUI. No data were obscured or altered to generate the data package. +NPSONLY - Contains CUI. For NPS access only.} \item{NPS}{defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE} } diff --git a/man/set.DOI.Rd b/man/set.DOI.Rd index 2103a44..59fbc66 100644 --- a/man/set.DOI.Rd +++ b/man/set.DOI.Rd @@ -11,7 +11,7 @@ set.DOI(emlObject, DSref, NPS = TRUE) \item{DSref}{is the same as the 7-digit reference code generated on DataStore when a draft reference is initiated.} -\item{NPS}{defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE} +\item{NPS}{is a logical that defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE} } \value{ an EML-formatted R object diff --git a/man/set.DRRdoi.Rd b/man/set.DRRdoi.Rd index caeb866..107cec5 100644 --- a/man/set.DRRdoi.Rd +++ b/man/set.DRRdoi.Rd @@ -4,14 +4,16 @@ \alias{set.DRRdoi} \title{adds DRR connection} \usage{ -set.DRRdoi(emlObject, DRRrefID, NPS = TRUE) +set.DRRdoi(emlObject, DRRrefID, DRRtitle, NPS = TRUE) } \arguments{ \item{emlObject}{is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml").} \item{DRRrefID}{a 7-digit string that is the DataStore Reference ID for the DRR associated with the data package.} -\item{NPS}{defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE} +\item{DRRtitle}{the title of the DRR as it appears in the DataStore Reference.} + +\item{NPS}{defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. Also fills in organizationName for the DRR creator. If you are NOT publishing with NPS/for, set NPS="your organization name".} } \value{ an EML-formatted R object @@ -20,8 +22,9 @@ an EML-formatted R object set.DRRdoi adds the DOI of an associated DRR } \details{ -adds uses the DataStore Reference ID for an associate DRR to the <useageCitation> as a properly formatted DOI (prefaced with "DRR: ") to the <useageCitation> tag. ####CAUTION: in the current implimentation this may overwrite any other useageCitation info. +adds uses the DataStore Reference ID for an associate DRR to the <usageCitation> as a properly formatted DOI (prefaced with "DRR: ") to the <usageCitation> element. Creates and populates required children elements for usageCitation including the DRR title, creator organization name, and report number. Note the default NPS=TRUE sets the DRR creator organization to NPS. If you do NOT want the organization name for the DRR to be NPS, set NPS="Your Favorite Organization". sets the id flag for this usageCitation to "associatedDRR". } \examples{ -set.DRRdoi(emlObject, "2293234") +DRRtitle<-"Data Release Report for Data Package 1234" +set.DRRdoi(emlObject, "2293234", DRRtitle) } diff --git a/man/set.NPSpublisher.Rd b/man/set.NPSpublisher.Rd index c412088..701e3df 100644 --- a/man/set.NPSpublisher.Rd +++ b/man/set.NPSpublisher.Rd @@ -2,16 +2,22 @@ % Please edit documentation in R/utils.R \name{set.NPSpublisher} \alias{set.NPSpublisher} -\title{inject NPS info into metadata} +\title{inject NPS Publisher info into metadata} \usage{ set.NPSpublisher(emlObject) } \arguments{ -\item{emlObject}{} +\item{emlObject}{is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml").} +} +\value{ +emlObject } \description{ -injects static NPS-specific info into eml documents +injects static NPS-specific publisher info into eml documents. Calls the sub-function set.forOrByNPS, which adds an additionalMetadata element with for or by NPS = TRUE. } \details{ -checks to see if it exists, and if not injects NPS-specific info into EML such as publisher, publication location, and ROR id - the types of things that will be the same for all NPS data or non-data publications and do not require user input. This function will be embedded in all set. and write. class functions (and get. functions?) +checks to see if the publisher element exists, and if not injects NPS-specific info into EML such as publisher, publication location, and ROR id - the types of things that will be the same for all NPS data or non-data publications and do not require user input. This function will be embedded in all set. and write. class functions (and get. functions?). +} +\examples{ +set.NPSpublisher(emlObject) } diff --git a/man/set.abstract.Rd b/man/set.abstract.Rd index 109a995..f9c6b7d 100644 --- a/man/set.abstract.Rd +++ b/man/set.abstract.Rd @@ -20,8 +20,8 @@ an EML-formatted R object set.abstract adds (or replaces) a simple abstract. } \details{ -checks for an abstract. If no abstract is found, it inserts the abstract given in @param abstract. If an existing abstract is found, the user is asked whether they want to replace it or not and the appropriate action is taken. Currently set.abstract does not allow for paragraphs or complex formatting. You are strongly encouraged to open your abstract in a text editor such as notepad and make sure there are no stray characers. If you need multiple paragraphs, you will need to do that via EMLassemblyline (for now). +checks for an abstract. If no abstract is found, it inserts the abstract given in @param abstract. If an existing abstract is found, the user is asked whether they want to replace it or not and the appropriate action is taken. Currently set.abstract does not allow for paragraphs or complex formatting. You are strongly encouraged to open your abstract in a text editor such as notepad and make sure there are no stray characters. If you need multiple paragraphs, you will need to do that via EMLassemblyline (for now). } \examples{ -set.abstract(emlObject "This is a very short abstract") +set.abstract(emlObject, "This is a very short abstract") } diff --git a/man/set.forByNPS.Rd b/man/set.forByNPS.Rd new file mode 100644 index 0000000..d1fbb4d --- /dev/null +++ b/man/set.forByNPS.Rd @@ -0,0 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/utils.R +\name{set.forByNPS} +\alias{set.forByNPS} +\title{Set "For or By" NPS} +\usage{ +set.forByNPS(emlObject) +} +\arguments{ +\item{emlObject}{is an R object imported (typically from an EML-formatted .xml file) using EML::read_eml(<filename>, from="xml").} +} +\value{ +emlObject +} +\description{ +set.forByNPS adds an element to additionalMetadata with For or By NPS set to TRUE and a second element agencyOriginated set to "NPS" with the understanding that all data products created for or by the NPS have NPS as the originating agency. +} +\examples{ +set.forByNPS(emlObject) +} diff --git a/man/set.lit.Rd b/man/set.lit.Rd index d3ae8a3..72e727c 100644 --- a/man/set.lit.Rd +++ b/man/set.lit.Rd @@ -9,9 +9,9 @@ set.lit(emlObject, bibtex_file, NPS = TRUE) \arguments{ \item{emlObject}{is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml").} -\item{NPS}{defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE} +\item{bibtex_file}{is a text file with one or more bib-formatted references with the extension .bib. Make sure the .bib file is in your working directory, or supply the path to the file.} -\item{bibtex}{is a text file with one or more bib-formatted references with the extension .bib. Make sure the .bib file is in your working directory, or supply the path to the file.} +\item{NPS}{defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE} } \value{ an EML object diff --git a/man/set.parkUnits.Rd b/man/set.parkUnits.Rd index 4ff1d05..e7c3938 100644 --- a/man/set.parkUnits.Rd +++ b/man/set.parkUnits.Rd @@ -2,14 +2,14 @@ % Please edit documentation in R/editEMLfunctions.R \name{set.parkUnits} \alias{set.parkUnits} -\title{Adds Park Unit Connections to metadata} +\title{Add Park Unit Connections to metadata} \usage{ set.parkUnits(emlObject, ParkUnits, NPS = TRUE) } \arguments{ \item{emlObject}{is an R object imported (typically from an EML-formatted .xml file) using EmL::read_eml(<filename>, from="xml").} -\item{ParkUnits}{a string of comma-separated park unit codes} +\item{ParkUnits}{a list of comma-separated strings where each string is a park unit code.} \item{NPS}{defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE} } @@ -17,10 +17,10 @@ set.parkUnits(emlObject, ParkUnits, NPS = TRUE) an EML-formatted R object } \description{ -Adds Park Unit Connections to metadata +adds all specified park unit connections and their N, E, S, W bounding boxes to <geographicCoverage>. } \details{ -Add the Park Unit Connection(s) to a <geographicDescription> tag under <coverage>. Park Unit Connection(s) are the (typically) four-letter codes describing the park unit(s) where data were collected (e.g. ROMO, not ROMN). If there are already =items listed under geographicCoverage, Park Unit Connections will be inserted as the first item in the list of geographicCoverages and will be prefaced by the string "NPS Unit Connections:". +Adds the Park Unit Connection(s) to a <coverage>. Park Unit Connection(s) are the (typically) four-letter codes describing the park unit(s) where data were collected (e.g. ROMO, not ROMN). Each park unit connection is given a separate <geographicCoverage> element. For each park unit connection, the unit name will be listed under <geographicDescription> and prefaced with "NPS Unit Connections:". Required child elements (bounding coordinates) are auto populated. If other <geographicCoverage> elements exist, set.parkUnits will add to them, not overwrite them. If not other <geographicCoverage> elements exist, set.parkUnits will create a new set of <geographicCoverage> elements. } \examples{ ParkUnits<-("ROMO, GRSD, TRYME") diff --git a/man/set.title.Rd b/man/set.title.Rd new file mode 100644 index 0000000..42163fb --- /dev/null +++ b/man/set.title.Rd @@ -0,0 +1,28 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/editEMLfunctions.R +\name{set.title} +\alias{set.title} +\title{Edit data package title} +\usage{ +set.title(emlObject, DataPackageTitle, NPS = TRUE) +} +\arguments{ +\item{emlObject}{is an R object imported (typically from an EML-formatted .xml file) using EML::read_eml(<filename>, from="xml").} + +\item{DataPackageTitle}{is a character string that will become the new title for the data package. It can be specified directly in the function call or it can be a previously defined object that holds a character string.} + +\item{NPS}{is a logical that defaults to TRUE. Checks EML for NPS publisher info and injects it if publisher is empty. If publisher already exists, does nothing. If you are not publishing with NPS, set to FALSE} +} +\value{ +an EML-formatted R object +} +\description{ +Edit data package title +} +\details{ +The set.Title function checks to see if there is an existing title and then asks the user if they would like to change the title. Some work is still needed on this function as get_eml() automatically returns all instances of a given tag. Specifying which title will be important for this function to work well. +} +\examples{ +DataPackageTitle<-"New Title. Must match DataStore Reference title." +set.title(emlObject, DataPackageTitle) +} diff --git a/man/set.version.Rd b/man/set.version.Rd index 3de25dd..fd2ce8a 100644 --- a/man/set.version.Rd +++ b/man/set.version.Rd @@ -2,19 +2,23 @@ % Please edit documentation in R/utils.R \name{set.version} \alias{set.version} -\title{Add EMLeditory version} +\title{Add/update EMLeditor version} \usage{ set.version(emlObject) } \arguments{ -\item{emlObject}{} +\item{emlObject}{is an R object imported (typically from an EML-formatted .xml file) using EML::read_eml(<filename>, from="xml").} +} +\value{ +emlObject } \description{ -set.version adds the current version of EMLeditor to the metadata +set.version adds the current version of EMLeditor to the EML document. } \details{ -set.version adds the current version of EMLeditor to the metadata, specifically in the +set.version adds the current version of EMLeditor to the metadata, specifically in the "additionalMetadata" element } \examples{ set.version(emlObject) + }