added toolExpectTrue, toolExpectLessDiff and toolStatusMessage

.Rbuildignore

@@ -8,3 +8,5 @@
 ^workflow$
 ^.lintr$
 ^tests/.lintr$
+^Makefile$
+^.*CITATION.cff$

.buildlibrary

@@ -1,4 +1,4 @@
-ValidationKey: '577200'
+ValidationKey: '789480'
 AutocreateReadme: yes
 AcceptedWarnings:
 - 'Warning: package ''.*'' was built under R version'

.github/workflows/check.yaml

@@ -0,0 +1,64 @@
+name: check
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: r-lib/actions/setup-pandoc@v2
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+          extra-repositories: "https://rse.pik-potsdam.de/r/packages"
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: |
+            gamstransfer=?ignore
+            any::lucode2
+            any::covr
+            any::madrat
+            any::magclass
+            any::citation
+            any::gms
+            any::goxygen
+            any::GDPuc
+          # piam packages also available on CRAN (madrat, magclass, citation,
+          # gms, goxygen, GDPuc) will usually have an outdated binary version
+          # available; by using extra-packages we get the newest version
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.9
+
+      - name: Install python dependencies if applicable
+        run: |
+          [ -f requirements.txt ] && python -m pip install --upgrade pip wheel || true
+          [ -f requirements.txt ] && pip install -r requirements.txt || true
+
+      - name: Verify validation key
+        shell: Rscript {0}
+        run: lucode2:::validkey(stopIfInvalid = TRUE)
+
+      - name: Checks
+        shell: Rscript {0}
+        run: |
+          options(crayon.enabled = TRUE)
+          lucode2::check(runLinter = FALSE)
+
+      - name: Test coverage
+        shell: Rscript {0}
+        run: |
+          nonDummyTests <- setdiff(list.files("./tests/testthat/"), c("test-dummy.R", "_snaps"))
+          if(length(nonDummyTests) > 0) covr::codecov(quiet = FALSE)
+        env:
+          NOT_CRAN: "true"

.pre-commit-config.yaml

@@ -3,7 +3,7 @@
 exclude: '^tests/testthat/_snaps/.*$'
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.3.0
+    rev: v4.5.0
     hooks:
     -   id: check-case-conflict
     -   id: check-json
@@ -15,7 +15,7 @@ repos:
     -   id: mixed-line-ending
 
 -   repo: https://github.com/lorenzwalthert/precommit
-    rev: v0.3.2.9001
+    rev: v0.3.2.9025
     hooks:
     -   id: parsable-R
     -   id: deps-in-desc

CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+message: If you use this software, please cite it using the metadata from this file.
+type: software
+title: 'mstools: Tool functions that can be used by several madrat-dependent or magpie4
+  output functions'
+version: 0.4.0
+date-released: '2024-01-15'
+abstract: Tool functions that can be used by several madrat-dependent or magpie4 output
+  functions.
+authors:
+- family-names: Bodirsky
+  given-names: Benjamin Leon
+  email: [email protected]
+- family-names: Dietrich
+  given-names: Jan Philipp
+  email: [email protected]
+license: LGPL-3.0
+repository-code: https://github.com/pik-piam/magpie4
+doi: 10.5281/zenodo.1158582
+

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: mstools
 Type: Package
 Title: Tool functions that can be used by several madrat-dependent or magpie4 output functions
-Version: 0.3.0
-Date: 2022-09-05
+Version: 0.4.0
+Date: 2024-01-15
 Authors@R: c(person("Benjamin Leon", "Bodirsky", email = "[email protected]", role = c("aut","cre")),
 		          person("Jan Philipp", "Dietrich", email = "[email protected]", role = "aut"))
 Description: Tool functions that can be used by several madrat-dependent or magpie4 output functions.
@@ -14,7 +14,7 @@ URL: https://github.com/pik-piam/magpie4, https://doi.org/10.5281/zenodo.1158582
 BugReports: https://github.com/pik-piam/magpie4/issues
 Encoding: UTF-8
 License: LGPL-3 | file LICENSE
-RoxygenNote: 7.2.1
+RoxygenNote: 7.2.3
 Suggests: 
     testthat,
     covr

Makefile

@@ -0,0 +1,46 @@
+.PHONY: help build check test lint lint-all format format-all install docs
+.DEFAULT_GOAL = help
+
+# extracts the help text and formats it nicely
+HELP_PARSING = 'm <- readLines("Makefile");\
+				m <- grep("\#\#", m, value=TRUE);\
+				command <- sub("^([^ ]*) *\#\#(.*)", "\\1", m);\
+				help <- sub("^([^ ]*) *\#\#(.*)", "\\2", m);\
+				cat(sprintf("%-8s%s", command, help), sep="\n")'
+
+help:           ## Show this help.
+	@Rscript -e $(HELP_PARSING)
+
+build:          ## Build the package using lucode2::buildLibrary(). You can pass the
+                ## updateType with 'make build u=3'
+	Rscript -e 'lucode2::buildLibrary(updateType = "$(u)")'
+
+check:          ## Build documentation and vignettes, run testthat tests,
+                ## and check if code etiquette is followed using lucode2::check().
+	Rscript -e 'lucode2::check()'
+
+test:           ## Run testthat tests
+	Rscript -e 'devtools::test(show_report = TRUE)'
+
+lint:           ## Check if code etiquette is followed using lucode2::lint().
+                ## Only checks files you changed.
+	Rscript -e 'lucode2::lint()'
+
+lint-all:       ## Check if code etiquette is followed using lucode2::lint().
+                ## Checks all files.
+	Rscript -e 'lucode2::lint(".")'
+
+format:         ## Apply auto-formatting to changed files and lint afterwards.
+	Rscript -e 'lucode2::autoFormat()'
+
+format-all:     ## Apply auto-formatting to all files and lint afterwards.
+	Rscript -e 'lucode2::autoFormat(files=list.files("./R", full.names = TRUE, pattern = "\\.R"))'
+
+install:        ## Install the package locally via devtools::install() after
+                ## generating NAMESPACE and docs (see docs target).
+	Rscript -e 'roxygen2::roxygenize(); devtools::install(upgrade = "never")'
+
+docs:           ## Generate the package documentation (man/*.Rd files) and
+                ## NAMESPACE via roxygen2::roxygenize(), view the generated
+                ## documentation with `?package::function`.
+	Rscript -e 'roxygen2::roxygenize()'

