document and clean up for release

.Rbuildignore

@@ -5,3 +5,7 @@
 ^.*CITATION.cff$
 ^.*\.Rproj$
 ^\.Rproj\.user$
+^.lintr$
+^tests/.lintr$
+^codecov\.yml$
+^\.github$

.buildlibrary

@@ -1,7 +1,10 @@
-ValidationKey: '39524'
+ValidationKey: '198020'
 AutocreateReadme: yes
 AcceptedWarnings:
 - 'Warning: package ''.*'' was built under R version'
 - 'Warning: namespace ''.*'' is not available and has been replaced'
-AcceptedNotes: ~
-allowLinterWarnings: no
+AcceptedNotes:
+- no visible binding for global variable
+- 'Found the following hidden files and directories:'
+allowLinterWarnings: yes
+enforceVersionUpdate: no

.github/workflows/check.yaml

@@ -49,6 +49,11 @@ jobs:
         shell: Rscript {0}
         run: lucode2:::validkey(stopIfInvalid = TRUE)
 
+      - name: Verify that lucode2::buildLibrary was successful
+        if: github.event_name == 'pull_request'
+        shell: Rscript {0}
+        run: lucode2:::isVersionUpdated()
+
       - name: Checks
         shell: Rscript {0}
         run: |

.gitignore

@@ -3,3 +3,4 @@
 *.RData
 *.Ruserdata
 *.html
+.Rproj.user

.lintr

@@ -0,0 +1,2 @@
+linters: lucode2::lintrRules()
+encoding: "UTF-8"

.pre-commit-config.yaml

@@ -15,7 +15,7 @@ repos:
     -   id: mixed-line-ending
 
 -   repo: https://github.com/lorenzwalthert/precommit
-    rev: v0.3.2.9025
+    rev: v0.4.0
     hooks:
     -   id: parsable-R
     -   id: deps-in-desc

CITATION.cff

@@ -2,14 +2,16 @@ cff-version: 1.2.0
 message: If you use this software, please cite it using the metadata from this file.
 type: software
 title: 'piamValidation: Validation Tools for PIK-PIAM'
-version: 0.0.2
-date-released: '2024-02-09'
+version: 0.1.0
+date-released: '2024-03-20'
 abstract: The piamValidation package provides validation tools for the Potsdam Integrated
   Assessment Modelling environment.
 authors:
 - family-names: Weigmann
   given-names: Pascal
   email: [email protected]
+- family-names: Richters
+  given-names: Oliver
 license: LGPL-3.0
 repository-code: https://github.com/pik-piam/piamValidation
 

DESCRIPTION

@@ -1,10 +1,11 @@
 Type: Package
 Package: piamValidation
 Title: Validation Tools for PIK-PIAM
-Version: 0.0.2
-Date: 2024-02-09
+Version: 0.1.0
+Date: 2024-03-20
 Authors@R:
-    person("Pascal", "Weigmann", , "[email protected]", role = c("aut", "cre"))
+    c(person("Pascal", "Weigmann",, "[email protected]", role = c("aut", "cre")),
+      person("Oliver", "Richters",, role = "aut"))
 Description: The piamValidation package provides validation tools for the Potsdam Integrated Assessment Modelling environment.
 License: LGPL-3
 URL: https://github.com/pik-piam/piamValidation
@@ -15,9 +16,11 @@ Imports:
     plotly,
     quitte (>= 0.3123.0),
     readxl,
+    tibble,
     tidyr
 Suggests:
-    testthat
+    testthat,
+    remind2
 Encoding: UTF-8
 RoxygenNote: 7.3.1
 Depends: 

NAMESPACE

@@ -14,4 +14,4 @@ importFrom(ggthemes,theme_tufte)
 importFrom(plotly,ggplotly)
 importFrom(readxl,excel_sheets)
 importFrom(readxl,read_excel)
-importFrom(tibble,as_tibble)
+importFrom(utils,read.csv2)

R/appendTooltips.R

