| Title: | Data Class and Tools for Handling Spatial-Temporal Data |
|---|---|
| Description: | 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 and other dimensions to facilitate the development and interoperability of tools build for it. Additional features are name-based addressing of data and internal consistency checks (e.g. checking for the right data order in calculations). |
| Authors: | Jan Philipp Dietrich [aut, cre] (Potsdam Institute for Climate Impact Research, <https://orcid.org/0000-0002-4309-6431>), Benjamin Leon Bodirsky [aut] (Potsdam Institute for Climate Impact Research), Markus Bonsch [aut], Florian Humpenoeder [aut] (Potsdam Institute for Climate Impact Research), Stephen Bi [aut], Kristine Karstens [aut] (Potsdam Institute for Climate Impact Research), Debbora Leip [aut] (Potsdam Institute for Climate Impact Research), Pascal Sauer [aut] (Potsdam Institute for Climate Impact Research), Lavinia Baumstark [ctb] (Potsdam Institute for Climate Impact Research), Christoph Bertram [ctb], Anastasis Giannousakis [ctb], David Klein [ctb] (Potsdam Institute for Climate Impact Research), Ina Neher [ctb], Michaja Pehl [ctb] (Potsdam Institute for Climate Impact Research), Anselm Schultes [ctb], Miodrag Stevanovic [ctb] (Potsdam Institute for Climate Impact Research), Xiaoxi Wang [ctb], Felicitas Beier [ctb] (Potsdam Institute for Climate Impact Research), Mika Pflüger [ctb], Oliver Richters [ctb] (Potsdam Institute for Climate Impact Research) |
| Maintainer: | Jan Philipp Dietrich <[email protected]> |
| License: | LGPL-3 | file LICENSE |
| Version: | 6.17.1 |
| Built: | 2024-10-30 05:17:18 UTC |
| Source: | https://github.com/pik-piam/magclass |
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 and other dimensions to facilitate the development and interoperability of tools build for it. Additional features are name-based addressing of data and internal consistency checks (e.g. checking for the right data order in calculations).
Maintainer: Jan Philipp Dietrich <[email protected]>
Useful links:
Report bugs at https://github.com/pik-piam/magclass/issues
Function adds new columns to the existing magpie object.
add_columns(x, addnm = "new", dim = 3.1, fill = NA)add_columns(x, addnm = "new", dim = 3.1, fill = NA)
x |
MAgPIE object which should be extended. |
addnm |
The new elements that should be added to the (sub)dimension |
dim |
The (sub)dimension to be filled either identified via
name or dimension code (see |
fill |
fill value of length 1 for the newly added columns (NA by default) |
The extended MAgPIE object
Jan Philipp Dietrich, Benjamin Bodirsky
a <- maxample("animal") a2 <- add_columns(a, addnm = c("horse", "magpie"), dim = "species", fill = 42) getItems(a2, dim = 3) getItems(a2, dim = 3, split = TRUE) head(a2[, , "magpie"])a <- maxample("animal") a2 <- add_columns(a, addnm = c("horse", "magpie"), dim = "species", fill = 42) getItems(a2, dim = 3) getItems(a2, dim = 3, split = TRUE) head(a2[, , "magpie"])
Function adds a name dimension as dimension number "dim" with the name "add" with an empty data column with the name "nm".
add_dimension(x, dim = 3.1, add = NULL, nm = "dummy")add_dimension(x, dim = 3.1, add = NULL, nm = "dummy")
x |
MAgPIE object which should be extended. |
dim |
The dimension number of the new dimension (e.g. 3.1) |
add |
The name of the new dimension |
nm |
The name of the first entry in dimension "add". |
The extended MAgPIE object
Jan Philipp Dietrich, Benjamin Bodirsky
a <- maxample("animal") str(add_dimension(a, dim = 3.2)) str(add_dimension(a, dim = 2.3, nm = paste0("d", 1:3)))a <- maxample("animal") str(add_dimension(a, dim = 3.2)) str(add_dimension(a, dim = 2.3, nm = paste0("d", 1:3)))
magpie method for tibble::as_tibble
## S3 method for class 'magpie' as_tibble( x, ..., .rows = NULL, .name_repair = c("check_unique", "unique", "universal", "minimal"), rownames = pkgconfig::get_config("tibble::rownames", NULL) )## S3 method for class 'magpie' as_tibble( x, ..., .rows = NULL, .name_repair = c("check_unique", "unique", "universal", "minimal"), rownames = pkgconfig::get_config("tibble::rownames", NULL) )
x |
A magpie object |
... |
Unused, for extensibility. |
.rows |
The number of rows, useful to create a 0-column tibble or just as an additional check. |
.name_repair |
Treatment of problematic column names:
This argument is passed on as |
rownames |
How to treat existing row names of a data frame or matrix:
Read more in rownames. |
A tibble object
~~ Methods for function as.array ~~
## S4 method for signature 'magpie' as.array(x)## S4 method for signature 'magpie' as.array(x)
x |
object which should be converted to an array |
standard as.array-method
Conversion takes place just by removing MAgPIE-object specific elements
~~ Methods for function as.data.frame ~~
## S4 method for signature 'magpie' as.data.frame(x, rev = 1, raw = FALSE)## S4 method for signature 'magpie' as.data.frame(x, rev = 1, raw = FALSE)
x |
A MAgPIE-object |
rev |
The revision of the algorithm that should be used for conversion. rev=1 creates columns with the predefined names Cell, Region, Year, Data1, Data2,... and Value, rev=2 uses the set names of the MAgPIE object for naming and adds an attribute "dimtype" to the data.frame which contains information about the types of the different columns (spatial, temporal, data or value), rev=3 is identical to rev=2 except that characters are not being converted to factors (stringsAsFactors = FALSE). |
raw |
Logical to control whether years beginning with "y" should be converted to integers (without "y") and coordinates should be converted to numerics. If set to raw columns are returned as they are in the initial object. |
Conversion creates columns for Cell, Region, Year, Data1, Data2,... and Value
pop <- maxample("pop") head(as.data.frame(pop)) head(as.data.frame(pop, rev = 2)) a <- maxample("animal") head(as.data.frame(a, rev = 3)) head(as.data.frame(a, rev = 3, raw = TRUE)) attr(as.data.frame(a, rev = 3), "dimtype")pop <- maxample("pop") head(as.data.frame(pop)) head(as.data.frame(pop, rev = 2)) a <- maxample("animal") head(as.data.frame(a, rev = 3)) head(as.data.frame(a, rev = 3, raw = TRUE)) attr(as.data.frame(a, rev = 3), "dimtype")
Convert magclass object to a RasterBrick object
as.RasterBrick(x, res = NULL)as.RasterBrick(x, res = NULL)
x |
MAgPIE object |
res |
spatial data resolution. If not provided it will be guessed. |
A RasterBrick object
Jan Philipp Dietrich
## Not run: if (requireNamespace("raster", quietly = TRUE)) { r <- raster::brick(ncols = 36, nrows = 18, nl = 4) r[14:18, 25:28] <- (1:20 %*% t(1:4)) names(r) <- c("y2000..bla", "y2001..bla", "y2000..blub", "y2001..blub") m <- as.magpie(r) r2 <- as.RasterBrick(m) } ## End(Not run)## Not run: if (requireNamespace("raster", quietly = TRUE)) { r <- raster::brick(ncols = 36, nrows = 18, nl = 4) r[14:18, 25:28] <- (1:20 %*% t(1:4)) names(r) <- c("y2000..bla", "y2001..bla", "y2000..blub", "y2001..blub") m <- as.magpie(r) r2 <- as.RasterBrick(m) } ## End(Not run)
Convert magclass object to a SpatRaster object. Requires the terra package.
as.SpatRaster(x, res = NULL)as.SpatRaster(x, res = NULL)
x |
MAgPIE object |
res |
spatial data resolution. If not provided it will be guessed. |
A SpatRaster object
Jan Philipp Dietrich
if (requireNamespace("terra", quietly = TRUE)) { r <- terra::rast(ncols = 360, nrows = 180, nl = 4) r[85:89, 176:179] <- (1:20 %*% t(1:4)) r[15:19, 76:79] <- (10 + 1:20 %*% t(1:4)) names(r) <- c("y2000..bla", "y2001..bla", "y2000..blub", "y2001..blub") m <- as.magpie(r) r2 <- as.SpatRaster(m) }if (requireNamespace("terra", quietly = TRUE)) { r <- terra::rast(ncols = 360, nrows = 180, nl = 4) r[85:89, 176:179] <- (1:20 %*% t(1:4)) r[15:19, 76:79] <- (10 + 1:20 %*% t(1:4)) names(r) <- c("y2000..bla", "y2001..bla", "y2000..blub", "y2001..blub") m <- as.magpie(r) r2 <- as.SpatRaster(m) }
Convert magclass object to a SpatRasterDataset object. Requires the terra package.
as.SpatRasterDataset(...)as.SpatRasterDataset(...)
... |
arguments passed to as.SpatRaster |
Calls as.SpatRaster and then spatRasterToDataset.
A SpatRasterDataset object
Pascal Sauer
Convert magclass object to a SpatVector object. Requires the terra package and requires the magclass object to provide the geometry of the spatial entities as "geometry" attribute in "WKT" format. (see object "m" in example).
as.SpatVector(x)as.SpatVector(x)
x |
MAgPIE object |
A SpatVector object
Jan Philipp Dietrich
if (requireNamespace("terra", quietly = TRUE)) { r <- terra::rast(ncols = 360, nrows = 180, nl = 4) r[85:89, 176:179] <- (1:20 %*% t(1:4)) r[15:19, 76:79] <- (10 + 1:20 %*% t(1:4)) names(r) <- c("y2000..bla", "y2001..bla", "y2000..blub", "y2001..blub") v <- terra::as.polygons(r) m <- as.magpie(v) attr(m, "geometry") attr(m, "crs") v2 <- as.SpatVector(m) }if (requireNamespace("terra", quietly = TRUE)) { r <- terra::rast(ncols = 360, nrows = 180, nl = 4) r[85:89, 176:179] <- (1:20 %*% t(1:4)) r[15:19, 76:79] <- (10 + 1:20 %*% t(1:4)) names(r) <- c("y2000..bla", "y2001..bla", "y2000..blub", "y2001..blub") v <- terra::as.polygons(r) m <- as.magpie(v) attr(m, "geometry") attr(m, "crs") v2 <- as.SpatVector(m) }
Function cleans MAgPIE objects so that they follow some extended magpie object rules (currently it makes sure that the dimnames have names and removes cell numbers if it is purely regional data)
clean_magpie(x, what = "all", maindim = 1:3)clean_magpie(x, what = "all", maindim = 1:3)
x |
MAgPIE object which should be cleaned. |
what |
term defining what type of cleaning should be performed. Current modes are "cells" (removes cell numbers if the data seems to be regional - this should be used carefully as it might remove cell numbers in some cases in which they should not be removed), "sets" (making sure that all dimensions have names), "items" (replace empty elements with single spaces " ") and "all" (performing all available cleaning methods) |
maindim |
main dimension(s) the cleaning should get applied to. |
The eventually corrected MAgPIE object
Jan Philipp Dietrich
"magpie"
pop <- maxample("pop") a <- clean_magpie(pop)pop <- maxample("pop") a <- clean_magpie(pop)
This function will remove names in the data dimension which are the same for
each element (meaning that this data dimension contains exactly one element)
or, if forced, remove any other subdimension. It is a generalized version
of the function collapseNames
collapseDim(x, dim = NULL, keepdim = NULL)collapseDim(x, dim = NULL, keepdim = NULL)
x |
MAgPIE object |
dim |
Either NULL, dimension code or
name of dimension or a vector of these. If set to NULL all single entry subdimensions will
be removed as they are irrelevant to uniquely identfy a data element. If specified, only the specified
subdimensions will be removed (See |
keepdim |
(only considered if |
The provided MAgPIE object with collapsed dimensions
This function has some similarities to dimReduce, but
serves a different purpose. While collapseDim only removes
dimensions which contain only a single element or which it is
specifically told to remove, dimReduce looks whether the
entries of a multi-entry dimension are all the same and removes dimensions
for which this is the case. In some cases both will lead to the same result
but in many other cases the results will differ.
Jan Philipp Dietrich
x <- new.magpie(c("GLO.1", "GLO.2"), 2000, c("bla.a", "bla.b")) collapseDim(x) collapseDim(x, keepdim = 1:2) collapseDim(x, dim = 1.1) collapseDim(x, dim = 3.2)x <- new.magpie(c("GLO.1", "GLO.2"), 2000, c("bla.a", "bla.b")) collapseDim(x) collapseDim(x, keepdim = 1:2) collapseDim(x, dim = 1.1) collapseDim(x, dim = 3.2)
This function has been superseded by collapseDim which is a
more generalized version of this function. Please use this one instead!
collapseNames(x, collapsedim = NULL, preservedim = NULL)collapseNames(x, collapsedim = NULL, preservedim = NULL)
x |
MAgPIE object |
collapsedim |
If you want to remove the names of particular dimensions provide the dimensions here. Since the function only works in the third dimension, you have to count from there on (e.g. dim = 3.2 refers to collapsedim = 2). Alternatively, you can also specify the name of the dimension. Default: NULL. CAUTION with parameter collapsedim! You could also force him to remove dimnames, which are NOT the same for each element and so create duplicates in dimnames. |
preservedim |
If you want to remove the name of particular dimensions except some, you can specify the dimension(s) to preserve here. See collapsedim for naming convention. Note that preservedim will be ignored in the case, of a specified collapsedim |
This function will remove names in the data dimension which are the same for each element (meaning that this data dimension contains exactly one element)
The provided MAgPIE object with collapsed names
Jan Philipp Dietrich, David Klein, Xiaoxi Wang
collapseDim, getItems,
"magpie"
~~ Methods for function colSums and colMeans ~~
## S4 method for signature 'magpie' colSums(x, na.rm = FALSE, dims = 1, ...)## S4 method for signature 'magpie' colSums(x, na.rm = FALSE, dims = 1, ...)
x |
object on which calculation should be performed |
na.rm |
logical. Should missing values (including NaN) be omitted from the calculations? |
dims |
integer: Which dimensions are regarded as "rows" or "columns" to sum over. For row*, the sum or mean is over dimensions dims+1, ...; for col* it is over dimensions 1:dims. |
... |
further arguments passed to other colSums/colMeans methods |
normal colSums and colMeans method
classical method prepared to handle MAgPIE objects
MAgPIE objects can be incomplete to reduce memory. This function blows up a magpie object to its real dimensions, so you can apply unwrap.
complete_magpie(x, fill = NA, dim = 3)complete_magpie(x, fill = NA, dim = 3)
x |
MAgPIE object which should be completed. |
fill |
Value that shall be written into the missing entries |
dim |
dimensions in which the completion should take place (1, 2 and/or 3). For
full completion use |
The completed MAgPIE object
Jan Philipp Dietrich, Benjamin Bodirsky
pop <- maxample("pop") complete_magpie(pop) ani <- maxample("animal") complete_magpie(ani)pop <- maxample("pop") complete_magpie(pop) ani <- maxample("animal") complete_magpie(ani)
Cross-Fades the values of one MAGPIE object into the values of another over a certain time
convergence( origin, aim, start_year = NULL, end_year = NULL, direction = NULL, type = "smooth", par = 1.5 )convergence( origin, aim, start_year = NULL, end_year = NULL, direction = NULL, type = "smooth", par = 1.5 )
origin |
an object with one name-column |
aim |
Can be twofold: An magpie object or a numeric value. |
start_year |
year in which the convergence from origin to aim starts. If set to NULL the the first year of aim is used as start_year |
end_year |
year in which the convergence from origin to aim shall be (nearly) reached. If set to NULL the the last year of aim is used as end_year. |
direction |
NULL, "up" or "down". NULL means normal convergence in both directions, "up" is only a convergence if origin<aim, "down" means only a convergence if origin>aim |
type |
"smooth", "s", "linear" or "decay". Describes the function used for convergence (x starts at 0 and ends at 1): "linear" means linear interpolation. "s" is an s-curve which starts from origin in start_year and reaches aim precisely in end_year. After 50% of the convergence time, it reaches about the middle of the two values. It's using the function x^4/(0.07+x^4)*1.07). "smooth" is a conversion based on the function x^3/(0.1+x^3). With "smooth" only 90% of convergence will be reached in the end year, full convergence is approached as x approaches infinity. "decay" is a conversion based on the function x / (par + x) * (par + 1). |
par |
parameter value for convergence function; currently only used for type="decay" |
returns a time-series with the same timesteps as origin, which lineary fades into the values of the aim object
Benjamin Bodirsky, Jan Philipp Dietrich
pop <- maxample("pop") population <- add_columns(pop, "MIX") population[, , "MIX"] <- convergence(population[, , "A2"], population[, , "B1"])pop <- maxample("pop") population <- add_columns(pop, "MIX") population[, , "MIX"] <- convergence(population[, , "A2"], population[, , "B1"])
This function copies attributes from one object and assigns them to another.
copy.attributes( from, to, delete = c("names", "row.names", "class", "dim", "dimnames"), delete2 = NULL ) copy.attributes( to, delete = c("names", "row.names", "class", "dim", "dimnames"), delete2 = NULL ) <- valuecopy.attributes( from, to, delete = c("names", "row.names", "class", "dim", "dimnames"), delete2 = NULL ) copy.attributes( to, delete = c("names", "row.names", "class", "dim", "dimnames"), delete2 = NULL ) <- value
from |
object from which the attributes should be taken |
to |
object to which the attributes should be written |
delete |
attributes which should not be copied. By default this are class specific attributes which might cause problems if copied to another object. But you can add or remove attributes from the vector. |
delete2 |
Identical to delete and just added for convenience for the case that you want to delete additional attributes but do not want to repeat the vector given in delete. In the function both vectors, delete and delete2, are just merged to one deletion vector. |
value |
Same as "from" (object from which the attributes should be taken) |
copy.attributes(
to,
delete = c("names", "row.names", "class", "dim", "dimnames"),
delete2 = NULL
) <- value: assign attributes from object "value"
Jan Philipp Dietrich
from <- array(12) attr(from,"blablub") <- "I am an attribute!" attr(from,"blablub2") <- "I am another attribute!" print(attributes(from)) to <- as.magpie(0) print(attributes(to)) copy.attributes(to) <- from print(attributes(to))from <- array(12) attr(from,"blablub") <- "I am an attribute!" attr(from,"blablub2") <- "I am another attribute!" print(attributes(from)) to <- as.magpie(0) print(attributes(to)) copy.attributes(to) <- from print(attributes(to))
This function copies MAgPIE-files from one location to another. During the copying it is also possible to change the file type (e.g. from 'mz' to 'csv')
copy.magpie(input_file, output_file, round = NULL)copy.magpie(input_file, output_file, round = NULL)
input_file |
file, that should be copied |
output_file |
copy destination |
round |
number of digits the values should be rounded. NULL means no rounding |
Jan Philipp Dietrich
# copy.magpie("bla.csv","blub.mz")# copy.magpie("bla.csv","blub.mz")
Function converts a dimension name or number to a dimension Code used for MAgPIE objects
dimCode(dim, x, missing = 0, strict = FALSE, sep = ".")dimCode(dim, x, missing = 0, strict = FALSE, sep = ".")
dim |
A vector of dimension numbers or dimension names which should be translated |
x |
MAgPIE object in which the dimensions should be searched for. |
missing |
Either a value to which a dimension should be set in case that it is not found (default is 0), or "stop" indicating that the function should throw an error in these cases. |
strict |
if set to TRUE also properly set dimension names which refer to non-existing subdimensions will be treated as missing, otherwise these dimension codes will be returned, even if the subdimension does not exist |
sep |
A character separating joined dimension names |
A dimension code identifying the dimension. Either a integer which represents the main dimensions (1=spatial, 2=temporal, 3=data) or a numeric, representing the subdimensions of a dimension (e.g. 3.2 for the second data dimension).
Jan Philipp Dietrich, Kristine Karstens
pop <- maxample("pop") dimCode(c("t", "scenario", "blablub"), pop)pop <- maxample("pop") dimCode(c("t", "scenario", "blablub"), pop)
Function checks whether a dimension exsist in a MAgPIE objects
dimExists(dim, x, sep = ".")dimExists(dim, x, sep = ".")
dim |
A vector of dimension numbers or dimension names which should be checked for |
x |
MAgPIE object in which the dimensions should be searched for. |
sep |
A character separating joined dimension names |
Boolean indicating whether dimension exists or not
Jan Philipp Dietrich
pop <- maxample("pop") dimExists(c("t","scenario","blablub"),pop)pop <- maxample("pop") dimExists(c("t","scenario","blablub"),pop)
Changes the order of the sub-dimension in a magpie object similar to unwrapping and applying the aperm command, but more efficient.
dimOrder(x, perm, dim = 3)dimOrder(x, perm, dim = 3)
x |
magpie object |
perm |
vector with the new order of the sub-dimension. Missing sub-dimensions will added automatically at the end |
dim |
main dimension in which the order of sub-dimensions should be changed (1, 2 or 3) |
magpie object
Jan Philipp Dietrich, Benjamin Leon Bodirsky
a <- maxample("animal") head(a) head(dimOrder(a, perm = 3:1, dim = 1)) head(dimOrder(a, perm = c(2,1,3), dim = 3))a <- maxample("animal") head(a) head(dimOrder(a, perm = 3:1, dim = 1)) head(dimOrder(a, perm = c(2,1,3), dim = 3))
Remove dimensions which contain identical data for all elements in it
dimReduce(x, dim_exclude = NULL)dimReduce(x, dim_exclude = NULL)
x |
MAgPIE object which should be reduced |
dim_exclude |
Vector with names of dimensions which must not be reduced |
The reduced MAgPIE object
This function has some similarities to collapseDim, but
serves a different purpose. While collapseDim only removes
dimensions which contain only a single element or which it is
specifically told to remove, dimReduce looks whether the
entries of a multi-entry dimension are all the same and removes dimensions
for which this is the case. In some cases both will lead to the same result
but in many other cases the results will differ.
Jan Philipp Dietrich
# create data with 5 identical scenarios p <- add_dimension(maxample("pop")[1:3, 1:3, ], nm = paste0("scen", 1:2)) str(p) str(dimReduce(p)) # set years to same value p[, , ] <- setYears(p[, 1, ], NULL) str(p) str(dimReduce(p)) # set regions to same value p[, , ] <- setCells(p[1, , ], "GLO") str(p) str(dimReduce(p))# create data with 5 identical scenarios p <- add_dimension(maxample("pop")[1:3, 1:3, ], nm = paste0("scen", 1:2)) str(p) str(dimReduce(p)) # set years to same value p[, , ] <- setYears(p[, 1, ], NULL) str(p) str(dimReduce(p)) # set regions to same value p[, , ] <- setCells(p[1, , ], "GLO") str(p) str(dimReduce(p))
This function sums over any (sub-)dimension of a magpie object
dimSums(x, dim = 3, na.rm = FALSE)dimSums(x, dim = 3, na.rm = FALSE)
x |
A MAgPIE-object |
dim |
The dimensions(s) to sum over. A vector of dimension codes or dimension names.
See |
na.rm |
logical. Should missing values (including NaN) be omitted from the calculations? |
A MAgPIE object with values summed over the specified dimensions
Jan Philipp Dietrich
a <- maxample("animal") dimSums(a, dim = c(1, 2, 3.2)) dimSums(a, dim = c("x", "y", "cell", "month"))a <- maxample("animal") dimSums(a, dim = c(1, 2, 3.2)) dimSums(a, dim = c("x", "y", "cell", "month"))
Escapes all symbols in a string which have a special meaning in regular expressions.
escapeRegex(x)escapeRegex(x)
x |
String or vector of strings that should be escaped. |
The escaped strings.
Jan Philipp Dietrich
Extend a magpie object to a dense grid based on the given xRange, yRange and resolution. This is e.g. required when writing netCDF files. Extending a sparse magpie object to a dense grid requires much more memory, so use with caution.
extend(x, gridDefinition = NULL, crop = FALSE)extend(x, gridDefinition = NULL, crop = FALSE)
x |
A magpie object |
gridDefinition |
A vector of 5 numeric values: c(xMin, xMax, yMin, yMax, resolution). Use c(-179.75, 179.75, -89.75, 89.75, 0.5) to extend to a standard 0.5-degree-resolution lon/lat grid. If NULL, use min/max of coordinates in x and guessResolution. |
crop |
If TRUE, discard cells from x which are not in the gridDefinition grid. If FALSE, throw an error if the coordinates of x are not a subset of the extended coordinates. |
Magpie object x with dense grid according to gridDefinition, gaps filled with NA.
Pascal Sauer
If a MAgPIE object is created from a source with more than one data dimension, these data dimensions are combined to a single dimension. fulldim reconstructs the original dimensionality and reports it.
fulldim(x, sep = ".")fulldim(x, sep = ".")
x |
A MAgPIE-object |
sep |
A character separating joined dimension names |
A list containing in the first element the dim output and in the second element the dimnames output of the reconstructed array.
Jan Philipp Dietrich
Extracts cell names of a MAgPIE-object
getCells(x) getCells(x) <- value setCells(object, nm = "GLO")getCells(x) getCells(x) <- value setCells(object, nm = "GLO")
x, object
|
MAgPIE object |
value, nm
|
cell names the data should be set to. |
setCells is a shortcut to use a MAgPIE object with manipulated cell names. setCells uses the variable names "object" and "nm" in order to be consistent to the already existing function setNames.
getCells returns cell names of the MAgPIE-object, whereas setCells returns the MAgPIE object with the manipulated cell names.
getCells(x) <- value: set cell names
setCells(): set cell names
Jan Philipp Dietrich
getRegions, getNames,
setNames, getCPR, read.magpie,
write.magpie, "magpie"
a <- as.magpie(1) getCells(a) setCells(a, "AFR")a <- as.magpie(1) getCells(a) setCells(a, "AFR")
Extracts the comment from a MAgPIE-object
getComment(x) getComment(x) <- value setComment(object, nm = NULL)getComment(x) getComment(x) <- value setComment(object, nm = NULL)
x, object
|
MAgPIE object |
value, nm
|
A vector containing the comment. |
getComment returns the comment attached to a MAgPIE-object, NULL if no comment is present. setComment returns the magpie object with the modified comment.
getComment(x) <- value: set comment
setComment(): set comment
Markus Bonsch
getRegions, getNames,
getYears, getCPR, read.magpie,
write.magpie, "magpie"
a <- as.magpie(1) #returns NULL getComment(a) #set the comment getComment(a)<-c("bla","blubb") getComment(a)a <- as.magpie(1) #returns NULL getComment(a) #set the comment getComment(a)<-c("bla","blubb") getComment(a)
Extracts spatial coordinates of a MAgPIE-object
getCoords(x, xlab = "x", ylab = "y") getCoords(x, xlab = "x", ylab = "y") <- valuegetCoords(x, xlab = "x", ylab = "y") getCoords(x, xlab = "x", ylab = "y") <- value
x |
MAgPIE object |
xlab |
label of x-dimension |
ylab |
label of y-dimension |
value |
coordinates as two column data.frame the data should be set to (first column = x, second column = y). |
coordinates of the MAgPIE-object
getCoords(x, xlab = "x", ylab = "y") <- value: set coordinates
Jan Philipp Dietrich
as.RasterBrick, getItems, "magpie"
a <- maxample("animal") getCoords(a)a <- maxample("animal") getCoords(a)
Counts how often each element of the provided subdimension exists in the given data set. Originally created to count the number of cells in a region (this is also where its name originates from) it can now be used to count elements of any subdimension via the dim argument.
getCPR(x, dim = 1.1)getCPR(x, dim = 1.1)
x |
MAgPIE object or a resolution written as numeric (currently only data for 0.5 degree resolution is available). |
dim |
Dimension for which the items should be returned. Either number or
name of dimension or a vector of these (in case of a vector all subimensions
must belong to the same main dimension!). See |
cells per region
Jan Philipp Dietrich
getRegions, read.magpie,
write.magpie
getCPR(0.5) a <- maxample("animal") getCPR(a, dim = "color") getCPR(a, dim = 3.2) getCPR(a, dim = "country") getCPR(a, dim = c("color", "species"))getCPR(0.5) a <- maxample("animal") getCPR(a, dim = "color") getCPR(a, dim = 3.2) getCPR(a, dim = "country") getCPR(a, dim = c("color", "species"))
Function which tries to detect the dimension to which the given elems belong
getDim(elems, x, fullmatch = FALSE, dimCode = TRUE)getDim(elems, x, fullmatch = FALSE, dimCode = TRUE)
elems |
A vector of characters containing the elements that should be found in the MAgPIE object |
x |
MAgPIE object in which elems should be searched for. |
fullmatch |
If enabled, only dimensions which match exactly the elements provided will be returned. Otherwise, it is sufficient if elems contains a subset of the dimension. |
dimCode |
If enabled, the dimCode will be returned, otherwise the name of the dimension. |
The name or dimCode of the dimensions in which elems were found.
Jan Philipp Dietrich
pop <- maxample("pop") getDim(c("AFR","CPA"),pop) getDim(c("AFR","CPA"),pop,fullmatch=TRUE) getDim(c("AFR","CPA"),pop,dimCode=FALSE)pop <- maxample("pop") getDim(c("AFR","CPA"),pop) getDim(c("AFR","CPA"),pop,fullmatch=TRUE) getDim(c("AFR","CPA"),pop,dimCode=FALSE)
Extract items of a given (sub-)dimension of a MAgPIE-object
getItems(x, dim = NULL, split = FALSE, full = FALSE) getItems(x, dim, full = NULL, maindim = NULL, raw = FALSE) <- valuegetItems(x, dim = NULL, split = FALSE, full = FALSE) getItems(x, dim, full = NULL, maindim = NULL, raw = FALSE) <- value
x |
MAgPIE object |
dim |
Dimension for which the items should be returned. Either number or
name of dimension or a vector of these. See |
split |
Boolean which determines whether a main dimension should be split in subdimensions. Only applicable to main dimensions (1,2,3) and ignored for all other. |
full |
if TRUE dimension names are returned as they are (including repetitions), if FALSE only the dimension elements (unique list of entries) are returned. |
maindim |
main dimension the data should be added to (does not need to be set if |
raw |
if set to FALSE inputs will be corrected (e.g. dots replaced by the letter "p") if necessary. If TRUE data will be written as is (risking the creation of inconsistent objects). |
value |
a vector with the length of the main dimension the dimnames should be replaced in / added to. If set to NULL the corresponding dimension will be removed. |
items of the requested dimension in the MAgPIE-object. If split=TRUE and applied to a main dimension (1,2,3) a list of items for each sub-dimension.
getItems(x, dim, full = NULL, maindim = NULL, raw = FALSE) <- value: set dimension names
Jan Philipp Dietrich
x <- maxample("pop") getItems(x, "scenario") getItems(x, 3.1) getItems(x, "i") <- paste0("REG", seq_len(ncells(x))) getItems(x, "i") y <- x[, 1, ] getItems(y, "t") <- NULLx <- maxample("pop") getItems(x, "scenario") getItems(x, 3.1) getItems(x, "i") <- paste0("REG", seq_len(ncells(x))) getItems(x, "i") y <- x[, 1, ] getItems(y, "t") <- NULL
Extracts dataset names of a MAgPIE-object
getNames(x, fulldim = FALSE, dim = NULL) getNames(x, dim = NULL) <- valuegetNames(x, fulldim = FALSE, dim = NULL) getNames(x, dim = NULL) <- value
x |
MAgPIE object |
fulldim |
specifies, how the object is treated. In case of FALSE, it is assumed that x is 3 dimensional and dimnames(x)[[3]] is returned. In case of TRUE, the dimnames of the real third dimension namesare returned |
dim |
Argument to choose a specific data dimension either by name of the dimension or by number of the data dimension. |
value |
a vector of names current names should be replaced with. If only one data element exists you can also set the name to NULL. |
setNames is a shortcut to use a MAgPIE object with manipulated data names. The setNames method uses the variable names "object" and "nm" in order to be consistent to the already existing function setNames.
getNames returns data names of the MAgPIE-object, whereas setNames returns the MAgPIE object with the manipulated data names.
getNames(x, dim = NULL) <- value: set names
Jan Philipp Dietrich
setNames-methods, getRegions, getYears,
getCPR, read.magpie,
write.magpie,ndata,
"magpie"
a <- as.magpie(1) getNames(a) setNames(a, "bla") x <- new.magpie("GLO", 2000, c("a.o1", "b.o1", "a.o2")) getNames(x, dim = 2) getSets(x, fulldim = FALSE)[3] <- "bla.blub" getNames(x, dim = "bla") getSets(x)[4] <- "ble" getNames(x, dim = "ble") <- c("Hi", "Bye") xa <- as.magpie(1) getNames(a) setNames(a, "bla") x <- new.magpie("GLO", 2000, c("a.o1", "b.o1", "a.o2")) getNames(x, dim = 2) getSets(x, fulldim = FALSE)[3] <- "bla.blub" getNames(x, dim = "bla") getSets(x)[4] <- "ble" getNames(x, dim = "ble") <- c("Hi", "Bye") x
Extracts a vector containing the region of each cell of a MAgPIE-object
getRegionList(x) getRegionList(x) <- valuegetRegionList(x) getRegionList(x) <- value
x |
MAgPIE object |
value |
A vector with ncell elements containing the regions of each cell. |
A vector with ncell elements containing the region of each cell.
getRegionList(x) <- value: set region names
Jan Philipp Dietrich
getRegions,getYears,
getNames, getCPR, read.magpie,
write.magpie, "magpie"
# a <- read.magpie("example.mz") # getRegionList(a)# a <- read.magpie("example.mz") # getRegionList(a)
Extracts regions of a MAgPIE-object
getRegions(x) getRegions(x) <- valuegetRegions(x) getRegions(x) <- value
x |
MAgPIE object |
value |
Vector containing the new region names of the MAgPIE objects.
If you also want to change the mapping of regions to cell please use
|
Regions of the MAgPIE-object
getRegions(x) <- value: overwrite region names
Jan Philipp Dietrich
getYears, getNames,
getCPR, read.magpie, write.magpie,
"magpie"
# a <- read.magpie("example.mz") # getRegions(a)# a <- read.magpie("example.mz") # getRegions(a)
Extracts sets of a MAgPIE-object if available
getSets(x, fulldim = TRUE, sep = ".") getSets(x, fulldim = TRUE, sep = ".") <- valuegetSets(x, fulldim = TRUE, sep = ".") getSets(x, fulldim = TRUE, sep = ".") <- value
x |
MAgPIE object |
fulldim |
bool: Consider dimension 3 as a possible aggregate of more dimensions (TRUE) or stick to it as one dimension (FALSE) |
sep |
A character separating joined dimension names |
value |
A vector with set names you want to replace the current set names of the object with. |
Sets of the MAgPIE-object. If no information about contained sets is available NULL
getSets(x, fulldim = TRUE, sep = ".") <- value: replace set names
Markus Bonsch, Jan Philipp Dietrich
getRegions,
getNames,getYears, getCPR,
read.magpie, write.magpie,
"magpie"
a <- new.magpie("GLO.1", 2000, c("a.o1", "b.o1", "a.o2")) getSets(a) <- c("reg", "cell", "t", "bla", "blub") getSets(a) getSets(a)["d3.1"] <- "BLA" getSets(a, fulldim = FALSE) getSets(a)a <- new.magpie("GLO.1", 2000, c("a.o1", "b.o1", "a.o2")) getSets(a) <- c("reg", "cell", "t", "bla", "blub") getSets(a) getSets(a)["d3.1"] <- "BLA" getSets(a, fulldim = FALSE) getSets(a)
Extracts years of a MAgPIE-object
getYears(x, as.integer = FALSE) getYears(x) <- value setYears(object, nm = NULL)getYears(x, as.integer = FALSE) getYears(x) <- value setYears(object, nm = NULL)
x, object
|
MAgPIE object |
as.integer |
Switch to decide, if output should be the used year-name (e.g. "y1995") or the year as integer value (e.g. 1995) |
value, nm
|
Years the data should be set to. Either supplied as a vector of integers or a vector of characters in the predefined year format ("y0000"). If only 1 year exist you can also set the name of the year to NULL. |
setYears is a shortcut to use a MAgPIE object with manipulated year names. setYears uses the variable names "object" and "nm" in order to be consistent to the already existing function setNames.
getYears returns years of the MAgPIE-object, whereas setYears returns the MAgPIE object with the manipulated years.
getYears(x) <- value: rename years
setYears(): set years
Jan Philipp Dietrich
getRegions, getNames,
setNames, getCPR, read.magpie,
write.magpie, "magpie"
a <- as.magpie(1) getYears(a) setYears(a,1995)a <- as.magpie(1) getYears(a) setYears(a,1995)
Guess the resolution of the given magpie object/coordinates by looking at the minimum difference between unique sorted values. Fall back to 0.5 if guess is infinite.
guessResolution(x)guessResolution(x)
x |
A magpie object or the coordinates of a magpie object (the result
of |
The guessed resolution of the data
Jan Philipp Dietrich, Pascal Sauer
Checks, whether object contains coordinates.
hasCoords(x, xlab = "x", ylab = "y")hasCoords(x, xlab = "x", ylab = "y")
x |
MAgPIE object |
xlab |
label of x-dimension |
ylab |
label of y-dimension |
Boolean indicating whether coordinates were found or not
Jan Philipp Dietrich
hasCoords(maxample("pop")) hasCoords(maxample("animal"))hasCoords(maxample("pop")) hasCoords(maxample("animal"))
Checks, whether set names have been set
hasSets(x)hasSets(x)
x |
MAgPIE object |
Boolean indicating whether coordinates were found or not
Jan Philipp Dietrich
hasSets(maxample("pop")) hasSets(maxample("animal"))hasSets(maxample("pop")) hasSets(maxample("animal"))
head and tail methods for MAgPIE objects to extract the head or tail of an object
## S3 method for class 'magpie' head(x, n1 = 3L, n2 = 6L, n3 = 2L, ...)## S3 method for class 'magpie' head(x, n1 = 3L, n2 = 6L, n3 = 2L, ...)
x |
MAgPIE object |
n1, n2, n3
|
number of lines in first, second and third dimension that should be returned. If the given number is higher than the length of the dimension all entries in this dimension will be returned. |
... |
arguments to be passed to or from other methods. |
head returns the first n1 x n2 x n3 entries, tail returns the last n1 x n2 x n3 entries.
Jan Philipp Dietrich
pop <- maxample("pop") head(pop) tail(pop,2,4,1)pop <- maxample("pop") head(pop) tail(pop,2,4,1)
Functions to find out whether a vector consists of strings consistent with the definition for auto-detection of temporal or spatial data.
is.temporal(x)is.temporal(x)
x |
A vector |
Returns TRUE or FALSE
Jan Philipp Dietrich
is.temporal(1991:1993) is.spatial(c("GLO","AFR"))is.temporal(1991:1993) is.spatial(c("GLO","AFR"))
Function to find out whether a vector consists of strings in the format "yXXXX" or "XXXX" with X being a number
isYear(x, with_y = TRUE)isYear(x, with_y = TRUE)
x |
A vector |
with_y |
indicates which dataformat years have to have (4-digit without y (e.g.1984) or 5digit including y (y1984)) |
Returns a vector of the length of x with TRUE and FALSE
Benjamin Bodirsky
x <- c("1955", "y1853", "12a4") isYear(x, with_y = TRUE) isYear(x, with_y = FALSE)x <- c("1955", "y1853", "12a4") isYear(x, with_y = TRUE) isYear(x, with_y = FALSE)
log-method for MAgPIE-objects respectively. Works exactly as for arrays.
## S4 method for signature 'magpie' log(x, base = exp(1))## S4 method for signature 'magpie' log(x, base = exp(1))
x |
a magpie object |
base |
ia positive or complex number: the base with respect to which logarithms are computed. Defaults to e=exp(1). |
works as log(x) for arrays.
Filters high frequencies out of a time series. The filter has the structure x'(n) = (x(n-1)+2*x(n)+x(n+1))/4
lowpass(x, i = 1, fix = NULL, altFilter = NULL, warn = TRUE)lowpass(x, i = 1, fix = NULL, altFilter = NULL, warn = TRUE)
x |
Vector of data points, that should be filtered or MAgPIE object |
i |
number of iterations the filter should be applied to the data |
fix |
Fixes the starting and/or ending data point. Default value is
|
altFilter |
set special filter rule to indexes defined in this parameter. The special filter has the structure x'(n) = (2*x(n)+x(n+1))/3 |
warn |
boolean deciding whether lowpass issues a warning for critical parameter choices or not |
The filtered data vector or MAgPIE object
Jan Philipp Dietrich, Misko Stevanovic
lowpass(c(1, 2, 11, 3, 4)) # to fix the starting point lowpass(c(0, 9, 1, 5, 14, 20, 6, 11, 0), i = 2, fix = "start")lowpass(c(1, 2, 11, 3, 4)) # to fix the starting point lowpass(c(0, 9, 1, 5, 14, 20, 6, 11, 0), i = 2, fix = "start")
General magclass-dataset
Please do not directly access that data. It should be only used by library functions.
Jan Philipp Dietrich
Expands a MAgPIE object based on a reference
magpie_expand(x, ref)magpie_expand(x, ref)
x |
MAgPIE object that should be expanded |
ref |
MAgPIE object that serves as a reference |
Expansion means here that the dimensions of x are expanded accordingly to ref. Please note that this is really only about expansion. In the case that one dimension of ref is smaller than of x nothing happens with this dimension. At the moment magpie_expand is only internally available in the magclass library
You can influence the verbosity of this function by setting the option "magclass.verbosity". By default verbosity is set to 1 which means that only warnings are returned. Setting verbosity to 2 means that warnings as well as additional notes are returned. This is done by options(verbosity.level=2)
With version 5 of the package magpie_expand has been updated to a newer version
(currently 2.1) and since version 6 this is the only currently supported
version. To switch to the old setup you have to install magclass in a version < 6
and set options(magclass_expand_version=1).
By default expansion is based on the elements in a dimension ignoring the set name of
the dimension. To expand based on set names instead of contents (recommended) you can
switch options(magclass_setMatching=TRUE). Please be careful with this setting
as it alters the behavior of magclass objects quite significantly! For more information
have a look at vignette("magclass-expansion").
An expanded version of x.
Jan Philipp Dietrich
a <- new.magpie(c("AFR", "CPA"), "y1995", c("m", "n")) b <- new.magpie("GLO", "y1995", c("bla", "blub")) magpie_expand(b, a) options(magclass.verbosity = 2) magpie_expand(b, a)a <- new.magpie(c("AFR", "CPA"), "y1995", c("m", "n")) b <- new.magpie("GLO", "y1995", c("bla", "blub")) magpie_expand(b, a) options(magclass.verbosity = 2) magpie_expand(b, a)
Expands a single MAgPIE object dimension
magpie_expand_dim(x, ref, dim = 1)magpie_expand_dim(x, ref, dim = 1)
x |
MAgPIE object that should be expanded |
ref |
MAgPIE object that serves as a reference |
dim |
dimension that should be expanded |
Expansion means here that the dimensions of x are expanded acordingly to ref. Please note that this is really only about expansion. In the case that one dimension of ref is smaller than of x nothing happens with this dimension. At the moment magpie_expand is only internally available in the magclass library
In contrast to magpie_expand this function is expanding only a single
dimension. It is meant as a support function for magpie_expand itself.
An expanded version of x.
Jan Philipp Dietrich
d <- new.magpie(c("AFR.BLUB.1", "AFR.BLUB.2", "EUR.BLUB.1", "AFR.BLA.1", "AFR.BLA.2", "EUR.BLA.1"), fill = 1) getSets(d)[1:3] <- c("reg", "b", "i") e <- new.magpie(c("BLA.AFR.A", "BLA.EUR.A", "BLUB.AFR.A", "BLUB.EUR.A", "BLA.AFR.B", "BLA.EUR.B", "BLUB.AFR.B", "BLUB.EUR.B"), fill = 2) getSets(e)[1:3] <- c("b", "reg", "a") magclass:::magpie_expand_dim(d, e, dim = 1)d <- new.magpie(c("AFR.BLUB.1", "AFR.BLUB.2", "EUR.BLUB.1", "AFR.BLA.1", "AFR.BLA.2", "EUR.BLA.1"), fill = 1) getSets(d)[1:3] <- c("reg", "b", "i") e <- new.magpie(c("BLA.AFR.A", "BLA.EUR.A", "BLUB.AFR.A", "BLUB.EUR.A", "BLA.AFR.B", "BLA.EUR.B", "BLUB.AFR.B", "BLUB.EUR.B"), fill = 2) getSets(e)[1:3] <- c("b", "reg", "a") magclass:::magpie_expand_dim(d, e, dim = 1)
The MAgPIE class is a data format for cellular MAgPIE data with a close
relationship to the array data format. is.magpie tests if x is
an MAgPIE-object, as.magpie transforms x to an MAgPIE-object
(if possible).
x |
An object that should be either tested or transformed as/to an MAgPIE-object. |
... |
additional arguments supplied for the conversion to a MAgPIE
object. Allowed arguments for arrays and dataframes are |
Objects can be created by calls of the form
new("magpie", data, dim, dimnames, ...). MAgPIE objects have three
dimensions (cells,years,datatype) and the dimensionnames of the first
dimension have the structure "REGION.cellnumber". MAgPIE-objects behave the
same like array-objects with 2 exceptions:
1.Dimensions of the object
will not collapse (e.g. x[1,1,1] will remain 3D instead of becoming
1D)
2.It is possible to extract full regions just by typing
x["REGIONNAME",,].
Please mind following standards:
Header must not contain any purely
numeric entries, but combinations of characters and numbers are allowed
(e.g. "bla","12" is forbidden, wheras "bla","b12" is allowed)
Years
always have the structure "y" + 4-digit number, e.g. "y1995"
Regions
always have the structure 3 capital letters, e.g. "AFR" or "GLO"
This
standards are necessary to allow the scripts to detect headers, years and
regions properly and to have a distinction to other data.
Jan Philipp Dietrich
read.magpie, write.magpie,
getRegions, getYears, getNames,
getCPR, ncells, nyears,
ndata
showClass("magpie") pop <- maxample("pop") # returning PAO and PAS for 2025 pop["PA", 2025, , pmatch = "left"] # returning CPA for 2025 pop["PA", 2025, , pmatch = "right"] # returning CPA PAO and PAS for 2025 pop["PA", 2025, , pmatch = TRUE] # returning PAS and 2025 pop["PAS", 2025, ] # return all entries for year 2025 pop[2025, dim = 2] # returning everything but values for PAS or values for 2025 pop["PAS", 2025, , invert = TRUE] # accessing subdimension via set name a <- maxample("animal") a[list(country = "NLD", y = "53p25"), , list(species = c("rabbit", "dog"))] # please note that the list elements act as filter. For instance, the # following example will not contain any dogs as the data set does # not contain any dogs which are black. a[list(country = "NLD", y = "53p25"), , list(species = c("rabbit", "dog"), color = "black")] # it is also possible to extract given combinations of subdimensions # via a data-frame df <- data.frame(getItems(a, 3, split = TRUE, full = TRUE))[c(1, 3, 4), ][3:2] getItems(a[df], 3) # Unknown dimensions to be added in output! df$blub <- paste0("bl", 1:dim(df)[1]) getItems(a[df], 3)showClass("magpie") pop <- maxample("pop") # returning PAO and PAS for 2025 pop["PA", 2025, , pmatch = "left"] # returning CPA for 2025 pop["PA", 2025, , pmatch = "right"] # returning CPA PAO and PAS for 2025 pop["PA", 2025, , pmatch = TRUE] # returning PAS and 2025 pop["PAS", 2025, ] # return all entries for year 2025 pop[2025, dim = 2] # returning everything but values for PAS or values for 2025 pop["PAS", 2025, , invert = TRUE] # accessing subdimension via set name a <- maxample("animal") a[list(country = "NLD", y = "53p25"), , list(species = c("rabbit", "dog"))] # please note that the list elements act as filter. For instance, the # following example will not contain any dogs as the data set does # not contain any dogs which are black. a[list(country = "NLD", y = "53p25"), , list(species = c("rabbit", "dog"), color = "black")] # it is also possible to extract given combinations of subdimensions # via a data-frame df <- data.frame(getItems(a, 3, split = TRUE, full = TRUE))[c(1, 3, 4), ][3:2] getItems(a[df], 3) # Unknown dimensions to be added in output! df$blub <- paste0("bl", 1:dim(df)[1]) getItems(a[df], 3)
Brings the spatial and temporal structure of MAgPIE objects in the right order. This function is especially useful when you create new MAgPIE objects as the order typically should be correct for MAgPIE objects.
magpiesort(x)magpiesort(x)
x |
MAgPIE object which might not be in the right order. |
The eventually corrected MAgPIE object (right order in spatial in temporal dimension)
Jan Philipp Dietrich
"magpie"
pop <- maxample("pop") a <- magpiesort(pop)pop <- maxample("pop") a <- magpiesort(pop)
apply command for magpieobjects. Very efficient for replacing loops.
magpply(X, FUN, MARGIN = NULL, DIM = NULL, ..., INTEGRATE = FALSE)magpply(X, FUN, MARGIN = NULL, DIM = NULL, ..., INTEGRATE = FALSE)
X |
magpie object |
FUN |
function that shall be applied X |
MARGIN |
dimension over which FUN shall be applied (like a loop over that dimension).
This dimension will be preserved in the output object (see also |
DIM |
dimension in which FUN shall be applied. This dimension will be missing in the output. DIM and MARGIN are opposite ways of expressing the dimensions to be addressed and you must only use one of them with MARGIN excluding dimensions from the calculation and DIM including them. |
... |
further parameters passed on to FUN |
INTEGRATE |
if TRUE, the output will be filled into an magpie object of the same dimensionality as X |
magpie object
Jan Philipp Dietrich, Benjamin Leon Bodirsky
pop <- maxample("pop") magpply(pop, FUN = sum, MARGIN = 2) fourdim <- pop * setNames(pop, c("jkk", "lk")) magpply(fourdim, FUN = sum, MARGIN = c(1, 3.1))pop <- maxample("pop") magpply(pop, FUN = sum, MARGIN = 2) fourdim <- pop * setNames(pop, c("jkk", "lk")) magpply(fourdim, FUN = sum, MARGIN = c(1, 3.1))
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.
matchDim(x, ref, dim = 1:3, fill = NA)matchDim(x, ref, dim = 1:3, fill = NA)
x |
A |
ref |
A |
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. |
fill |
Value to be set in new dimensions. |
The modified magpie object.
Falk Benke
A collection of magclass example data sets
maxample(data)maxample(data)
data |
name of the example data set. Currently available are "pop" (regional population data, previously named "population_magpie"), "animal" (fictional, high-dimensional animal sighting data set) and "bilateral" (fictional, bilateral trade cost data set). |
the chosen example data set
Jan Philipp Dietrich
p <- maxample("pop") str(p) a <- maxample("animal") str(a) getItems(a, split = TRUE)p <- maxample("pop") str(p) a <- maxample("animal") str(a) getItems(a, split = TRUE)
Merges MAgPIE-objects with identical structure in two dimensions. If data differs in the temporal or spatial dimension each year or region/cell must appear only once!
mbind(...)mbind(...)
... |
MAgPIE objects or a list of MAgPIE objects that should be merged. |
The merged MAgPIE object
Jan Philipp Dietrich, Misko Stevanovic
"magpie"
m <- new.magpie(c("AFR", "CPA", "EUR"), c(1995, 2005), "Data1", fill = c(1, 2, 3, 4, 5, 6)) ms <- dimSums(m, dim = 3.1) mbind(m, ms) my <- new.magpie(getRegions(m), 2010, getNames(m), fill = c(6, 6, 4)) mbind(m, my) md <- new.magpie(getRegions(m), getYears(m), "Data2", fill = c(7, 6, 5, 7, 8, 9)) mbind(m, md) pop <- maxample("pop") a <- mbind(pop, pop) dim(pop) dim(a)m <- new.magpie(c("AFR", "CPA", "EUR"), c(1995, 2005), "Data1", fill = c(1, 2, 3, 4, 5, 6)) ms <- dimSums(m, dim = 3.1) mbind(m, ms) my <- new.magpie(getRegions(m), 2010, getNames(m), fill = c(6, 6, 4)) mbind(m, my) md <- new.magpie(getRegions(m), getYears(m), "Data2", fill = c(7, 6, 5, 7, 8, 9)) mbind(m, md) pop <- maxample("pop") a <- mbind(pop, pop) dim(pop) dim(a)
Select values from a MAgPIE-object
mcalc(x, f, dim = NULL, append = FALSE)mcalc(x, f, dim = NULL, append = FALSE)
x |
MAgPIE object |
f |
A formula describing the calculation that should be performed |
dim |
The dimension in which the manipulation should take place. If set to NULL function tries to detect the dimension automatically. |
append |
If set to TRUE the result will be appended to x, otherwise the result will be returned. |
This functions only work for MAgPIE objects with named dimensions as the dimension name (set_name) has to be used to indicate in which dimension the entries should be searched for!
The calculated MAgPIE object in the case that append is set to FALSE. Otherwise nothing is returned (as x is appended in place)
Jan Philipp Dietrich
pop <- maxample("pop") pop mcalc(pop, X12 ~ A2 * B1, append = TRUE) pop mcalc(pop, `Nearly B1` ~ 0.5 * A2 + 99.5 * B1)pop <- maxample("pop") pop mcalc(pop, X12 ~ A2 * B1, append = TRUE) pop mcalc(pop, `Nearly B1` ~ 0.5 * A2 + 99.5 * B1)
Select values from a MAgPIE-object
mselect(x, ..., collapseNames = FALSE) mselect(x, ...) <- valuemselect(x, ..., collapseNames = FALSE) mselect(x, ...) <- value
x |
MAgPIE object |
... |
entry selections of the form
|
collapseNames |
Boolean which decides whether names should be collapsed or not. |
value |
values on which the selected magpie entries should be set. |
This functions only work for MAgPIE objects with named dimensions as the dimension name (set_name) has to be used to indicate in which dimension the entries should be searched for!
The reduced MAgPIE object containing only the selected entries or the full MAgPIE object in which a selection of entries was manipulated.
mselect(x, ...) <- value: replace values in magpie object
Jan Philipp Dietrich
pop <- maxample("pop") mselect(pop, i = c("AFR", "EUR"), scenario = "A2", t = "y2035")pop <- maxample("pop") mselect(pop, i = c("AFR", "EUR"), scenario = "A2", t = "y2035")
Functions to count the number of cells/years/datasets/regions of an MAgPIE-object
ncells(x) ndata(x) nregions(x) nyears(x)ncells(x) ndata(x) nregions(x) nyears(x)
x |
A MAgPIE-object |
value |
The number of cells/years/datasets/regions of |
ndata(): count datasets
nregions(): count regions
nyears(): count years
Jan Philipp Dietrich
a <- is.magpie(NULL) ncells(a) nyears(a) ndata(a) nregions(a)a <- is.magpie(NULL) ncells(a) nyears(a) ndata(a) nregions(a)
Functions to count the subdimensions of an MAgPIE-object
ndim(x, dim = NULL)ndim(x, dim = NULL)
x |
A MAgPIE-object |
dim |
main dimension in which the sub-dimensions should be counted. If NULL the sum of all subdimensions is returned |
Number of subdimensions
Jan Philipp Dietrich
a <- maxample("animal") ndim(a) ndim(a,1) ndim(a,2) ndim(a,3)a <- maxample("animal") ndim(a) ndim(a,1) ndim(a,2) ndim(a,3)
Creates a new MAgPIE object
new.magpie( cells_and_regions = "GLO", years = NULL, names = NULL, fill = NA, sort = FALSE, sets = NULL, unit = NULL )new.magpie( cells_and_regions = "GLO", years = NULL, names = NULL, fill = NA, sort = FALSE, sets = NULL, unit = NULL )
cells_and_regions |
Either the region names (e.g. "AFR"), or the cells (e.g. 1:10), or both in combination (e.g. "AFR.1"). NULL means no spatial element. |
years |
dimnames for years in the format "yXXXX" or as integers. NULL means one year which is not further specified |
names |
dimnames for names. NULL means one data element which is not further specified |
fill |
Default value for the MAgPIE object |
sort |
Bolean. Decides, wheher output should be sorted or not. |
sets |
A vector of dimension names. See |
unit |
deprecated |
an empty magpie object filled with fill, with the given dimnames
Benjamin Bodirsky, Jan Philipp Dietrich
a <- new.magpie(1:10, 1995:2000) b <- new.magpie(c("AFR", "CPA"), "y1995", c("bla", "blub"), sets = c("i", "t", "value")) c <- new.magpie()a <- new.magpie(1:10, 1995:2000) b <- new.magpie(c("AFR", "CPA"), "y1995", c("bla", "blub"), sets = c("i", "t", "value")) c <- new.magpie()
Example dataset for a regional MAgPIE object
A2 and B1 population scenario from SRES
Benjamin Bodirsky
print method for MAgPIE objects for conventient display of magpie data.
## S3 method for class 'magpie' print(x, drop = TRUE, reshape = FALSE, ...)## S3 method for class 'magpie' print(x, drop = TRUE, reshape = FALSE, ...)
x |
MAgPIE object |
drop |
argument which controls whether empty dimensions should be skipped or not. |
reshape |
argument that controls tabular representation of nested data dimension cross tables, FALSE will reproduce standard print behavior any pair of two dimension numbers will create a table for these two dims, and loop over the other dimensions |
... |
arguments to be passed to or from other methods. |
Invisibly, the MAgPIE object x.
Jan Philipp Dietrich, Kristine Karstens, Felicitas Beier
pop <- maxample("pop") print(pop) print(pop[, 1, ], drop = FALSE) print(pop[, 1, ])pop <- maxample("pop") print(pop) print(pop[, 1, ], drop = FALSE) print(pop[, 1, ])
Reads a MAgPIE-file and converts it to a 3D array of the structure (cells,years,datacolumn)
read.magpie( file_name, file_folder = "", file_type = NULL, as.array = FALSE, comment.char = "*", check.names = FALSE, ... )read.magpie( file_name, file_folder = "", file_type = NULL, as.array = FALSE, comment.char = "*", check.names = FALSE, ... )
file_name |
file name including file ending (wildcards are supported). Optionally also the full path can be specified here (instead of splitting it to file_name and file_folder) |
file_folder |
folder the file is located in (alternatively you can also specify the full path in file_name - wildcards are supported) |
file_type |
format the data is stored in. If file_type=NULL the file ending
of the file_name is used as format. If format is different to the formats
mentioned standard MAgPIE format is assumed. See |
as.array |
Should the input be transformed to an array? This can be useful for regional or global inputs, but all advantages of the magpie-class are lost. |
comment.char |
character: a character vector of length one containing a single character or an empty string. Use "" to turn off the interpretation of comments altogether. If a comment is found it will be stored in attr(,"comment"). In text files the comment has to be at the beginning of the file in order to be recognized by read.magpie. |
check.names |
logical. If TRUE then the names of the variables in the data frame are checked to ensure that they are syntactically valid variable names. Same functionality as in read.table. |
... |
additional arguments passed to specific read functions (e.g.
|
See write.magpie for a list of supported file formats.
x |
MAgPIE-object |
See write.magpie for the detailed structure of binary MAgPIE formats .m and .mz.
Jan Philipp Dietrich, Stephen Bi, Florian Humpenoeder, Pascal Sauer
This function reads the content of a reporting file (a file in the model intercomparison file format *.mif) into a list of MAgPIE objects or a single MAgPIE object.
read.report(file, as.list = TRUE, showSeparatorWarning = TRUE)read.report(file, as.list = TRUE, showSeparatorWarning = TRUE)
file |
file name the object should be read from. |
as.list |
if TRUE a list is returned (default), if FALSE it is tried to merge all information in one MAgPIE object (still under development and works currently only if the entries for the different models and scenarios have exactly the same regions and years). |
showSeparatorWarning |
Boolean (default value TRUE) that decides whether the warning about the replacement of dots in variable names is displayed (default value) or not. |
The Model Intercomparison File Format (MIF) is the default file format for data produced by Integrated Assessment Models. It is based on the common format used for Model Intercomparison Projects such as EMF and SSP with some slight changes/clarifications in its definition. For interactions between models this format should be used. For everything else it is at least recommended to use this format, too.
Aim of this standardization is to achieve a more flexible and smooth communication between models and to facilitate the creation of aggregated outputs from integrated assessment scenario runs which then can easily be uploaded to external databases such as the EMF or SSP database. By using this standard most of the required decisions for a working input output interface between models have already been specified which significantly reduces the required work to get a new interaction running.
Definition
The format is characterized by the following features:
The file ending is ".mif"
The file is written in ASCII format
Entries are separated with ";", every line ends with a ";"
The file always contains a header
The format of the header is: Model;Scenario;Region;Variable;Unit;<ADDITIONAL_COLUMNS>;<YEARS>;
The first 5 entries always have to exist, <ADDITIONAL_COLUMNS> is additional information which can be added optionally (e.g. "Description") and <YEARS> are the years for which data is delivered. <YEARS> are always written as 4 digit numbers. In the (very unlikely) case that a year before 1000 is used the number has to start with a 0, e.g. 0950. <ADDITIONAL_COLUMNS> can be anything, there are no further rules at the moment what it can contain. However, there are strict rules for naming these columns. Allowed are single names starting with a capital letter without special characters in it except "_" which is allowed. Examples: "Description" allowed, "More Description" not allowed, "More_Description" allowed, "123Description" not allowed, "Description123" allowed. Scripts using this format must be able to ignore additional columns. For years there are no specific limitations/requirements which years should be reported. Scripts dealing with this data must be able to work with different temporal resolutions. For variables basically everything can be reported here. Missing values have to be marked with "N/A".
Jan Philipp Dietrich
## Not run: read.report("report.csv") ## End(Not run)## Not run: read.report("report.csv") ## End(Not run)
Replaces all instances of non-finite data (NA, NaN, Inf, and -Inf).
replace_non_finite(x, replace = 0)replace_non_finite(x, replace = 0)
x |
A vector or |
replace |
A value to replace non-finite data with. |
A vector or magpie object, same as x.
Michaja Pehl
part <- new.magpie(letters[1:3], years = 'y1995', names = 'foo') total <- new.magpie(letters[1:3], years = 'y1995', names = 'foo') part[,,] <- c(0, 1, 2) total[,,] <- c(0, 10, 10) part / total replace_non_finite(part / total)part <- new.magpie(letters[1:3], years = 'y1995', names = 'foo') total <- new.magpie(letters[1:3], years = 'y1995', names = 'foo') part[,,] <- c(0, 1, 2) total[,,] <- c(0, 10, 10) part / total replace_non_finite(part / total)
Round-method for MAgPIE-objects respectively. Works exactly as for arrays.
## S4 method for signature 'magpie' round(x, digits = 0)## S4 method for signature 'magpie' round(x, digits = 0)
x |
a magpie object |
digits |
integer indicating the number of decimal places (round) or significant digits (signif) to be used. Negative values are allowed. |
works as round(x) for arrays.
~~ Methods for function rowSums and rowMeans~~
## S4 method for signature 'magpie' rowSums(x, na.rm = FALSE, dims = 1, ...)## S4 method for signature 'magpie' rowSums(x, na.rm = FALSE, dims = 1, ...)
x |
object on which calculation should be performed |
na.rm |
logical. Should missing values (including NaN) be omitted from the calculations? |
dims |
integer: Which dimensions are regarded as "rows" or "columns" to sum over. For row*, the sum or mean is over dimensions dims+1, ...; for col* it is over dimensions 1:dims. |
... |
further arguments passed to other colSums/colMeans methods |
normal rowSums and rowMeans method
classical method prepared to handle MAgPIE objects
Set items of a given (sub-)dimension of a MAgPIE-object
setItems(x, dim, value, maindim = NULL, raw = FALSE)setItems(x, dim, value, maindim = NULL, raw = FALSE)
x |
MAgPIE object |
dim |
Dimension for which the items should be returned. Either number or
name of dimension or a vector of these. See |
value |
a vector with the length of the main dimension the dimnames should be replaced in / added to. If set to NULL the corresponding dimension will be removed. |
maindim |
main dimension the data should be added to (does not need to be set if |
raw |
if set to FALSE inputs will be corrected (e.g. dots replaced by the letter "p") if necessary. If TRUE data will be written as is (risking the creation of inconsistent objects). |
the manipulated MAgPIE object
Jan Philipp Dietrich
x <- maxample("pop") setItems(x, "i", paste0("REG", 1:ncells(x)))x <- maxample("pop") setItems(x, "i", paste0("REG", 1:ncells(x)))
Extracts dataset names of a MAgPIE-object
## S4 method for signature 'magpie' setNames(object = nm, nm)## S4 method for signature 'magpie' setNames(object = nm, nm)
object |
MAgPIE object |
nm |
a vector of names current names should be replaced with. If only one data element exists you can also set the name to NULL. |
setNames is a shortcut to use a MAgPIE object with manipulated data names. The setNames method uses the variable names "object" and "nm" in order to be consistent to the already existing function setNames.
normal setNames method
setNames for MAgPIE objects
show ~~Show a magpie object by calling the default show method, print, or str, depending on options("magclass_show_func").
## S4 method for signature 'magpie' show(object)## S4 method for signature 'magpie' show(object)
object |
A MAgPIE-object |
Pascal Sauer
Calculates expected magclass object length and checks that it stays below
the limit defined with magclass_sizeLimit (default = 10^9). This is useful
to prevent out of memory errors in case of unwanted object expansions
Ignored if getOption("magclass_sizeLimit") is negative.
sizeCheck(dim)sizeCheck(dim)
dim |
dimensions of the current object as returned by function |
Jan Philipp Dietrich
pop <- maxample("pop") magclass:::sizeCheck(dim(pop)) ## Not run: magclass:::sizeCheck(c(6765L, 10946L, 17711L)) ## End(Not run)pop <- maxample("pop") magclass:::sizeCheck(dim(pop)) ## Not run: magclass:::sizeCheck(c(6765L, 10946L, 17711L)) ## End(Not run)
Convert a SpatRaster to a SpatRasterDataset.
spatRasterToDataset(x)spatRasterToDataset(x)
x |
SpatRaster with names of the form "y[0-9]+..[varname]" |
SpatRasterDataset
Pascal Sauer
str method for MAgPIE objects for conventient display of the structure of a magpie object.
## S3 method for class 'magpie' str(object, ...)## S3 method for class 'magpie' str(object, ...)
object |
MAgPIE object |
... |
arguments to be passed to or from other methods. |
In contrast to the default str this will not show the attributes of [email protected] as these contain only a duplicate of dimnames. Also, dim is not shown, because the information it provides is implicitly included in dimnames.
Pascal Sauer
str(maxample("pop"))str(maxample("pop"))
Like suppressWarnings, but instead of suppressing all warnings this only suppresses
warnings if they match the given pattern.
suppressSpecificWarnings(expr, regularExpr, fixed = FALSE)suppressSpecificWarnings(expr, regularExpr, fixed = FALSE)
expr |
The expression/code to evaluate, can be a block of code inside curly braces. |
regularExpr |
Only warnings matching this regular expression are suppressed. |
fixed |
Match the literal string given by regularExpr instead of interpreting it
as a regular expression. Passed to |
The result of evaluating expr.
Pascal Sauer
Function to extrapolate missing years in MAgPIE objects.
time_interpolate( dataset, interpolated_year, integrate_interpolated_years = FALSE, extrapolation_type = "linear" )time_interpolate( dataset, interpolated_year, integrate_interpolated_years = FALSE, extrapolation_type = "linear" )
dataset |
An MAgPIE object |
interpolated_year |
Vector of years, of which values are required. Can be in the formats 1999 or y1999. |
integrate_interpolated_years |
FALSE returns only the dataset of the interpolated year, TRUE returns the whole dataset, including all years of data and the itnerpolated year |
extrapolation_type |
Determines what happens if extrapolation is
required, i.e. if a requested year lies outside the range of years in
|
Uses linear extrapolation to estimate the values of the interpolated year, using the values of the two surrounding years. If the value is before or after the years in data, the two closest neighbours are used for extrapolation.
Benjamin Bodirsky, Jan Philipp Dietrich
p <- maxample("pop") time_interpolate(p, "y2000", integrate = TRUE) time_interpolate(p, c("y1980", "y2000"), integrate = TRUE, extrapolation_type = "constant")p <- maxample("pop") time_interpolate(p, "y2000", integrate = TRUE) time_interpolate(p, c("y1980", "y2000"), integrate = TRUE, extrapolation_type = "constant")
splits a data.frame or vector of strings with form 'variable (unit)' into a data.frame with variable and unit separated
unitsplit(x, col = "variable")unitsplit(x, col = "variable")
x |
data.frame or vector of strings |
col |
column name. Default: variable |
Jan Philipp Dietrich, Mika Pflüger, Oliver Richters
Creates a higher dimensional array by separating all subdimensions in the third dimension of a MAgPIE object and returning them as separate dimension.
unwrap(x, sep = NULL)unwrap(x, sep = NULL)
x |
A MAgPIE object |
sep |
deprecated, please do not use anymore |
An array with the full dimensionality of the original data
Jan Philipp Dietrich
a <- as.magpie(array(1:6, c(3, 2), list(c("bla", "blub", "ble"), c("up", "down")))) unwrap(a)a <- as.magpie(array(1:6, c(3, 2), list(c("bla", "blub", "ble"), c("up", "down")))) unwrap(a)
Analysis function for magpie objects
where(x, plot = NULL)where(x, plot = NULL)
x |
A logical statement with a magpie object |
plot |
deprecated. Use the function whereplot in package luplot. |
A list of analysis parameters
Benjamin Leon Bodirsky, Jan Philipp Dietrich
whereplot in package luplot
p <- maxample("pop") where(p > 500)p <- maxample("pop") where(p > 500)
Reshape an array or a matrix by permuting and/or joining dimensions.
wrap(x, map = list(NA), sep = ".")wrap(x, map = list(NA), sep = ".")
x |
An array |
map |
A list of length equal to the number of dimensions in the reshaped array. Each element should be an integer vectors specifying the dimensions to be joined in corresponding new dimension. One element may equal NA to indicate that that dimension should be a join of all non-specified (remaining) dimensions. Default is to wrap everything into a vector. |
sep |
A character separating joined dimension names |
This function is extracted from the R.utils library which is licensed under LGPL>=2.1 and written by Henrik Bengtsson.
Henrik Bengtsson, Jan Philipp Dietrich
Writes a magpie object to a file. The file type is determined by the filename extension.
The written file can be read again using read.magpie.
write.magpie( x, file_name, file_folder = "", file_type = NULL, append = FALSE, comment = NULL, comment.char = "*", mode = NULL, zname = "time", ... )write.magpie( x, file_name, file_folder = "", file_type = NULL, append = FALSE, comment = NULL, comment.char = "*", mode = NULL, zname = "time", ... )
x |
a magclass object. An exception is that formats written via the raster package (currently "asc", "grd" and "tif") also accept RasterBrick objects which have been previously created from a magclass object via as.RasterBrick) |
file_name |
file name including file ending (wildcards are supported). Optionally also the full path can be specified here (instead of splitting it to file_name and file_folder) |
file_folder |
folder the file should be written to (alternatively you can also specify the full path in file_name - wildcards are supported) |
file_type |
Format the data should be stored as. If file_type=NULL the file ending of the file_name is used as format. See detailed description for a list of available file types. Please be aware that the file_name is independent of the file_type you choose here, so no additional file ending will be added! |
append |
Decides whether an existing file should be overwritten (FALSE) or the data should be added to it (TRUE). Append = TRUE only works if the existing data can be combined with the new data using the mbind function |
comment |
Vector of strings: Optional comment giving additional information about the data. If different to NULL this will overwrite the content of attr(x,"comment"). For nc files the unit can be passed with e.g. 'comment = "unit: kg"'. |
comment.char |
character: a character vector of length one containing a single character or an empty string. Use "" to turn off the interpretation of comments altogether. |
mode |
File permissions the file should be written with as 3-digit number (e.g. "777" means full access for user, group and all, "750" means full access for user, read access for group and no acess for anybody else). Set to NULL system defaults will be used. Access codes are identical to the codes used in unix function chmod. |
zname |
name of the time variable for raster files like nc, asc, grd and tif |
... |
additional arguments passed to specific write functions. Check ?magclass::writeNC for available arguments when writing nc files. |
This function supports writing the following file types:
"cs2" is the new standard format for cellular data with or without header and the first columns (year,regiospatial) or only (regiospatial)
"cs2b" is identical to "cs2" except that it will suppress the data name if it has only 1 element in the data dimension.
"csv" is the standard format for regional data with or without header and the first columns (year,region,cellnumber) or only (region,cellnumber)
"cs3" is another csv format which is specifically designed for multidimensional data for usage in GAMS.
"cs4" alternative multidimensional format compatible to GAMS, in contrast to cs3 it can also handle sparse data
"csvr", "cs2r", "cs3r", "cs4r" which are the same formats as the ones previously explained with the only difference that they have a REMIND compatible format
"cs5" a more generalized version of cs4
"rds" is an R-default format for storing R objects
"m" (magpie) and "mz" (magpie zipped) are new formats developed to allow a less storage intensive management of MAgPIE-data. The only difference between both formats is that .mz is gzipped whereas .m is not compressed. So .mz needs less memory, whereas .m might have a higher compatibility to other languages
"asc" is the ASCII grid format. It can only be applied for gridded data and writes one file per year per data column. In the case that more than one year and data column is supplied several files are written with the structure filename_year_datacolumn.asc
"tif" is the GEOtiff format for gridded data.
"grd" is the native raster format for gridded data.
"nc" is the netCDF format for gridded data. Check ?magclass::writeNC for more details on how nc files are written.
The binary MAgPIE formats .m and .mz have the following content/structure
(you only have to care for that if you want to implement
read.magpie/write.magpie functions in other languages):
[ FileFormatVersion | Current file format version number (currently 6) | integer | 2 Byte ]
[ nchar_comment | Number of character bytes of the file comment | integer | 4 Byte ]
[ nbyte_metadata | Number of bytes of the serialized metadata (currently = 0) | integer | 4 Byte ]
[ nchar_sets | Number of characters bytes of all regionnames + 2 delimiter | integer | 2 Byte]
[ nyears | Number of years | integer | 2 Byte ]
[ yearList | All years of the dataset (0, if year is not present) | integer | 2*nyears Byte ]
[ ncells | Number of cells | integer | 4 Byte ]
[ nchar_cell | Number of characters bytes of all regionnames + (nreg-1) for delimiters | integer | 4 Byte ]
[ cells | Cell names saved as cell1\cell2 (\n is the delimiter) | character | 1*nchar_cell Byte ]
[ nelem | Total number of data elements | integer | 4 Byte ]
[ nchar_data | Number of char. bytes of all datanames + (ndata - 1) for delimiters | integer | 4 Byte ]
[ datanames | Names saved in the format data1\ndata2 (\n as del.) | character | 1*nchar_data Byte ]
[ data | Data of the MAgPIE array in vectorized form | numeric | 4*nelem Byte ]
[ comment | Comment with additional information about the data | character | 1*nchar_comment Byte ]
[ sets | Set names with \n as delimiter | character | 1*nchar_sets Byte]
[ metadata | serialized metadata information (currently not in use) | bytes | 1*nbyte_metadata Byte]
Jan Philipp Dietrich, Stephen Bi, Florian Humpenoeder, Pascal Sauer
pop <- maxample("pop") path <- tempfile(fileext = ".mz") write.magpie(pop, path) pop2 <- read.magpie(path)pop <- maxample("pop") path <- tempfile(fileext = ".mz") write.magpie(pop, path) pop2 <- read.magpie(path)
This function writes the content of a MAgPIE object into a file or returns it directly using the reporting format as it is used for many model inter-comparisons.
write.report( x, file = NULL, model = NULL, scenario = NULL, unit = NULL, ndigit = 4, append = FALSE, skipempty = TRUE, extracols = NULL )write.report( x, file = NULL, model = NULL, scenario = NULL, unit = NULL, ndigit = 4, append = FALSE, skipempty = TRUE, extracols = NULL )
x |
MAgPIE object or a list of lists with MAgPIE objects as created by read.report. In the latter case settings for model and scenario are overwritten by the information given in the list. |
file |
file name the object should be written to. If NULL the formatted content is returned |
model |
Name of the model which calculated the results |
scenario |
The scenario which was used to get that results. |
unit |
Unit of the data. Only relevant if unit is not already supplied in Dimnames (format "name (unit)"). Can be either a single string or a vector of strings with a length equal to the number of different data elements in the MAgPIE object |
ndigit |
Number of digits the output should have |
append |
Logical which decides whether data should be added to an existing file or an existing file should be overwritten |
skipempty |
Determines whether empty entries (all data NA) should be written to file or not. |
extracols |
names of dimensions which should appear in the output as additional columns |
Jan Philipp Dietrich
write.report(maxample("pop"))write.report(maxample("pop"))
This function is deprecated, please use write.report instead.
write.report2(...)write.report2(...)
... |
arguments are forwarded to |
Jan Philipp Dietrich
Write a magpie object to a netCDF file
writeNC( x, filename, unit, ..., compression = 2, missval = NA, gridDefinition = NULL, zname = "time", progress = FALSE )writeNC( x, filename, unit, ..., compression = 2, missval = NA, gridDefinition = NULL, zname = "time", progress = FALSE )
x |
A magpie object |
filename |
Name of the netCDF file to write |
unit |
Unit of the data, to omit pass "" (empty string) |
... |
For future expansion |
compression |
Level of compression to use (1-9), NA for no compression |
missval |
The value that encodes NA in the resulting netCDF file |
gridDefinition |
A vector of 5 numeric values: c(xMin, xMax, yMin, yMax, resolution). Use c(-179.75, 179.75, -89.75, 89.75, 0.5) to write a standard 0.5-degree-resolution lon/lat grid. If NULL, use min/max of coordinates in x and guessResolution |
zname |
Name of the z dimension in the netCDF file |
progress |
If TRUE, print progress messages |
Pascal Sauer