Package 'mstools'

mstools: Tool functions that can be used by several madrat-dependent or magpie4 output functions

Description

Tool functions that can be used by several madrat-dependent or magpie4 output functions.

Author(s)

Maintainer: Benjamin Leon Bodirsky [email protected]

Authors:

• Kristine Karstens

• Felicitas Beier

• Jan Philipp Dietrich [email protected]

See Also

Useful links:

• https://github.com/pik-piam/magpie4

• doi:10.5281/zenodo.1158582

• Report bugs at https://github.com/pik-piam/magpie4/issues

---

toolAggregateCell2Country

Description

Aggregate cellular data (with coordinate information) to countries and perform consistency checks

Usage

toolAggregateCell2Country(x, weight = NULL, ...)

Arguments

x	cellular magpie object with coordinates
weight	aggregation weight
...	additional options forwarded to 'toolCountryFill'

Value

return country ISO level data

Author(s)

Jan Philipp Dietrich

---

toolCell2isoCell

Description

Sets cell names to "iso country code"."cell number"

Usage

toolCell2isoCell(x, cells = "magpiecell")

Arguments

x	magpie object on cellular level
cells	switch between magpie cells (59199) and lpj cells (67420)

Value

return changed input data

Author(s)

Kristine Karstens

---

toolConv2CountryByCelltype

Description

Aggregates cellular data to ISO country level after conversion of cellular data to a specific cell setup (this type is relevant as some settings, such as "magpiecell" remove some cells and therby affect country sums)

Usage

toolConv2CountryByCelltype(x, cells)

Arguments

x	magpie object on cellular level
cells	switch between 59199 ("magpiecell") and 67420 ("lpjcell") cells

Value

return selected input data on ISO country level

Author(s)

Jan Philipp Dietrich

---

toolCoord2Isocell

Description

Transforms an object with coordinate spatial data (on half-degree) to isocell (59199) standard

Usage

toolCoord2Isocell(
  x,
  cells = "magpiecell",
  fillMissing = NULL,
  warnMissing = TRUE
)

Arguments

x	Object to be transformed from coordinates to (old) magpie isocell standard
cells	Switch between "magpiecell" (59199) and "lpjcell" (67420)
fillMissing	if NULL cells missing from the total 59199 are just being ignore. If set to a value missing cells will be added with this value (e.g. all set to 0 if fillMissing is 0)
warnMissing	Switch which controls whether missing cells should trigger a warning or not

Value

magpie object with 59199 cells in isocell naming

Author(s)

Kristine Karstens, Felicitas Beier, Jan Philipp Dietrich

---

toolCoord2Isocoord

Description

Transforms an object with coordinate spatial data (on half-degree) to object with 67420 cells and coordinate and iso country information

Usage

toolCoord2Isocoord(x)

Arguments

x	magclass object to be transformed from coordinates to iso-coordinate

Value

magpie object with 67420 cells in x.y.iso naming

Author(s)

Felicitas Beier, Michael Crawford

---

toolCountryFillBilateral

Description

Fills bilateral iso-level magpie objects to 249 x 249 countries

Usage

toolCountryFillBilateral(x, fill = NA)

Arguments

x	input variable, a bilateral magclass object
fill	fill value, default NA

---

toolExpectLessDiff

Description

tool function for status reporting. It performs a difference check between two objects and returns either a message via toolStatusMessage, that the test was successful or that it failed.

Usage

toolExpectLessDiff(x, y, maxdiff, description, level = 0, maxdiff2 = NULL)

Arguments

x	object 1
y	object 2 which has the same format as object 1
maxdiff	allowed maximum difference per element between x and y.
description	a description of the check
level	as the test result will be linked to a function call, the function needs to know to which call it should be linked. by default (level = 0) the parent function call is being used. Increasing the number by one will let the function go up by one in the call stack, level = -1 will use toolExpectTrue itself as function call.
maxdiff2	optional additional threshold. If set it will serve as a second, critial threshold which will throw a warning (instead of a simple note in case of maxdiff) if being surpassed.

Author(s)

Jan Philipp Dietrich

See Also

getMadratMessage, toolExpectTrue, toolStatusMessage

Examples

toolExpectLessDiff(1:3, 2:4, 10, "data is sufficiently close", level = -1)
getMadratMessage("status")

---

toolExpectTrue

Description

tool function for status reporting. It performs a logical check and returns either a message via toolStatusMessage, that the test was successful or that it failed.

Usage

toolExpectTrue(check, description, level = 0, falseStatus = "note")

Arguments

check	logical check to be run (has to be either TRUE or FALSE)
description	a description of the check
level	as the test result will be linked to a function call, the function needs to know to which call it should be linked. by default (level = 0) the parent function call is being used. Increasing the number by one will let the function go up by one in the call stack, level = -1 will use toolExpectTrue itself as function call.
falseStatus	the type of status that is used when the check fails (typically "note" for a simple message or "warn" for a warning).

Author(s)

Jan Philipp Dietrich

See Also

getMadratMessage, toolExpectLessDiff, toolStatusMessage, toolWriteMadratLog

Examples

toolExpectTrue(is.numeric(1), "data is numeric", level = -1)
getMadratMessage("status")

---

toolFertilizerDistribution

Description

Disaggregates fertilizer usage, trying to best match a certain soil nitrogen uptake efficiency (SNUpE). Also used in magpie4 library

Usage

toolFertilizerDistribution(
  iteration_max = 50,
  max_snupe = 0.85,
  mapping,
  from,
  to,
  fertilizer,
  SNUpE,
  withdrawals,
  organicinputs,
  threshold = 0.5
)

Arguments

