@hestia-earth/aggregation-engine 0.23.4 → 0.23.5

package/formulas/README.md

@@ -53,7 +53,7 @@ Binding token forms, matching the models format:
 | `[const:365]` | a fixed literal, substituted as-is |
 | `[display]` | documentation-only: never substitutable (e.g. a per-Cycle value that is not stored) |
 
-Two rules the tests enforce, both learned the hard way:
+Rules learned the hard way. The tests enforce the first three; the last one no test can catch:
 
 - **Each `$$` block owns only the glossary between it and the next block.** Several formulas sharing
   one `Where:` list leaves the earlier ones unbound. Give each formula its own list, or combine them
@@ -61,6 +61,13 @@ Two rules the tests enforce, both learned the hard way:
 - **At most one `\sum` per formula.** `renderFormula` expands a sum by treating everything after it
   as the summand, so a sum in both numerator and denominator substitutes into malformed KaTeX.
   Express the divisor as a scalar total (`W`) instead.
+- **Keep symbols distinct within a doc**, `{` and `_` not being token boundaries: a bare `n` matches
+  inside `n_{k(i)}` and drags that formula's binding onto every formula containing an `n`. Use
+  `n_T`, `n_R` and so on.
+- **Everything the divisor applies to must sit inside the summand.** The expansion is
+  `<before the sum> + <summand per row joined by " + ">`, so `\frac{1}{n} \sum_i v_i` substitutes to
+  `\frac{1}{3} (20) + (30) + (90)` — the division reaches the first row only. Write
+  `\sum_i \frac{v_i}{n}`.
 
 Run `npm run build:formulas` after editing, and commit the regenerated `index.json` — a test fails
 if it is stale.

package/formulas/index.json

@@ -112,10 +112,33 @@
     }
   ],
   "hestia_earth/aggregation/docs/general-process.md": [
+    {
+      "formula": "\\bar{v} = \\sum_i \\frac{v_i}{n_T}",
+      "section": "Number values",
+      "context": "Where no weighting structure applies, every contributor counts for the same share of the result and the mean is a simple one.",
+      "bindings": [
+        {
+          "symbol": "\\bar{v}",
+          "description": "the aggregated value, rounded to 4 significant figures",
+          "key": "value"
+        },
+        {
+          "symbol": "v_i",
+          "description": "the value contributed by the underlying Cycle or sub-aggregation $i$, stored for a sub-aggregation but not for a Cycle",
+          "key": "weights",
+          "column": "value"
+        },
+        {
+          "symbol": "n_T",
+          "description": "the number of contributors combined",
+          "key": "weights_count"
+        }
+      ]
+    },
     {
       "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.",
+      "context": "Where a weighting structure does apply, each contributor counts for the share its weight gives it.",
       "bindings": [
         {
           "symbol": "\\bar{v}",
@@ -130,7 +153,7 @@
         },
         {
           "symbol": "w_i",
-          "description": "the weight of $i$, or `1` where no weighting structure applies",
+          "description": "the weight of $i$",
           "key": "weights",
           "column": "weight"
         },
@@ -169,9 +192,37 @@
       ]
     },
     {
-      "formula": "\\bar{v} = \\sum_i v_i \\times \\frac{w_i}{W_R + W_Z}",
+      "formula": "\\bar{v} = \\sum_i \\frac{v_i}{n_R + n_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}",
+          "description": "the aggregated value",
+          "key": "value"
+        },
+        {
+          "symbol": "v_i",
+          "description": "the value reported for the term, stored for a sub-aggregation but not for a Cycle",
+          "key": "reporting",
+          "column": "value"
+        },
+        {
+          "symbol": "n_R",
+          "description": "the number of Cycles or sub-aggregations that report the term",
+          "key": "reporting_count"
+        },
+        {
+          "symbol": "n_Z",
+          "description": "the number of them that are complete for the area but report no value",
+          "key": "zero_filled_count"
+        }
+      ]
+    },
+    {
+      "formula": "\\bar{v} = \\sum_i v_i \\times \\frac{w_i}{W_R + W_Z}",
+      "section": "Completeness",
+      "context": "Where a weighting structure applies, the same split is made over the weights rather than the counts.",
       "bindings": [
         {
           "symbol": "\\bar{v}",

package/package.json

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