adjustCommodityTree: Adjust Commodity Tree

In SWS-Methodology/faoswsStandardization: Package to perform standardization of SUA (supply utilization account) data to FBS level

Description

This function takes a set of commodity trees (typically all countries for one year) and adjusts the extraction rates. The rationale is that previous extraction rates were manually adjusted, sometimes to extreme values. Thus, we need a consistent way to modify those rates, and the logic for adjusting those rates is contained in this function.

Usage

adjustCommodityTree(commodityTree, parentColname = "measuredItemParentFS",
  childColname = "measuredItemChildFS",
  extractionColname = "extractionRate", shareColname = "share",
  byKey = NULL, nSigma)

Arguments

commodityTree	A data.table containing the edge structure of the commodity tree (specified by parent/child columns) and the extraction rates and shares. Typically, this is produced from getOldCommodityTree.
parentColname	The column name of commodityTree which contains the ID for the parent commodity.
childColname	The column name of commodityTree which contains the ID for the child commodity.
extractionColname	The column name of commodityTree which contains the extraction rates. Extraction rates represent the quantity of the child that can be produced from 1 unit of the parent. Typically, though, they are expressed in 10,000's: i.e. if the extraction rate is 8000, 1 parent unit can be processed into 1 * 8000/10000 = 0.8 child units.
shareColname	The column name of commodityTree which contains the shares variable. This value represents the percent of the parent commodity that is processed into the child. For example, a share value of 50 means that 300 units of the parent would be processed into 300*50/100 = 150 units of the child.
byKey	A character vector of column names of commodityTree. We group extraction rates based on averages across groups. The byKey argument provides the column names which should be used as grouping variables for estimating this mean. Note that parentColname and childColname are always used as grouping variables, as extraction rates are specific to edges. This defaults to NULL, in which case all values (for the same edge) are averaged.
nSigma	The number of standard deviations away from the mean that is deemed acceptable. Any extraction rates outside of this range will be updated based on the estimated mean and standard error. The new extraction rate value will be based on the quantile of the original value. If the original value was the largest value in a group of N extraction rates, then the new value will be the (N-0.5)/N*100 percentile of a normal distribution with mean and variance estimated from the data. If all data should be mapped to the corresponding normal quantile, set nSigma = 0. To just adjust extreme values, set nSigma to something like 2 or 3. Note: this mapping may not preserve the original ordering, and it is only guaranteed to do so if nSigma = 0 (all adjusted) or nSigma = Inf (none adjusted).

Value

This function returns an object that is the same as the input commodityTree except that extreme extraction rates have been adjusted.

SWS-Methodology/faoswsStandardization documentation built on Feb. 7, 2022, 5:05 a.m.