standardizationWrapper: FULL STANDARDIZATION PROCESS

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

Description

This function implements the new standardization process. The algorithm is as follows:

This function implements the new standardization process. The algorithm is as follows:

Usage

standardizationWrapper(data, tree, fbsTree = NULL, standParams,
  nutrientData = NULL, printCodes = c(), debugFile = NULL,
  batchnumber = batchnumber, utilizationTable = utilizationTable,
  cutItems = cutItems)

standardizationWrapper(data, tree, fbsTree = NULL, standParams,
  nutrientData = NULL, printCodes = c(), debugFile = NULL,
  batchnumber = batchnumber, utilizationTable = utilizationTable,
  cutItems = cutItems)

Arguments

data	The data.table containing the full dataset for standardization. It should have columns corresponding to year, country, element, commodity, and value. The specific names of these columns should be in standParams.
tree	The commodity tree which details how elements can be processed into other elements. It does not, however, specify which elements get aggregated into others. This data.table should have columns parent, child, extraction rate, share, and target (target specifying if an element is processed forward or not). Names of these columns should be provided in standParams.
fbsTree	This "tree" should just have three columns: standParams$parentID, standParams$childID, and standParams$extractVar (which if missing will just be assigned all values of 1). This tree specifies how SUA commodities get combined to form the FBS aggregates. If NULL, the last step (aggregation to FBS codes) is skipped and data is simply returned at SUA level.
standParams	The parameters for standardization. These parameters provide information about the columns of data and tree, specifying (for example) which columns should be standardized, which columns represent parents/children, etc.
nutrientData	A data.table containing one column with the item codes (and this column's name must match standParams$itemVar) and additional columns representing nutrient information. For example, you could have 4 columns: measuredItemCPC, calories, proteins, fats. In the calories, proteins, and fats columns there should be numeric values representing multipliers to convert kilograms of the item into calories/proteins/fats. If NULL, nothing is done with nutrients.
printCodes	A list of the item codes which should be printed at each step to show the progress of the algorithm.
debugFile	folder for saving the intermediate files.
batchnumber	Number of batch running.
utilizationTable	Table of utilization for suaFilling
cutItems	tree's cuts
data	The data.table containing the full dataset for standardization. It should have columns corresponding to year, country, element, commodity, and value. The specific names of these columns should be in standParams.
tree	The commodity tree which details how elements can be processed into other elements. It does not, however, specify which elements get aggregated into others. This data.table should have columns parent, child, extraction rate, share, and target (target specifying if an element is processed forward or not). Names of these columns should be provided in standParams.
fbsTree	This "tree" should just have three columns: standParams$parentID, standParams$childID, and standParams$extractVar (which if missing will just be assigned all values of 1). This tree specifies how SUA commodities get combined to form the FBS aggregates. If NULL, the last step (aggregation to FBS codes) is skipped and data is simply returned at SUA level.
standParams	The parameters for standardization. These parameters provide information about the columns of data and tree, specifying (for example) which columns should be standardized, which columns represent parents/children, etc.
nutrientData	A data.table containing one column with the item codes (and this column's name must match standParams$itemVar) and additional columns representing nutrient information. For example, you could have 4 columns: measuredItemCPC, calories, proteins, fats. In the calories, proteins, and fats columns there should be numeric values representing multipliers to convert kilograms of the item into calories/proteins/fats. If NULL, nothing is done with nutrients.
printCodes	A list of the item codes which should be printed at each step to show the progress of the algorithm.
debugFile	folder for saving the intermediate files.
batchnumber	Number of batch running.
utilizationTable	Table of utilization for suaFilling
cutItems	tree's cuts

Details

1. Any edges with a target of "F" should be immediately "processed forward". This amounts to computing the residual and allocating it to food processing, and, hence, to production of the children of this node.

2. Balance the processed products in the SUA by creating production of processed products. If a node is set to be processed forward, then it is also balanced via a residual (i.e. food processing).

2.1 Since food quantities are now available, we can compute initial calorie estimates.

3. Availability at the "balancing level" (usually primary level, but possibly lower if a node is processed forward or standardized in a different tree) is determined. Note that at this point, all edges designated with an "F" (i.e. forward) will have been removed, and so "balancing level" is the same as the top node of the tree. This availability defines shares for standardization. If no availability of parents is available, the initial shares are used (in tree[, get(standParams$shareVar)]).

4. Standardize commodities according to the commodity tree. This defines the food processing element at balancing level.

5. Balance at the balancing level.

6. Update calories of processed products proportionally based on updated food element values.

7. (only if fbsTree is provided) Sum all commodities up to their FBS level categories. This is the final step to prepare data for FAOSTAT.

1. Any edges with a target of "F" should be immediately "processed forward". This amounts to computing the residual and allocating it to food processing, and, hence, to production of the children of this node.

2. Balance the processed products in the SUA by creating production of processed products. If a node is set to be processed forward, then it is also balanced via a residual (i.e. food processing).

2.1 Since food quantities are now available, we can compute initial calorie estimates.

3. Availability at the "balancing level" (usually primary level, but possibly lower if a node is processed forward or standardized in a different tree) is determined. Note that at this point, all edges designated with an "F" (i.e. forward) will have been removed, and so "balancing level" is the same as the top node of the tree. This availability defines shares for standardization. If no availability of parents is available, the initial shares are used (in tree[, get(standParams$shareVar)]).

4. Standardize commodities according to the commodity tree. This defines the food processing element at balancing level.

5. Balance at the balancing level.

6. Update calories of processed products proportionally based on updated food element values.

7. (only if fbsTree is provided) Sum all commodities up to their FBS level categories. This is the final step to prepare data for FAOSTAT.

Value

A data.table containing the final balanced and standardized SUA data. Additionally, this table will have new elements in it if nutrientData was provided.

A data.table containing the final balanced and standardized SUA data. Additionally, this table will have new elements in it if nutrientData was provided.

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