NAMESPACE

@@ -1,8 +1,11 @@
 # Generated by roxygen2: do not edit by hand
 
+export(toolExpectLessDiff)
+export(toolExpectTrue)
 export(toolFertilizerDistribution)
 export(toolHoldConstant)
 export(toolIsocode2Country)
+export(toolStatusMessage)
 import(madrat)
 import(magclass)
 importFrom(madrat,toolAggregate)

R/toolExpectLessDiff.R

@@ -0,0 +1,28 @@
+#' toolExpectLessDiff
+#'
+#' tool function for status reporting. It performs a difference check between
+#' two objects and returns either a message via \code{toolStatusMessage}, that
+#' the test was successful or that it failed.
+#'
+#' @param x object 1
+#' @param y object 2 which has the same format as object 1
+#' @param maxdiff allowed maximum difference per element between x and y.
+#' @param description a description of the check
+#' @param level as the test result will be linked to a function call, the function
+#' needs to know to which call it should be linked. by default (\code{level = 0}) the parent
+#' function call is being used. Increasing the number by one will let the function go
+#' up by one in the call stack, \code{level = -1} will use \code{toolExpectTrue} itself as
+#' function call.
+#' @author Jan Philipp Dietrich
+#' @seealso \code{\link{getMadratMessage}}, \code{\link{toolExpectTrue}}, \code{\link{toolStatusMessage}}
+#' @examples
+#' toolExpectLessDiff(1:3, 2:4, 10, "data is sufficiently close", level = -1)
+#' getMadratMessage("status")
+#' @export
+
+toolExpectLessDiff <- function(x, y, maxdiff, description, level = 0) {
+  value <- max(abs(x - y))
+  description <- paste0(description, " (maxdiff = ", format(value, digits = 2),
+                        ", threshold = ", format(maxdiff, digits = 2), ")")
+  toolExpectTrue(value <= maxdiff, description, level = level + 1)
+}

R/toolExpectTrue.R

@@ -0,0 +1,24 @@
+#' toolExpectTrue
+#'
+#' tool function for status reporting. It performs a logical check
+#' and returns either a message via \code{toolStatusMessage}, that
+#' the test was successful or that it failed.
+#'
+#' @param check logical check to be run (has to be either TRUE or FALSE)
+#' @param description a description of the check
+#' @param level as the test result will be linked to a function call, the function
+#' needs to know to which call it should be linked. by default (\code{level = 0}) the parent
+#' function call is being used. Increasing the number by one will let the function go
+#' up by one in the call stack, \code{level = -1} will use \code{toolExpectTrue} itself as
+#' function call.
+#' @author Jan Philipp Dietrich
+#' @seealso \code{\link{getMadratMessage}}, \code{\link{toolExpectLessDiff}}, \code{\link{toolStatusMessage}}
+#' @examples
+#' toolExpectTrue(is.numeric(1), "data is numeric", level = -1)
+#' getMadratMessage("status")
+#' @export
+toolExpectTrue <- function(check, description, level = 0) {
+  status <- ifelse(isTRUE(check), "ok", "warn")
+  if (!isTRUE(check)) description <- paste0("Check failed: ", description)
+  toolStatusMessage(status, description, level = 1 + level)
+}

R/toolStatusMessage.R

@@ -0,0 +1,28 @@
+#' toolStatusMessage
+#'
+#' tool to trigger status messages describing the data quality at different stages
+#' of processing. Messages are directly written to the log at execution but also
+#' collected to be finally returned as data report.
+#'
+#' @param status status indicator of the messages. Currently either "ok" (check
+#' succesful / quality ok), or "warn" (check unsuccessful / undesired result).
+#' @param message message to be triggered.
+#' @param level as the test result will be linked to a function call, the function
+#' needs to know to which call it should be linked. by default (\code{level = 0}) the parent
+#' function call is being used. Increasing the number by one will let the function go
+#' up by one in the call stack, \code{level = -1} will use \code{toolExpectTrue} itself as
+#' function call.
+#' @author Jan Philipp Dietrich
+#' @seealso \code{\link{getMadratMessage}}, \code{\link{toolExpectLessDiff}}, \code{\link{toolStatusMessage}}
+#' @examples
+#' toolStatusMessage("ok", "everything is ok", level = -1)
+#' toolStatusMessage("warn", "this is not ok", level = -1)
+#' getMadratMessage("status")
+#' @export
+
+toolStatusMessage <- function(status, message, level = 0) {
+  symbol <- toolSubtypeSelect(status, c(ok = "\u2713", warn = "!"))
+  message <- paste0("[", symbol, "] ", message)
+  vcat(1, message, show_prefix = FALSE)
+  putMadratMessage("status", message, fname = -2 - level, add = TRUE)
+}