iteration_max	maximum iteration for downscaling
max_snupe	the maximum level of nue or snupe
mapping	mapping used for disaggregation
from	name of from column in mapping
to	name of to column in mapping
fertilizer	total inorganic fertilizer to be distributed on regional leve
SNUpE	Nitrogen use efficiency or SNUPE on regional level which should be matched best possible
withdrawals	nitrogen withdrawals on cell level
organicinputs	non-inroganic fertilizer inputs on cell level
threshold	threshold in Tg Nr until when the distribution counts as converged

Value

magpie object with fertilizer usage on cell level

Author(s)

Benjamin Leon Bodirsky

---

toolFreezeEffect

Description

This function freeze values given a specific year and optionally additionally at the first non-zero value

Usage

toolFreezeEffect(x, year, constrain = FALSE)

Arguments

x	data set to freeze
year	year to hold constant (onwards)
constrain	if FALSE, no constrain. Other options: 'first_use' (freeze from 'first use' ( <=> !=0 ))

Value

magpie object with global parameters

Author(s)

Kristine Karstens

---

toolGetMappingCoord2Country

Description

loads mapping of cellular coordinate data (67420 halfdegree cells) to country iso codes

Usage

toolGetMappingCoord2Country(pretty = FALSE, extended = FALSE)

Arguments

pretty	If TRUE, coordinate data is returned as numeric 'lon' and 'lat' columns
extended	If TRUE, additional cells missing in the original 67420 data set will be returned as well.

Value

data frame of mapping

Author(s)

Felicitas Beier, Kristine Karstens

---

toolHarmonize2Baseline

Description

toolHarmonize2Baseline

Usage

toolHarmonize2Baseline(
  x,
  base,
  ref_year = "y2015",
  method = "limited",
  hard_cut = FALSE
)

Arguments

x	magclass object that should be set on baseline
base	magclass object for baseline
ref_year	Reference year
method	additive: x is harmonized to base by additive factor multiplicative: x is harmonized to base by multiplicative factor limited: multiplicative harmonization, but for an underestimated baseline the signal is limited to the additive term rather than the multiplicative factor
hard_cut	Switch to TRUE for data that can not be harmonized, but have to be glued together

Value

the averaged data in magclass format

Author(s)

Kristine Karstens, Felicitas Beier

---

toolHoldConstant

Description

Holds a historical dataset constant for the entire period years.

Usage

toolHoldConstant(x, years)

Arguments

x	MAgPIE object to be continued.
years	years for which the data should exist (hold constant, if missing)

Value

MAgPIE object with completed time dimensionality.

Author(s)

Benjamin Leon Bodirsky, Jan Philipp Dietrich

---

toolHoldConstantBeyondEnd

Description

Holds a historical dataset constant for the entire simulation period "time".

Usage

toolHoldConstantBeyondEnd(x)

Arguments

x	MAgPIE object to be continued.

Value

MAgPIE object with completed time dimensionality.

Author(s)

Benjamin Leon Bodirsky

---

toolIso2CellCountries

Description

Select country names of countries which are present on cellular level

Usage

toolIso2CellCountries(x, cells = "magpiecell", absolute = NULL)

Arguments

x	magpie object on iso country level
cells	switch between 59199 ("magpiecell") and 67420 ("lpjcell") cells
absolute	switch declaring the values as absolute (TRUE) or relative (FALSE) for additional (type-specific) diagnostic information. If not defined (NULL) additional diagnostics will not be shown.

Value

return selected input data

Author(s)

Kristine Karstens, Felicitas Beier, Jan Philipp Dietrich

---

toolIsocode2Country

Description

Translate iso country code to country names

Usage

toolIsocode2Country(x)

Arguments

x	Array of iso country codes

Value

return array of country names

Author(s)

Kristine Karstens

---

toolSmooth

Description

Smooth a time series using a given method and its default settings

Usage

toolSmooth(x, method = "spline")

Arguments

x	magclass object that should be smoothed
method	spline, average or more (See default argument for current default setting)

Value

smoothed data in magclass format

Author(s)

Kristine Karstens

---

toolStatusMessage

Description

tool to trigger status messages describing the data quality at different stages of processing. Messages are directly written to the log at execution but also collected to be finally returned as data report.

Usage

toolStatusMessage(status, message, level = 0)

Arguments

status	status indicator of the messages. Currently either "ok" (check succesful / quality ok), "note" (check unsuccessful but still acceptable) or "warn" (check unsuccessful / undesired result).
message	message to be triggered.
level	as the test result will be linked to a function call, the function needs to know to which call it should be linked. by default (level = 0) the parent function call is being used. Increasing the number by one will let the function go up by one in the call stack, level = -1 will use toolExpectTrue itself as function call.

Author(s)

Jan Philipp Dietrich

See Also

getMadratMessage, toolExpectLessDiff, toolStatusMessage

Examples

toolStatusMessage("ok", "everything is ok", level = -1)
toolStatusMessage("note", "this is not optimal but probably acceptable", level = -1)
toolStatusMessage("warn", "this is not ok", level = -1)
getMadratMessage("status")

---

toolSum2Country

Description

Efficient method to sum cellular data with country dimension as first sub-dimension to country level

Usage

toolSum2Country(x)

Arguments

x	magpie object on cellular level with countries in dim 1.1

Value

return selected input data on ISO country level

Author(s)

Jan Philipp Dietrich

---

toolWriteMadratLog

Description

Tool function for writing madrat messages to a log file. Useful after running madrat calculations which are performing checks via toolExpectTrue or other toolExpect functions.

Usage

toolWriteMadratLog(
  checkResults = getMadratMessage("status"),
  logPath = "status.log"
)

Arguments

checkResults	list of check results as returned by getMadratMessage
logPath	path to the log file to be written

Author(s)

Pascal Sauer

---