toolAggregate: toolAggregate

Description Usage Arguments Details Value Author(s) See Also Examples

View source: R/toolAggregate.R

Description

(Dis-)aggregates a magclass object from one resolution to another based on a relation matrix or mapping

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
toolAggregate(
  x,
  rel,
  weight = NULL,
  from = NULL,
  to = NULL,
  dim = 1,
  wdim = NULL,
  partrel = FALSE,
  negative_weight = "warn",
  mixed_aggregation = FALSE,
  verbosity = 1
)

Arguments

x

magclass object that should be (dis-)aggregated

rel

relation matrix, mapping or csv file containing a mapping. A mapping object should contain 2 columns in which each element of x is mapped to the category it should belong to after (dis-)aggregation

weight

magclass object containing weights which should be considered for a weighted aggregation. The provided weight should only contain positive values, but does not need to be normalized (any positive number>=0 is allowed). Please see the "details" section below for more information.

from

Name of the first column to be used in rel if it is a mapping (if not set the first or second column will be used).

to

Name of the second column to be used in rel if it is a mapping (if not set the second or third column will be used).

dim

Specifying the dimension of the magclass object that should be (dis-)aggregated. Either specified as an integer (1=spatial,2=temporal,3=data) or if you want to specify a sub dimension specified by name of that dimension or position within the given dimension (e.g. 3.2 means the 2nd data dimension, 3.8 means the 8th data dimension).

wdim

Specifying the according weight dimension as choosen with dim for the aggregation object. If set to NULL the function will try to automatically detect the dimension.

partrel

If set to TRUE allows that the relation matrix does contain less entries than x and vice versa. These values without relation are lost in the output.

negative_weight

Describes how a negative weight should be treated. "allow" means that it just should be accepted (dangerous), "warn" returns a warning and "stop" will throw an error in case of negative values

mixed_aggregation

boolean which allows for mixed aggregation (weighted mean mixed with summations). If set to TRUE weight columns filled with NA will lead to summation.

verbosity

Verbosity level of messages coming from the function: -1 = error, 0 = warning, 1 = note, 2 = additional information, >2 = no message

Details

Basically toolAggregate is doing nothing more than a normal matrix multiplication which is taking into account the 3 dimensional structure of MAgPIE objects. So, you can provide any kind of relation matrix you would like. However, for easier usability it is also possible to provide weights for a weighted (dis-)aggregation as a MAgPIE object. In this case rel must be a 1-0-matrix or a mapping between both resolutions. The weight needs to be provided in the higher spatial aggregation, meaning for aggregation the spatial resolution of your input data and in the case of disaggregation the spatial resolution of your output data. The temporal and data dimension must be either identical to the resolution of the data set that should be (dis-)aggregated or 1. If the temporal and/or data dimension is 1 this means that the same transformation matrix is applied for all years and/or all data columns. In the case that a column should be just summed up instead of being calculated as a weighted average you either do not provide any weight (than all columns are just summed up) or your set this specific weighting column to NA and mixed_aggregation to TRUE.

Value

the aggregated data in magclass format

Author(s)

Jan Philipp Dietrich, Ulrich Kreidenweis

See Also

calcOutput

Examples

1
2
3
4
5
6
7
8
# create example mapping
mapping <- data.frame(from=getRegions(population_magpie),to=rep(c("REG1","REG2"),5))
mapping 

# run aggregation
toolAggregate(population_magpie,mapping)
# weighted aggregation
toolAggregate(population_magpie,mapping, weight=population_magpie)

madrat documentation built on Dec. 25, 2019, 9:07 a.m.