updated metadata entries and documentation

.buildlibrary

@@ -1,4 +1,4 @@
-ValidationKey: '34569960'
+ValidationKey: '34575540'
 AcceptedWarnings:
 - 'Warning: package ''.*'' was built under R version'
 - 'Warning: namespace ''.*'' is not available and has been replaced'

DESCRIPTION

@@ -2,7 +2,7 @@ Package: madrat
 Type: Package
 Title: May All Data be Reproducible and Transparent (MADRaT) *
 Version: 1.86.0
-Date: 2020-11-20
+Date: 2020-11-23
 Authors@R: c(person("Jan Philipp", "Dietrich", email = "dietrich@pik-potsdam.de", role = c("aut","cre")),
              person("Lavinia", "Baumstark", email = "lavinia@pik-potsdam.de", role = "aut"),
              person("Stephen", "Wirth", email = "wirth@pik-potsdam.de", role = "aut"),

R/calcTauTotal.R

@@ -33,8 +33,7 @@ calcTauTotal <- function(source="paper") {
               description="Agricultural Land Use Intensity Tau",
               note=c('data based on Dietrich J.P., Schmitz C., M\uFCller C., Fader M., Lotze-Campen H., Popp A.,',
                      'Measuring agricultural land-use intensity - A global analysis using a model-assisted approach',
-                     'Ecological Modelling, Volume 232, 10 May 2012, Pages 109-118, ISSN 0304-3800, 10.1016/j.ecolmodel.2012.03.002.',
-                     'preprint available \u40 https://doi.org/10.1016/j.ecolmodel.2012.03.002'),
+                     'Ecological Modelling, Volume 232, 10 May 2012, Pages 109-118, ISSN 0304-3800, https://doi.org/10.1016/j.ecolmodel.2012.03.002.'),
               source=bibentry("Article",
                               title="Measuring agricultural land-use intensity - A global analysis using a model-assisted approach",
                               author=c(person("Jan Philipp","Dietrich"),person("Christoph","Schmitz"),person("Christoph","Mueller"),person("Marianela","Fader"),

R/downloadSource.R

@@ -11,6 +11,27 @@
 #' have subtypes, subtypes should not be set.
 #' @param overwrite Boolean deciding whether existing data should be
 #' overwritten or not.
+#' @note The underlying download-functions are required to provide a list of information back to 
+#' \code{downloadSource}. Following list entries should be provided:
+#' \itemize{
+#' \item \bold{url} - full path to the file that should be downloaded
+#' \item \bold{title} - title of the data source
+#' \item \bold{author} - author(s) of the data set
+#' \item \bold{license} - license of the data set. Put \bold{unknown} if not specified.
+#' \item \bold{doi} (optional) - a DOI URL to the data source
+#' \item \bold{version} (optional) - version number of the data set
+#' \item \bold{release_date} (optional) - release date of the data set
+#' \item \bold{reference} (optional) - A reference for the data set (e.g. a paper, if the data was derived from it) 
+#' }
+#' This user-provided data is enriched by automatically derived metadata:
+#' \itemize{
+#' \item \bold{call} - Information about the used madrat function call to download the data
+#' will check whether there are any values below the given threshold and warn in this case
+#' \item \bold{accessibility} - A measure of quality for the accessibility of the data. Currently it distinguished between
+#' \bold{iron} (manual access), \bold{silver} (automatic access via URL) and \bold{gold} (automatic access via DOI).
+#' }
+#' Besides the names above (user-provided and automatically derived) it is possible to add custom metadata entries by extending
+#' the return list with additional, named entries.
 #' @importFrom yaml write_yaml
 #' @author Jan Philipp Dietrich, David Klein
 #' @seealso \code{\link{setConfig}}, \code{\link{readSource}}
@@ -53,23 +74,24 @@ downloadSource <- function(type,subtype=NULL,overwrite=FALSE) {
   meta <- eval(parse(text=functionname))
 
   # define mandatory elements of meta data and check if they exist
-  mandatory <- c("url","authors","title","license")
+  mandatory <- c("url","author","title","license")
   if(!all(mandatory %in% names(meta))) {vcat(0, paste0("Missing entries in the meta data of function '",functionname[1],"': ",mandatory[!mandatory %in% names(meta)]))}
 
   # define reserved elements of meta data and check if they already exist
-  reserved <- c("type","subtype","origin","date_downloaded","source_quality")
+  reserved <- c("call","accessibility")
   if(any(reserved %in% names(meta))) {vcat(0, paste0("The following entries in the meta data of the function '",functionname[1],"' are reserved and will be overwritten: ",reserved[reserved %in% names(meta)]))}
 
   # set reserved meta data elements
-  meta$type    <- type
-  meta$subtype <- ifelse(is.null(subtype), "none",subtype)
-  meta$origin  <- paste0(gsub("\\s{2,}"," ",paste(deparse(match.call()),collapse=""))," -> ",functionname," (madrat ",packageDescription("madrat")$Version," | ",attr(functionname,"pkgcomment"),")")
-  meta$date_downloaded <- date()
-  meta$source_quality <- ifelse(!is.null(meta$doi),"gold","silver")
+  meta$call <- list(origin  = paste0(gsub("\\s{2,}"," ",paste(deparse(match.call()),collapse="")),
+                                     " -> ",functionname," (madrat ",packageDescription("madrat")$Version,
+                                     " | ",attr(functionname,"pkgcomment"),")"),
+                    type    = type,
+                    subtype = ifelse(is.null(subtype), "none",subtype),
+                    time    = format(Sys.time(),"%F %T %Z"))
+  meta$accessibility <- ifelse(!is.null(meta$doi),"gold","silver")
 
   # reorder meta entries
-  preferred_order <- c("title","authors","doi","url","license","version","date_released","date_downloaded","origin",
-                       "type","subtype", "source_quality","source")
+  preferred_order <- c("title","author","doi","url","accessibility","license","version","release_date","call","reference")
   order <- c(intersect(preferred_order,names(meta)),setdiff(names(meta),preferred_order))
 
   write_yaml(meta[order],"DOWNLOAD.yml")

R/downloadTau.R

@@ -16,13 +16,13 @@ downloadTau <- function(subtype="paper") {
   return(list(url           = meta$url,
               doi           = meta$doi,
               title         = meta$title,
-              authors       = person("Jan Philipp","Dietrich", email="dietrich@pik-potsdam.de", comment=c(ORCID="0000-0002-4309-6431")),
+              author        = person("Jan Philipp","Dietrich", email="dietrich@pik-potsdam.de", comment="https://orcid.org/0000-0002-4309-6431"),
               version       = "1.0",
-              date_released = "2012-05-10",
-              license  = "Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0)",
-              source   = bibentry("Article",
+              release_date  = "2012-05-10",
+              license       = "Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0)",
+              reference     = bibentry("Article",
                                   title="Measuring agricultural land-use intensity - A global analysis using a model-assisted approach",
-                                  author=c(person("Jan Philipp","Dietrich", email="dietrich@pik-potsdam.de", comment=c(ORCID="0000-0002-4309-6431")),
+                                  author=c(person("Jan Philipp","Dietrich", email="dietrich@pik-potsdam.de", comment="https://orcid.org/0000-0002-4309-6431"),
                                            person("Christoph","Schmitz"),
                                            person("Christoph","Mueller"),
                                            person("Marianela","Fader"),