@hestia-earth/aggregation-engine 0.22.1 → 0.22.3

package/cjs/formulas.d.ts

@@ -49,6 +49,16 @@ export interface IFormula {
      * The KaTeX source (without the `$$` delimiters).
      */
     formula: string;
+    /**
+     * The heading the formula is documented under, e.g. `Completeness`. Names what the formula
+     * is for, so several formulas shown together can be told apart.
+     */
+    section?: string;
+    /**
+     * The sentence that introduces the formula in the documentation. Shown above it, so a reader
+     * who never opens the guide still knows what it calculates and how it relates to the others.
+     */
+    context?: string;
     /**
      * The symbols in the formula, in "Where:" list order.
      */

package/esm/formulas.d.ts

@@ -49,6 +49,16 @@ export interface IFormula {
      * The KaTeX source (without the `$$` delimiters).
      */
     formula: string;
+    /**
+     * The heading the formula is documented under, e.g. `Completeness`. Names what the formula
+     * is for, so several formulas shown together can be told apart.
+     */
+    section?: string;
+    /**
+     * The sentence that introduces the formula in the documentation. Shown above it, so a reader
+     * who never opens the guide still knows what it calculates and how it relates to the others.
+     */
+    context?: string;
     /**
      * The symbols in the formula, in "Where:" list order.
      */

package/formulas/index.json

@@ -1,10 +1,12 @@
 {
   "hestia_earth/aggregation/docs/crop.md": [
     {
-      "formula": "w = O \\times I",
+      "formula": "w_s = O \\times I",
+      "section": "Aggregation stages",
+      "context": "Each sub-aggregation's weight is the product of its organic share and its irrigation share.",
       "bindings": [
         {
-          "symbol": "w",
+          "symbol": "w_s",
           "description": "the weight of the sub-aggregation",
           "key": "weight"
         },
@@ -21,7 +23,9 @@
       ]
     },
     {
-      "formula": "p_{org} = \\min\\left(1, \\frac{L_{org}}{100}\\right)",
+      "formula": "p_{org} = \\min\\left(1, \\frac{V_{org}}{100}\\right)",
+      "section": "Aggregation stages",
+      "context": "The organic share comes from the region-standardsLabels-isOrganic lookup (FiBL), averaged over the aggregation period.",
       "bindings": [
         {
           "symbol": "p_{org}",
@@ -29,19 +33,16 @@
           "key": "organic_weight"
         },
         {
-          "symbol": "L_{org}",
+          "symbol": "V_{org}",
           "description": "the lookup value as a percentage, averaged over the period",
           "key": "organic_weight_lookup_value"
-        },
-        {
-          "symbol": "L",
-          "description": "the plantation lifespan in days",
-          "key": "plantation_lifespan"
         }
       ]
     },
     {
       "formula": "p_{irr} = \\frac{A_{irr}}{A_{total}}",
+      "section": "Aggregation stages",
+      "context": "The irrigation share comes from the region-irrigated lookup (AQUASTAT).",
       "bindings": [
         {
           "symbol": "p_{irr}",
@@ -61,12 +62,14 @@
       ]
     },
     {
-      "formula": "w = \\begin{cases} \\frac{L - N}{L} & \\text{productive phase} \\\\ \\frac{365}{L} & \\text{preparation phase} \\\\ \\frac{N - 365}{L} & \\text{non-productive phase} \\end{cases}",
+      "formula": "w_p = \\begin{cases} \\frac{L - N}{L} & \\text{productive phase} \\\\ \\frac{365}{L} & \\text{preparation phase} \\\\ \\frac{N - 365}{L} & \\text{non-productive phase} \\end{cases}",
+      "section": "Plantation weighting",
+      "context": "The weight for each category is then calculated from the default glossary values for plantation_lifespan and plantation_non_productive_lifespan.",
       "bindings": [
         {
-          "symbol": "w",
-          "description": "the weight of a Cycle, by the phase it describes",
-          "key": "weight"
+          "symbol": "w_p",
+          "description": "the weight of a Cycle, by the phase it describes, which is not stored",
+          "display": true
         },
         {
           "symbol": "L",
@@ -87,6 +90,8 @@
     },
     {
       "formula": "w_c = \\min\\left(1, \\frac{P_c}{P_{world}}\\right)",
+      "section": "World aggregations",
+      "context": "World aggregations are created by combining verified country aggregations.",
       "bindings": [
         {
           "symbol": "w_c",
@@ -102,18 +107,15 @@
           "symbol": "P_{world}",
           "description": "the world production quantity of the product over the same period",
           "key": "world_production"
-        },
-        {
-          "symbol": "w",
-          "description": "the weight of the sub-aggregation",
-          "key": "weight"
         }
       ]
     }
   ],
   "hestia_earth/aggregation/docs/general-process.md": [
     {
-      "formula": "\\bar{v} = \\sum_i v_i \\times \\frac{w_i}{W}",
+      "formula": "\\bar{v} = \\sum_i v_i \\times \\frac{w_i}{W_T}",
+      "section": "Number values",
+      "context": "The simple mean is the case of the weighted mean where every weight is equal, so both are calculated the same way.",
       "bindings": [
         {
           "symbol": "\\bar{v}",
@@ -133,14 +135,16 @@
           "column": "weight"
         },
         {
-          "symbol": "W",
+          "symbol": "W_T",
           "description": "the total of every $w_i$",
           "key": "total_weight"
         }
       ]
     },
     {
-      "formula": "\\hat{w}_i = \\frac{w_i}{n_{k(i)} \\times W}",
+      "formula": "\\hat{w}_i = \\frac{w_i}{n_{k(i)} \\times W_T}",
+      "section": "Number values",
+      "context": "When several Cycles share the same weight, that weight is divided between them, so a group represented by many Cycles does not count more than a group represented by few: a group's share of the result is its intended weight, not its number of uploads.",
       "bindings": [
         {
           "symbol": "\\hat{w}_i",
@@ -158,7 +162,7 @@
           "display": true
         },
         {
-          "symbol": "W",
+          "symbol": "W_T",
           "description": "the total of every $w_i / n_{k(i)}$",
           "display": true
         }
@@ -166,6 +170,8 @@
     },
     {
       "formula": "\\bar{v} = \\sum_i v_i \\times \\frac{w_i}{W_R + W_Z}",
+      "section": "Completeness",
+      "context": "This zero-filling is what allows a term reported by only part of the population to be averaged over the whole population rather than only where it occurs.",
       "bindings": [
         {
           "symbol": "\\bar{v}",
@@ -193,16 +199,13 @@
           "symbol": "W_Z",
           "description": "the total weight of those that are complete for the area but report no value",
           "key": "zero_filled_weight"
-        },
-        {
-          "symbol": "W",
-          "description": "the total of every $w_i$",
-          "key": "total_weight"
         }
       ]
     },
     {
-      "formula": "EVS = \\overline{evs} \\times \\frac{W_P}{W}",
+      "formula": "EVS = \\overline{evs} \\times \\frac{W_P}{W_T}",
+      "section": "Primary Product",
+      "context": "Because economicValueShare is a share of the Cycle's total revenue rather than a physical quantity, it also has to account for how prevalent the product is across the population.",
       "bindings": [
         {
           "symbol": "EVS",
@@ -220,7 +223,7 @@
           "key": "product_weight"
         },
         {
-          "symbol": "W",
+          "symbol": "W_T",
           "description": "the total weight of all sub-aggregations",
           "key": "total_weight"
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hestia-earth/aggregation-engine",
-  "version": "0.22.1",
+  "version": "0.22.3",
   "description": "HESTIA Aggregation Engine",
   "main": "cjs/index.js",
   "directories": {