From b3d8fe262ce59deb759f4d479a0fd94c03a1044d Mon Sep 17 00:00:00 2001 From: Jan Philipp Dietrich Date: Mon, 23 Nov 2020 12:59:27 +0100 Subject: [PATCH] updated metadata entries and documentation --- .buildlibrary | 2 +- DESCRIPTION | 2 +- R/calcTauTotal.R | 3 +-- R/downloadSource.R | 40 +++++++++++++++++++++++++++++++--------- R/downloadTau.R | 10 +++++----- 5 files changed, 39 insertions(+), 18 deletions(-) diff --git a/.buildlibrary b/.buildlibrary index 56cace5d..ed48ac89 100644 --- a/.buildlibrary +++ b/.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' diff --git a/DESCRIPTION b/DESCRIPTION index f6db9de0..51f9b271 100644 --- a/DESCRIPTION +++ b/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"), diff --git a/R/calcTauTotal.R b/R/calcTauTotal.R index 3d7f75ba..247a0e2f 100644 --- a/R/calcTauTotal.R +++ b/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"), diff --git a/R/downloadSource.R b/R/downloadSource.R index 1479c196..4c168e40 100644 --- a/R/downloadSource.R +++ b/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") diff --git a/R/downloadTau.R b/R/downloadTau.R index e33ddd7e..f1ae3074 100644 --- a/R/downloadTau.R +++ b/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"),