@@ -2,12 +2,13 @@
 appendTooltips <- function(df) {
 
   df$text <- NA
+  region <- period <- NULL
 
   # historic - relative
   df[df$category == "historic" & df$metric == "relative", ] <-
     df[df$category == "historic" & df$metric == "relative", ] %>%
-    mutate(text = paste0(region, "\n",
-                         period, "\n",
+    mutate(text = paste0(.data$region, "\n",
+                         .data$period, "\n",
                          "Value: ", round(value, 2), "\n",
                          "Ref_Value: ", round(ref_value, 2), "\n",
                          "Ref_Source: ", ref_model, "\n",

R/combineData.R

@@ -2,7 +2,7 @@
 
 # for one row of cfg: filter and merge relevant scenario data with cfg
 # results in one df that contains scenario data, reference data and thresholds
-combineData <- function(data, cfg_row, ref_data = NULL) {
+combineData <- function(data, cfgRow, refData = NULL) {
 
   # shorten as it will be used a lot
   c <- cfg_row

R/importFunctions.R

@@ -1,6 +1,6 @@
-#' @importFrom dplyr filter select mutate summarise group_by %>%
-#' @importFrom tibble as_tibble
+#' @importFrom dplyr filter select mutate %>%
 #' @importFrom readxl read_excel excel_sheets
+#' @importFrom utils read.csv2
 
 # scenarioPath: one or multiple paths to .mif or .csv file(s) containing
 #               scenario data in IAM format
@@ -41,7 +41,8 @@ getConfig <- function(configName) {
       )
     cfg <- filter(cfg, ! grepl("^#", cfg[[1]]))
   } else {
-    cfg <- as_tibble(read.csv2(path, na.strings = "", comment.char = "#"))
+    cfg <- tibble::as_tibble(
+      read.csv2(path, na.strings = "", comment.char = "#"))
   }
   message("loading config file: ", configName, "\n")
   return(cfg)

R/outputFunctions.R

@@ -1,18 +1,20 @@
-#' @importFrom dplyr filter select mutate summarise group_by %>%
-# yellowFail: if set to TRUE a yellow check result of a critical variable will
-#             lead to the scenario not passing as validated
+#' returns information on whether scenarios passed critical validation checks
+#'
+#' @param data data.frame as returned from ``validateScenarios()``
+#' @param yellowFail if set to TRUE a yellow check result of a critical
+#'        variable will lead to the scenario not passing as validated
+#'
+#' @importFrom dplyr %>%
 #' @export
 validationPass <- function(data, yellowFail = FALSE) {
 
   fail_color <- ifelse(yellowFail, c("red", "yellow"), "red")
 
   # see if any critical variables have failed per scenario and model
   pass <- data %>%
-    filter(check %in% fail_color, critical == "yes") %>%
-    group_by(model, scenario) %>%
-    summarize(pass = n() == 0,
-              n_fail = n()
-              )
+    dplyr::filter(check %in% fail_color, critical == "yes") %>%
+    dplyr::group_by(model, scenario) %>%
+    dplyr::summarize(pass = dplyr::n() == 0, n_fail = dplyr::n())
 
   return(pass)
 }

R/piamValidation-package.R

@@ -0,0 +1,7 @@
+#' Validation Tools for PIK-PIAM
+#'
+#' The piamValidation package provides validation tools for the Potsdam Integrated Assessment Modelling environment.
+#'
+#' @name piamValidation-package
+#' @aliases piamValidation-package piamValidation
+"_PACKAGE"

R/validateScenarios.R

@@ -1,6 +1,11 @@
-#' @importFrom dplyr filter select mutate summarise group_by %>%
-
-# performs the validation checks from a config on a scenario dataset
+#' performs the validation checks from a config on a scenario dataset
+#'
+#' @param scenarioPath one or multiple path(s) to scenario data in .mif or .csv
+#'        format
+#' @param configName select config from inst/config
+#' @param referencePath in case of historic comparison, choose path to ref data
+#'
+#' @importFrom dplyr filter select mutate group_by %>%
 #' @export
 validateScenarios <- function(scenarioPath, configName, referencePath = NULL) {
 
@@ -20,7 +25,7 @@ validateScenarios <- function(scenarioPath, configName, referencePath = NULL) {
   for (i in 1:nrow(cfg)) {
     # TODO: hist should only be needed if category "historical" is in config
     #       validation generally should work without hist data
-    df_row <- combineData(data, cfg[i, ], ref_data = hist)
+    df_row <- combineData(data, cfg[i, ], refData = hist)
     df <- rbind(df, df_row)
     cat(paste0("Combined config row ", i, " of ", nrow(cfg), "\n"))
   }

R/validationHeatmap.R

@@ -1,28 +1,38 @@
+#' takes the output of "validateScenarios()" and plots heatmaps per variable
+#'
+#' @param data data.frame as returned by ``validateScenarios()``
+#' @param var variable to be plotted
+#' @param cat choose category from "historical" or "scenario"
+#' @param met choose metric from "relative", "difference", "absolute" or
+#'        "growthrate"
+#' @param interactive return plots as interactive plotly plots by default
+#' @param compareModels if TRUE, plots compare models instead of scenarios
+#'
 #' @importFrom dplyr filter select mutate %>%
 #' @import ggplot2
 #' @importFrom ggthemes theme_tufte
 #' @importFrom plotly ggplotly
 #' @export
 
-# takes the output of "validateScenarios()" and plots heatmaps per variable
-validationHeatmap <- function(df, var, cat, met, interactive = T, compareModels = T) {
+validationHeatmap <- function(data, var, cat, met,
+                              interactive = T, compareModels = T) {
 
   # possible extension: when giving multiple vars, plot as facets in same row
 
   # prepare data slice
-  d <- df %>%
+  d <- data %>%
     filter(variable == var,
            category == cat,
            metric == met)
 
   # warn if no data is found for combination of var, cat and met
   if (nrow(d) == 0) {
-    df$cm <- paste(category, metric, sep = "-")
+    data$cm <- paste(category, metric, sep = "-")
     warning(
       paste0(
         "No data found for variable in this category and metric.\n
         variable ", var ," is available for the following category-metric
-        combinations: ", unique(df[df$variable == var, "cm"])
+        combinations: ", unique(data[data$variable == var, "cm"])
         )
       )
   }

README.md

@@ -1,6 +1,6 @@
 # Validation Tools for PIK-PIAM
 
-R package **piamValidation**, version **0.0.2**
+R package **piamValidation**, version **0.1.0**
 
 [![CRAN status](https://www.r-pkg.org/badges/version/piamValidation)](https://cran.r-project.org/package=piamValidation)  [![R build status](https://github.com/pik-piam/piamValidation/workflows/check/badge.svg)](https://github.com/pik-piam/piamValidation/actions) [![codecov](https://codecov.io/gh/pik-piam/piamValidation/branch/master/graph/badge.svg)](https://app.codecov.io/gh/pik-piam/piamValidation) 
 
@@ -9,13 +9,6 @@ R package **piamValidation**, version **0.0.2**
 The piamValidation package provides validation tools for the Potsdam Integrated Assessment Modelling environment.
 
 
-## How to use
-
-The following categories/metrics require allow the following columns in the cfg:
-
-
-
-
 ## Installation
 
 For installation of the most recent package version an additional repository has to be added in R:
@@ -45,16 +38,16 @@ In case of questions / problems please contact Pascal Weigmann <pascal.weigmann@
 
 To cite package **piamValidation** in publications use:
 
-Weigmann P (2024). _piamValidation: Validation Tools for PIK-PIAM_. R package version 0.0.2, <URL: https://github.com/pik-piam/piamValidation>.
+Weigmann P, Richters O (2024). _piamValidation: Validation Tools for PIK-PIAM_. R package version 0.1.0, <URL: https://github.com/pik-piam/piamValidation>.
 
 A BibTeX entry for LaTeX users is
 
  ```latex
 @Manual{,
   title = {piamValidation: Validation Tools for PIK-PIAM},
-  author = {Pascal Weigmann},
+  author = {Pascal Weigmann and Oliver Richters},
   year = {2024},
-  note = {R package version 0.0.2},
+  note = {R package version 0.1.0},
   url = {https://github.com/pik-piam/piamValidation},
 }
 ```

codecov.yml

@@ -0,0 +1,18 @@
+comment: true
+github_checks:
+  annotations: false
+coverage:
+  precision: 2
+  round: down
+  range: "0...95"
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 1%
+        informational: true
+    patch:
+      default:
+        target: auto
+        threshold: 1%
+        informational: true