add function matchDim

.buildlibrary

@@ -1,4 +1,4 @@
-ValidationKey: '122405360'
+ValidationKey: '122616222'
 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.0
-date-released: '2024-05-28'
+version: 6.16.1
+date-released: '2024-06-28'
 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
@@ -79,7 +79,7 @@ authors:
   given-names: Oliver
   affiliation: Potsdam Institute for Climate Impact Research
 license: LGPL-3.0
-keywords: 
+keywords:
 - tool
 repository-code: https://github.com/pik-piam/magclass
 doi: 10.5281/zenodo.1158580

DESCRIPTION

@@ -1,8 +1,8 @@
 Type: Package
 Package: magclass
 Title: Data Class and Tools for Handling Spatial-Temporal Data
-Version: 6.16.0
-Date: 2024-05-28
+Version: 6.16.1
+Date: 2024-06-28
 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")),

NAMESPACE

@@ -58,6 +58,7 @@ export(lowpass)
 export(magpie_expand)
 export(magpiesort)
 export(magpply)
+export(matchDim)
 export(maxample)
 export(mbind)
 export(mcalc)

R/matchDim.R

@@ -0,0 +1,57 @@
+#' match object dimensions of a magclass object to the dimensions 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.
+#'
+#' @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) {
+
+  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")
+  }
+
+  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
+        )
+      )
+    }
+  }
+
+  # extend new object to the union of both objects
+  d1 <- if (1 %in% dim) union(getItems(x, dim = 1), getItems(ref, dim = 1)) else getItems(x, dim = 1)
+  d2 <- if (2 %in% dim) union(getItems(x, dim = 2), getItems(ref, dim = 2)) else getItems(x, dim = 2)
+  d3 <- if (3 %in% dim) union(getItems(x, dim = 3), getItems(ref, dim = 3)) else getItems(x, dim = 3)
+
+  r <- new.magpie(
+    cells_and_regions = d1,
+    years = d2,
+    names = d3,
+    fill = fill,
+    sets = names(dimnames(ref))
+  )
+
+  # copy over values from x
+  r[getItems(x, dim = 1), getItems(x, dim = 2), getItems(x, dim = 3)] <- x
+
+  # restrict object to dimensions of ref
+  if (1 %in% dim) r <- r[getItems(ref, dim = 1), , ]
+  if (2 %in% dim) r <- r[, getItems(ref, dim = 2), ]
+  if (3 %in% dim) r <- r[, , getItems(ref, dim = 3)]
+
+  return(r)
+}

README.md

@@ -1,6 +1,6 @@
 # Data Class and Tools for Handling Spatial-Temporal Data
 
-R package **magclass**, version **6.16.0**
+R package **magclass**, version **6.16.1**
 
 [![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.0, <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.16.1, <https://github.com/pik-piam/magclass>.
 
 A BibTeX entry for LaTeX users is
 
@@ -65,7 +65,7 @@ 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.0},
+  note = {R package version 6.16.1},
   doi = {10.5281/zenodo.1158580},
   url = {https://github.com/pik-piam/magclass},
 }

tests/testthat/test-matchDim.R

@@ -0,0 +1,47 @@
+test_that("matchDim works", {
+
+  mp <- new.magpie(
+    cells_and_regions = c("AAA", "BBB", "CCC"),
+    years = paste0("y", c(2000, 2005, 2010)),
+    names = c("foo", "bar", "baz"),
+    sets = c("region", "t", "name")
+  )
+
+  mp2 <- new.magpie(
+    cells_and_regions = c("BBB", "CCC", "DDD"),
+    years = paste0("y", c(2000, 2010, 2020)),
+    names = c("foo", "bar", "qux"),
+    sets = c("region", "t", "name")
+  )
+
+  # 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
+  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
+  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
+  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
+  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")
+  expect_no_error(matchDim(mp, mp3, dim = 2))
+
+})