have matchDim(x, ref = NULL) return x

.buildlibrary

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

CITATION.cff

@@ -2,8 +2,8 @@ cff-version: 1.2.0
 message: If you use this software, please cite it using the metadata from this file.
 type: software
 title: 'magclass: Data Class and Tools for Handling Spatial-Temporal Data'
-version: 6.16.1
-date-released: '2024-06-28'
+version: 6.17.0
+date-released: '2024-07-02'
 abstract: Data class for increased interoperability working with spatial-temporal
   data together with corresponding functions and methods (conversions, basic calculations
   and basic data manipulation). The class distinguishes between spatial, temporal

DESCRIPTION

@@ -1,8 +1,8 @@
 Type: Package
 Package: magclass
 Title: Data Class and Tools for Handling Spatial-Temporal Data
-Version: 6.16.1
-Date: 2024-06-28
+Version: 6.17.0
+Date: 2024-07-02
 Authors@R: c(
     person("Jan Philipp", "Dietrich", , "dietrich@pik-potsdam.de", 
     comment = c(affiliation = "Potsdam Institute for Climate Impact Research", ORCID = "0000-0002-4309-6431"), role = c("aut", "cre")),
@@ -63,5 +63,5 @@ VignetteBuilder:
     knitr
 Encoding: UTF-8
 LazyData: true
-RoxygenNote: 7.3.1
+RoxygenNote: 7.3.2
 Config/Keywords: tool

R/matchDim.R

@@ -1,32 +1,51 @@
-#' match object dimensions of a magclass object to the dimensions of a reference object
+#' Match dimensions of a magpie object to those of a reference object
 #'
-#' A helper that restricts and expands a magclass object x to the size of a magclass object ref.
-#' Dimension names not present in x are added and set to the value provided by 'fill'.
-#' Dimension names not present in ref are cropped.
+#' A helper that restricts and expands a magpie object `x` to the size of a
+#' magpie object `ref`.  Dimension names not present in `x` are added and set to
+#' the value provided by `fill`.  Dimension names not present in `ref` are
+#' cropped.
+#'
+#' @md
+#' @param x A `magpie` object to be modified.
+#' @param ref A `magpie` object used as a reference for the modification.
+#'   Returns `x` if `ref` is `NULL`.
+#' @param fill Value to be set in new dimensions.
+#' @param dim Subset of dimensions for which the matching should be done.  Can
+#'   be either a number between 1 and 3 or a vector of these.  Defaults to all
+#'   dimensions (i.e. `1:3`).
+#'
+#' @return The modified `magpie` object.
 #'
-#' @param x a magclass object to be modified
-#' @param ref a magclass object used as a reference for the modification
-#' @param fill value to be set in new dimensions
-#' @param dim subset of dimensions for which the matching should be done.
-#' Can be either a number between 1 and 3 or a vector of these.
-#' Set to NULL (default) for matching all dimensions.
 #' @author Falk Benke
 #'
 #' @export
-matchDim <- function(x, ref, dim = NULL, fill = NA) {
+matchDim <- function(x, ref, dim = 1:3, fill = NA) {
+
+  if (is.null(ref)) {
+    return(x)
+  }
+
+  if (!is.magpie(x)) {
+    stop("`x` must be a magpie object, not `", paste(class(x), collapse = ", "),
+         "`")
+  }
+
+  if (!is.magpie(ref)) {
+    stop("`ref` must be a magpie object or NULL, not `",
+         paste(class(ref), collapse = ", "), "`")
+  }
 
-  if (is.null(dim)) {
-    dim <- c(1, 2, 3)
-  } else if (length(setdiff(dim, c(1, 2, 3))) > 0) {
-    stop("argument 'dim' can only contain numbers between 1 and 3")
+  if (!is.numeric(dim) || any(!dim %in% 1:3)) {
+    stop("`dim` must be a numeric vector containing only numbers between 1 ",
+         "and 3, not `", utils::capture.output(dput(dim)), "`")
   }
 
   for (i in dim) {
     if (ndim(x, dim = i) != ndim(ref, dim = i)) {
       stop(
         paste0(
-          "Unsupported case: magclass objects x and ref have different number of ",
-          "subdimensions in dimension ", i
+          "Unsupported case: magclass objects x and ref have different number ",
+          "of subdimensions in dimension ", i
         )
       )
     }

README.md

@@ -1,6 +1,6 @@
 # Data Class and Tools for Handling Spatial-Temporal Data
 
-R package **magclass**, version **6.16.1**
+R package **magclass**, version **6.17.0**
 
 [![CRAN status](https://www.r-pkg.org/badges/version/magclass)](https://cran.r-project.org/package=magclass) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1158580.svg)](https://doi.org/10.5281/zenodo.1158580) [![R build status](https://github.com/pik-piam/magclass/workflows/check/badge.svg)](https://github.com/pik-piam/magclass/actions) [![codecov](https://codecov.io/gh/pik-piam/magclass/branch/master/graph/badge.svg)](https://app.codecov.io/gh/pik-piam/magclass) [![r-universe](https://pik-piam.r-universe.dev/badges/magclass)](https://pik-piam.r-universe.dev/builds)
 
@@ -56,7 +56,7 @@ In case of questions / problems please contact Jan Philipp Dietrich <dietrich@pi
 
 To cite package **magclass** in publications use:
 
-Dietrich J, Bodirsky B, Bonsch M, Humpenoeder F, Bi S, Karstens K, Leip D, Sauer P (2024). _magclass: Data Class and Tools for Handling Spatial-Temporal Data_. doi:10.5281/zenodo.1158580 <https://doi.org/10.5281/zenodo.1158580>, R package version 6.16.1, <https://github.com/pik-piam/magclass>.
+Dietrich J, Bodirsky B, Bonsch M, Humpenoeder F, Bi S, Karstens K, Leip D, Sauer P (2024). _magclass: Data Class and Tools for Handling Spatial-Temporal Data_. doi:10.5281/zenodo.1158580 <https://doi.org/10.5281/zenodo.1158580>, R package version 6.17.0, <https://github.com/pik-piam/magclass>.
 
 A BibTeX entry for LaTeX users is
 
@@ -65,8 +65,8 @@ A BibTeX entry for LaTeX users is
   title = {magclass: Data Class and Tools for Handling Spatial-Temporal Data},
   author = {Jan Philipp Dietrich and Benjamin Leon Bodirsky and Markus Bonsch and Florian Humpenoeder and Stephen Bi and Kristine Karstens and Debbora Leip and Pascal Sauer},
   year = {2024},
-  note = {R package version 6.16.1},
-  doi = {10.5281/zenodo.1158580},
+  note = {R package version 6.17.0},
   url = {https://github.com/pik-piam/magclass},
+  doi = {10.5281/zenodo.1158580},
 }
 ```

tests/testthat/test-matchDim.R

@@ -14,31 +14,40 @@ test_that("matchDim works", {
     sets = c("region", "t", "name")
   )
 
-  # match all dimensions
+  # reject non-magpie objects ----
+  expect_error(matchDim(data.frame(), mp2),
+               regexp = "must be a magpie object, not")
+  expect_error(matchDim(mp, data.frame()),
+               regexp = "must be a magpie object or NULL, not")
+
+  # ignore NULL reference ----
+  expect_identical(matchDim(mp, NULL), mp)
+
+  # match all dimensions ----
   x <- matchDim(mp, mp2)
   expect_equal(getItems(x, dim = 1), c("BBB", "CCC", "DDD"))
   expect_equal(getItems(x, dim = 2), c("y2000", "y2010", "y2020"))
   expect_equal(getItems(x, dim = 3), c("foo", "bar", "qux"))
 
-  # match only spatial
+  # match only spatial ----
   x <- matchDim(mp, mp2, dim = 1)
   expect_equal(getItems(x, dim = 1), c("BBB", "CCC", "DDD"))
   expect_equal(getItems(x, dim = 2), c("y2000", "y2005", "y2010"))
   expect_equal(getItems(x, dim = 3), c("foo", "bar", "baz"))
 
-  # match only temporal
+  # match only temporal ----
   x <- matchDim(mp, mp2, dim = 2)
   expect_equal(getItems(x, dim = 1), c("AAA", "BBB", "CCC"))
   expect_equal(getItems(x, dim = 2), c("y2000", "y2010", "y2020"))
   expect_equal(getItems(x, dim = 3), c("foo", "bar", "baz"))
 
-  # match only third
+  # match only third ----
   x <- matchDim(mp, mp2, dim = 3)
   expect_equal(getItems(x, dim = 1), c("AAA", "BBB", "CCC"))
   expect_equal(getItems(x, dim = 2), c("y2000", "y2005", "y2010"))
   expect_equal(getItems(x, dim = 3), c("foo", "bar", "qux"))
 
-  # reject objects with varying subdimensions
+  # reject objects with varying subdimensions ----
   mp3 <- add_dimension(mp2, dim = 1.2, add = "subregion", "yyy")
   expect_error(matchDim(mp, mp3, dim = 1),
                regexp = "magclass objects x and ref have different number of subdimensions in dimension 1")