toolCubicFunctionDisaggregate: toolCubicFunctionDisaggregate

In pik-piam/mrremind: MadRat REMIND Input Data Package

toolCubicFunctionDisaggregate

Description

Estimates cubic function inverses based on a weight factor that sum up to the original cubic function (sum in the x-axis)

Usage

toolCubicFunctionDisaggregate(
  x,
  weight,
  rel = NULL,
  xLowerBound = 0,
  xUpperBound = 100,
  returnMagpie = TRUE,
  returnCoeff = TRUE,
  returnChart = FALSE,
  returnSample = FALSE,
  numberOfSamples = 1000,
  unirootLowerBound = -10,
  unirootUpperBound = 1e+100,
  colourPallete = FALSE,
  label = list(x = "x", y = "y", legend = "legend")
)

Arguments

x	magclass object that should be aggregated or data frame with coefficients as columns.
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).
rel	relation matrix containing a region 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
xLowerBound	numeric. Lower bound for x sampling (default=0).
xUpperBound	numeric. Upper bound for x sampling (default=100).
returnMagpie	boolean. if true, the function will return a single data table with all the countries in MagPie format. returnChart and returnSample are set to FALSE automatically if this option is active (default=TRUE).
returnCoeff	boolean. Return estimated coefficients (default=TRUE).
returnChart	boolean. Return chart (default=FALSE).
returnSample	boolean. Return samples used on estimation (default=FALSE).
numberOfSamples	numeric. NUmber of y-axis samples used on estimation (default=1e3).
unirootLowerBound	numeric. Lower bound to search for inverse solution in the initial bounds (default = -10).
unirootUpperBound	numeric. Upper bound to search for inverse solution in the initial bounds (default = 1e100).
colourPallete	vector. colour pallete to use on chart (default=FALSE).
label	list. List of chart labels (default=list(x = "x", y = "y", legend = "legend")).

Details

Use case: disaggregate a single region cubic cost function to multiple country cubic functions weighted by a contribution factor. The sum of the countries function output is equal to the original regional function.

input: coefficients of the n-th country level cubic cost function.

Description of the problem: the disaggregation of functions that represent unit costs (or prices) in the y-axis and quantities in the x-axis require operations with the inverse of the original functions. As complex functions present analytically challenging inverse function derivations, we adopt a sampling method to derive the function that corresponds to the sum of cubic function inverses.

Further extensions: the R function can be extended to support more complex curve estimations (beyond third degree), whenever the mathematical function have a well defined inverse function in the selected boundaries.

Value

return: returns a list of magpie objects containing the coefficients for the aggregate function. If returnMagpie is FALSE, returns a list containing the coefficients for the aggregate function (returnCoeff=TRUE), charts (returnChart=FALSE) and/or samples used in the estimation (returnSample=FALSE).

Author(s)

Renato Rodrigues

See Also

toolCubicFunctionAggregate

Examples

# Example
# LAM coefficients
df <- setNames(data.frame(30,50,0.34369,2),c("c1","c2","c3","c4"))
row.names(df) <- "LAM"
# weight
weight <- setNames(c(21,0,579,3,228),c("ARG","BOL","BRA","CHL","COL"))
# maxExtraction (upper limit for function estimation)
maxExtraction <- 100
# output
output <- toolCubicFunctionDisaggregate(df, weight,xUpperBound=maxExtraction,
 returnMagpie=FALSE,returnChart=TRUE,returnSample=TRUE,
 label=list(x="Cumulated Extraction", y="Cost", legend="Region Fuel Functions"))#' output$chart
output$coeff
output$chart

pik-piam/mrremind documentation built on March 30, 2024, 3:37 a.m.