@hestia-earth/aggregation-engine 0.22.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +38 -0
- package/cjs/formulas.d.ts +81 -0
- package/cjs/formulas.js +40 -0
- package/cjs/index.d.ts +1 -0
- package/cjs/index.js +17 -0
- package/esm/formulas.d.ts +81 -0
- package/esm/formulas.js +24 -0
- package/esm/index.d.ts +1 -0
- package/esm/index.js +1 -0
- package/formulas/README.md +66 -0
- package/formulas/index.json +230 -0
- package/package.json +64 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2019-2025 Harmonised Environmental Storage and Tracking of the Impacts of Agriculture (HESTIA) Project
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# HESTIA Aggregation Engine
|
|
2
|
+
|
|
3
|
+
[](https://gitlab.com/hestia-earth/hestia-aggregation-engine/commits/master)
|
|
4
|
+
[](https://gitlab.com/hestia-earth/hestia-aggregation-engine/commits/master)
|
|
5
|
+
[](https://hestia-aggregation-engine.readthedocs.io/en/latest/?badge=latest)
|
|
6
|
+
|
|
7
|
+
## Documentation
|
|
8
|
+
|
|
9
|
+
Official documentation can be found on [Read the Docs](https://hestia-aggregation-engine.readthedocs.io/en/latest/index.html).
|
|
10
|
+
|
|
11
|
+
Additional models documentation can be found in the [source folder](./hestia_earth/aggregation).
|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
1. Install the module:
|
|
16
|
+
```bash
|
|
17
|
+
pip install hestia_earth.aggregation
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
### Usage
|
|
21
|
+
|
|
22
|
+
```python
|
|
23
|
+
import os
|
|
24
|
+
from hestia_earth.aggregation import aggregate
|
|
25
|
+
|
|
26
|
+
aggregates = aggregate(country_name='Japan')
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Generating Covariance martrix
|
|
30
|
+
|
|
31
|
+
To generate the covariance matrix, some CSV files are generated and stored in a folder.
|
|
32
|
+
|
|
33
|
+
By default, these files will be created in the `/tmp` directory and removed at the end of aggregation, which can be changed setting the `TMP_DIR` env variable.
|
|
34
|
+
|
|
35
|
+
You can also choose a different storage method with the `AGGREGATION_COVARIANCE_STORAGE` env variable:
|
|
36
|
+
- `temporary`: default value, will store the files in the `TMP_DIR` and delete them at the end;
|
|
37
|
+
- `s3#<folder>`: upload the files on the S3 bucket defined by the variable `AWS_BUCKET_UPLOADS`;
|
|
38
|
+
- `local#<folder>`: copy the files to a local folder.
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A single symbol in a formula, optionally bound to a value.
|
|
3
|
+
*
|
|
4
|
+
* The shape is identical to `IFormulaBinding` in `@hestia-earth/engine-models`, so a
|
|
5
|
+
* formula from this package can be passed straight to that package's `renderFormula`.
|
|
6
|
+
*/
|
|
7
|
+
export interface IFormulaBinding {
|
|
8
|
+
/**
|
|
9
|
+
* The KaTeX symbol as written in the formula, e.g. `\bar{v}`, `W`.
|
|
10
|
+
*/
|
|
11
|
+
symbol: string;
|
|
12
|
+
/**
|
|
13
|
+
* Human-readable description from the formula's "Where:" list.
|
|
14
|
+
*/
|
|
15
|
+
description?: string;
|
|
16
|
+
/**
|
|
17
|
+
* The field this symbol resolves to. `value` is the result (left-hand side); any other
|
|
18
|
+
* key is looked up on the values passed to `renderFormula`. Absent for constants and
|
|
19
|
+
* display-only symbols. When `column` is set, this is the key of a packed table string
|
|
20
|
+
* rather than a scalar.
|
|
21
|
+
*/
|
|
22
|
+
key?: string;
|
|
23
|
+
/**
|
|
24
|
+
* A value inside a packed table string: the column to read. With no `match`, the symbol
|
|
25
|
+
* sits under a `\sum` and is expanded once per row.
|
|
26
|
+
*/
|
|
27
|
+
column?: string;
|
|
28
|
+
/**
|
|
29
|
+
* Row selection: pick the row of the `key` table whose id starts with this value, then
|
|
30
|
+
* read `column` from it.
|
|
31
|
+
*/
|
|
32
|
+
match?: string;
|
|
33
|
+
/**
|
|
34
|
+
* A fixed constant (not logged): the symbol always substitutes to this literal.
|
|
35
|
+
*/
|
|
36
|
+
constant?: string;
|
|
37
|
+
/**
|
|
38
|
+
* Documentation-only: a symbol that can never be substituted, because the value it
|
|
39
|
+
* refers to is not stored. Excluded from coverage; never flagged as missing.
|
|
40
|
+
*/
|
|
41
|
+
display?: boolean;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* A KaTeX formula extracted from the aggregation documentation, with the bindings needed to
|
|
45
|
+
* substitute its symbols.
|
|
46
|
+
*/
|
|
47
|
+
export interface IFormula {
|
|
48
|
+
/**
|
|
49
|
+
* The KaTeX source (without the `$$` delimiters).
|
|
50
|
+
*/
|
|
51
|
+
formula: string;
|
|
52
|
+
/**
|
|
53
|
+
* The symbols in the formula, in "Where:" list order.
|
|
54
|
+
*/
|
|
55
|
+
bindings: IFormulaBinding[];
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* The page a formula is documented on, which is also its id in the guide's
|
|
59
|
+
* `aggregated-data` section.
|
|
60
|
+
*/
|
|
61
|
+
export type AggregationPage = string;
|
|
62
|
+
/**
|
|
63
|
+
* Every page that documents at least one formula.
|
|
64
|
+
*/
|
|
65
|
+
export declare const getFormulaPages: () => AggregationPage[];
|
|
66
|
+
/**
|
|
67
|
+
* Get the formulas documented on an aggregation page, in the order they appear.
|
|
68
|
+
* Returns an empty array when the page is unknown or documents no formula.
|
|
69
|
+
*
|
|
70
|
+
* ```ts
|
|
71
|
+
* import { getFormulas } from '@hestia-earth/aggregation-engine';
|
|
72
|
+
* import { renderFormula } from '@hestia-earth/engine-models';
|
|
73
|
+
*
|
|
74
|
+
* getFormulas('crop').map((formula) => renderFormula(formula, {}));
|
|
75
|
+
* ```
|
|
76
|
+
*/
|
|
77
|
+
export declare const getFormulas: (page: AggregationPage) => IFormula[];
|
|
78
|
+
/**
|
|
79
|
+
* Every formula in the package, flattened.
|
|
80
|
+
*/
|
|
81
|
+
export declare const getAllFormulas: () => IFormula[];
|
package/cjs/formulas.js
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.getAllFormulas = exports.getFormulas = exports.getFormulaPages = void 0;
|
|
4
|
+
var data = require("../formulas/index.json");
|
|
5
|
+
// keyed by the doc path, e.g. `hestia_earth/aggregation/docs/crop.md`
|
|
6
|
+
var formulas = data;
|
|
7
|
+
var docPath = function (page) {
|
|
8
|
+
return "hestia_earth/aggregation/docs/".concat(page, ".md");
|
|
9
|
+
};
|
|
10
|
+
/**
|
|
11
|
+
* Every page that documents at least one formula.
|
|
12
|
+
*/
|
|
13
|
+
var getFormulaPages = function () {
|
|
14
|
+
return Object.keys(formulas).map(function (path) {
|
|
15
|
+
return path.replace('hestia_earth/aggregation/docs/', '').replace('.md', '');
|
|
16
|
+
});
|
|
17
|
+
};
|
|
18
|
+
exports.getFormulaPages = getFormulaPages;
|
|
19
|
+
/**
|
|
20
|
+
* Get the formulas documented on an aggregation page, in the order they appear.
|
|
21
|
+
* Returns an empty array when the page is unknown or documents no formula.
|
|
22
|
+
*
|
|
23
|
+
* ```ts
|
|
24
|
+
* import { getFormulas } from '@hestia-earth/aggregation-engine';
|
|
25
|
+
* import { renderFormula } from '@hestia-earth/engine-models';
|
|
26
|
+
*
|
|
27
|
+
* getFormulas('crop').map((formula) => renderFormula(formula, {}));
|
|
28
|
+
* ```
|
|
29
|
+
*/
|
|
30
|
+
var getFormulas = function (page) {
|
|
31
|
+
return formulas[docPath(page)] || [];
|
|
32
|
+
};
|
|
33
|
+
exports.getFormulas = getFormulas;
|
|
34
|
+
/**
|
|
35
|
+
* Every formula in the package, flattened.
|
|
36
|
+
*/
|
|
37
|
+
var getAllFormulas = function () {
|
|
38
|
+
return Object.values(formulas).reduce(function (all, pageFormulas) { return all.concat(pageFormulas); }, []);
|
|
39
|
+
};
|
|
40
|
+
exports.getAllFormulas = getAllFormulas;
|
package/cjs/index.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from './formulas';
|
package/cjs/index.js
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __exportStar = (this && this.__exportStar) || function(m, exports) {
|
|
14
|
+
for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
|
|
15
|
+
};
|
|
16
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
17
|
+
__exportStar(require("./formulas"), exports);
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A single symbol in a formula, optionally bound to a value.
|
|
3
|
+
*
|
|
4
|
+
* The shape is identical to `IFormulaBinding` in `@hestia-earth/engine-models`, so a
|
|
5
|
+
* formula from this package can be passed straight to that package's `renderFormula`.
|
|
6
|
+
*/
|
|
7
|
+
export interface IFormulaBinding {
|
|
8
|
+
/**
|
|
9
|
+
* The KaTeX symbol as written in the formula, e.g. `\bar{v}`, `W`.
|
|
10
|
+
*/
|
|
11
|
+
symbol: string;
|
|
12
|
+
/**
|
|
13
|
+
* Human-readable description from the formula's "Where:" list.
|
|
14
|
+
*/
|
|
15
|
+
description?: string;
|
|
16
|
+
/**
|
|
17
|
+
* The field this symbol resolves to. `value` is the result (left-hand side); any other
|
|
18
|
+
* key is looked up on the values passed to `renderFormula`. Absent for constants and
|
|
19
|
+
* display-only symbols. When `column` is set, this is the key of a packed table string
|
|
20
|
+
* rather than a scalar.
|
|
21
|
+
*/
|
|
22
|
+
key?: string;
|
|
23
|
+
/**
|
|
24
|
+
* A value inside a packed table string: the column to read. With no `match`, the symbol
|
|
25
|
+
* sits under a `\sum` and is expanded once per row.
|
|
26
|
+
*/
|
|
27
|
+
column?: string;
|
|
28
|
+
/**
|
|
29
|
+
* Row selection: pick the row of the `key` table whose id starts with this value, then
|
|
30
|
+
* read `column` from it.
|
|
31
|
+
*/
|
|
32
|
+
match?: string;
|
|
33
|
+
/**
|
|
34
|
+
* A fixed constant (not logged): the symbol always substitutes to this literal.
|
|
35
|
+
*/
|
|
36
|
+
constant?: string;
|
|
37
|
+
/**
|
|
38
|
+
* Documentation-only: a symbol that can never be substituted, because the value it
|
|
39
|
+
* refers to is not stored. Excluded from coverage; never flagged as missing.
|
|
40
|
+
*/
|
|
41
|
+
display?: boolean;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* A KaTeX formula extracted from the aggregation documentation, with the bindings needed to
|
|
45
|
+
* substitute its symbols.
|
|
46
|
+
*/
|
|
47
|
+
export interface IFormula {
|
|
48
|
+
/**
|
|
49
|
+
* The KaTeX source (without the `$$` delimiters).
|
|
50
|
+
*/
|
|
51
|
+
formula: string;
|
|
52
|
+
/**
|
|
53
|
+
* The symbols in the formula, in "Where:" list order.
|
|
54
|
+
*/
|
|
55
|
+
bindings: IFormulaBinding[];
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* The page a formula is documented on, which is also its id in the guide's
|
|
59
|
+
* `aggregated-data` section.
|
|
60
|
+
*/
|
|
61
|
+
export type AggregationPage = string;
|
|
62
|
+
/**
|
|
63
|
+
* Every page that documents at least one formula.
|
|
64
|
+
*/
|
|
65
|
+
export declare const getFormulaPages: () => AggregationPage[];
|
|
66
|
+
/**
|
|
67
|
+
* Get the formulas documented on an aggregation page, in the order they appear.
|
|
68
|
+
* Returns an empty array when the page is unknown or documents no formula.
|
|
69
|
+
*
|
|
70
|
+
* ```ts
|
|
71
|
+
* import { getFormulas } from '@hestia-earth/aggregation-engine';
|
|
72
|
+
* import { renderFormula } from '@hestia-earth/engine-models';
|
|
73
|
+
*
|
|
74
|
+
* getFormulas('crop').map((formula) => renderFormula(formula, {}));
|
|
75
|
+
* ```
|
|
76
|
+
*/
|
|
77
|
+
export declare const getFormulas: (page: AggregationPage) => IFormula[];
|
|
78
|
+
/**
|
|
79
|
+
* Every formula in the package, flattened.
|
|
80
|
+
*/
|
|
81
|
+
export declare const getAllFormulas: () => IFormula[];
|
package/esm/formulas.js
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import * as data from '../formulas/index.json';
|
|
2
|
+
// keyed by the doc path, e.g. `hestia_earth/aggregation/docs/crop.md`
|
|
3
|
+
const formulas = data;
|
|
4
|
+
const docPath = (page) => `hestia_earth/aggregation/docs/${page}.md`;
|
|
5
|
+
/**
|
|
6
|
+
* Every page that documents at least one formula.
|
|
7
|
+
*/
|
|
8
|
+
export const getFormulaPages = () => Object.keys(formulas).map((path) => path.replace('hestia_earth/aggregation/docs/', '').replace('.md', ''));
|
|
9
|
+
/**
|
|
10
|
+
* Get the formulas documented on an aggregation page, in the order they appear.
|
|
11
|
+
* Returns an empty array when the page is unknown or documents no formula.
|
|
12
|
+
*
|
|
13
|
+
* ```ts
|
|
14
|
+
* import { getFormulas } from '@hestia-earth/aggregation-engine';
|
|
15
|
+
* import { renderFormula } from '@hestia-earth/engine-models';
|
|
16
|
+
*
|
|
17
|
+
* getFormulas('crop').map((formula) => renderFormula(formula, {}));
|
|
18
|
+
* ```
|
|
19
|
+
*/
|
|
20
|
+
export const getFormulas = (page) => formulas[docPath(page)] || [];
|
|
21
|
+
/**
|
|
22
|
+
* Every formula in the package, flattened.
|
|
23
|
+
*/
|
|
24
|
+
export const getAllFormulas = () => Object.values(formulas).reduce((all, pageFormulas) => all.concat(pageFormulas), []);
|
package/esm/index.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from './formulas';
|
package/esm/index.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from './formulas';
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# Aggregation formulas
|
|
2
|
+
|
|
3
|
+
This folder contains the KaTeX formulas extracted from the aggregation rule documentation in
|
|
4
|
+
[`hestia_earth/aggregation/docs`](../hestia_earth/aggregation/docs), together with the **bindings**
|
|
5
|
+
that tie every symbol to a value. It is the aggregation-engine counterpart of the `formulas` folder
|
|
6
|
+
in `hestia-engine-models`, and uses the **same format**, so the same `renderFormula` and the same
|
|
7
|
+
ui-components formula component can render both.
|
|
8
|
+
|
|
9
|
+
`index.json` is generated by `scripts/generate-formulas.js` (`npm run build:formulas`). **Do not
|
|
10
|
+
edit it by hand** — edit the `.md` documentation instead and regenerate.
|
|
11
|
+
|
|
12
|
+
## Why these exist
|
|
13
|
+
|
|
14
|
+
An aggregation cannot show which values went into it: a sub-aggregation can cover tens of thousands
|
|
15
|
+
of Cycles, and copying their values into the output would multiply the dataset for no information
|
|
16
|
+
gain. What it *can* show is **how** the number was built — the formula, and the bounded quantities
|
|
17
|
+
that feed it (weights, totals, counts).
|
|
18
|
+
|
|
19
|
+
A formula renders with no values at all: symbols that have nothing to substitute stay symbolic and
|
|
20
|
+
are flagged as not logged. So these ship as documentation today, and become substitutable if and
|
|
21
|
+
when the aggregation records a jlog, without the docs changing.
|
|
22
|
+
|
|
23
|
+
## Contents
|
|
24
|
+
|
|
25
|
+
`index.json` holds every formula keyed by doc path: `{ [docPath]: IFormula[] }`. The file name is
|
|
26
|
+
the key a consumer addresses a formula by — `weightedAverage`, `countryWeights`, and so on.
|
|
27
|
+
|
|
28
|
+
The shape is `IFormula` / `IFormulaBinding` as exported by `@hestia-earth/engine-models`.
|
|
29
|
+
|
|
30
|
+
## Authoring
|
|
31
|
+
|
|
32
|
+
A doc is markdown with one or more `$$...$$` blocks, each followed by its own `Where:` list:
|
|
33
|
+
|
|
34
|
+
```markdown
|
|
35
|
+
$$\bar{v} = \sum_i v_i \times \frac{w_i}{W}$$
|
|
36
|
+
|
|
37
|
+
Where:
|
|
38
|
+
|
|
39
|
+
- $\bar{v}$ = the aggregated value `[value]`
|
|
40
|
+
- $v_i$ = the value reported by sub-aggregation $i$ `[weights:value]`
|
|
41
|
+
- $w_i$ = the weight of sub-aggregation $i$ `[weights:weight]`
|
|
42
|
+
- $W$ = the total weight `[total_weight]`
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Binding token forms, matching the models format:
|
|
46
|
+
|
|
47
|
+
| token | meaning |
|
|
48
|
+
|---|---|
|
|
49
|
+
| `[value]` | the result — the left-hand side |
|
|
50
|
+
| `[scalar_key]` | a single logged value |
|
|
51
|
+
| `[table:column]` | a column of a packed table, expanded once per row under a `\sum` |
|
|
52
|
+
| `[table@match:column]` | the row whose id starts with `match`, read `column` |
|
|
53
|
+
| `[const:365]` | a fixed literal, substituted as-is |
|
|
54
|
+
| `[display]` | documentation-only: never substitutable (e.g. a per-Cycle value that is not stored) |
|
|
55
|
+
|
|
56
|
+
Two rules the tests enforce, both learned the hard way:
|
|
57
|
+
|
|
58
|
+
- **Each `$$` block owns only the glossary between it and the next block.** Several formulas sharing
|
|
59
|
+
one `Where:` list leaves the earlier ones unbound. Give each formula its own list, or combine them
|
|
60
|
+
into one block with `\begin{cases}`.
|
|
61
|
+
- **At most one `\sum` per formula.** `renderFormula` expands a sum by treating everything after it
|
|
62
|
+
as the summand, so a sum in both numerator and denominator substitutes into malformed KaTeX.
|
|
63
|
+
Express the divisor as a scalar total (`W`) instead.
|
|
64
|
+
|
|
65
|
+
Run `npm run build:formulas` after editing, and commit the regenerated `index.json` — a test fails
|
|
66
|
+
if it is stale.
|
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
{
|
|
2
|
+
"hestia_earth/aggregation/docs/crop.md": [
|
|
3
|
+
{
|
|
4
|
+
"formula": "w = O \\times I",
|
|
5
|
+
"bindings": [
|
|
6
|
+
{
|
|
7
|
+
"symbol": "w",
|
|
8
|
+
"description": "the weight of the sub-aggregation",
|
|
9
|
+
"key": "weight"
|
|
10
|
+
},
|
|
11
|
+
{
|
|
12
|
+
"symbol": "O",
|
|
13
|
+
"description": "$p_{org}$ for an organic sub-aggregation, $1 - p_{org}$ for a conventional one",
|
|
14
|
+
"key": "organic_factor"
|
|
15
|
+
},
|
|
16
|
+
{
|
|
17
|
+
"symbol": "I",
|
|
18
|
+
"description": "$p_{irr}$ for an irrigated sub-aggregation, $1 - p_{irr}$ for a rainfed one",
|
|
19
|
+
"key": "irrigated_factor"
|
|
20
|
+
}
|
|
21
|
+
]
|
|
22
|
+
},
|
|
23
|
+
{
|
|
24
|
+
"formula": "p_{org} = \\min\\left(1, \\frac{L_{org}}{100}\\right)",
|
|
25
|
+
"bindings": [
|
|
26
|
+
{
|
|
27
|
+
"symbol": "p_{org}",
|
|
28
|
+
"description": "the organic share of the country's area",
|
|
29
|
+
"key": "organic_weight"
|
|
30
|
+
},
|
|
31
|
+
{
|
|
32
|
+
"symbol": "L_{org}",
|
|
33
|
+
"description": "the lookup value as a percentage, averaged over the period",
|
|
34
|
+
"key": "organic_weight_lookup_value"
|
|
35
|
+
},
|
|
36
|
+
{
|
|
37
|
+
"symbol": "L",
|
|
38
|
+
"description": "the plantation lifespan in days",
|
|
39
|
+
"key": "plantation_lifespan"
|
|
40
|
+
}
|
|
41
|
+
]
|
|
42
|
+
},
|
|
43
|
+
{
|
|
44
|
+
"formula": "p_{irr} = \\frac{A_{irr}}{A_{total}}",
|
|
45
|
+
"bindings": [
|
|
46
|
+
{
|
|
47
|
+
"symbol": "p_{irr}",
|
|
48
|
+
"description": "the irrigated share of the country's area",
|
|
49
|
+
"key": "irrigated_weight"
|
|
50
|
+
},
|
|
51
|
+
{
|
|
52
|
+
"symbol": "A_{irr}",
|
|
53
|
+
"description": "the irrigated area, averaged over the period",
|
|
54
|
+
"key": "irrigated_area"
|
|
55
|
+
},
|
|
56
|
+
{
|
|
57
|
+
"symbol": "A_{total}",
|
|
58
|
+
"description": "the total area for the same site type, averaged over the period",
|
|
59
|
+
"key": "total_area"
|
|
60
|
+
}
|
|
61
|
+
]
|
|
62
|
+
},
|
|
63
|
+
{
|
|
64
|
+
"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}",
|
|
65
|
+
"bindings": [
|
|
66
|
+
{
|
|
67
|
+
"symbol": "w",
|
|
68
|
+
"description": "the weight of a Cycle, by the phase it describes",
|
|
69
|
+
"key": "weight"
|
|
70
|
+
},
|
|
71
|
+
{
|
|
72
|
+
"symbol": "L",
|
|
73
|
+
"description": "the plantation lifespan in days",
|
|
74
|
+
"key": "plantation_lifespan"
|
|
75
|
+
},
|
|
76
|
+
{
|
|
77
|
+
"symbol": "N",
|
|
78
|
+
"description": "the non-productive lifespan in days",
|
|
79
|
+
"key": "plantation_non_productive_lifespan"
|
|
80
|
+
},
|
|
81
|
+
{
|
|
82
|
+
"symbol": "365",
|
|
83
|
+
"description": "the preparation phase, fixed at one year",
|
|
84
|
+
"constant": "365"
|
|
85
|
+
}
|
|
86
|
+
]
|
|
87
|
+
},
|
|
88
|
+
{
|
|
89
|
+
"formula": "w_c = \\min\\left(1, \\frac{P_c}{P_{world}}\\right)",
|
|
90
|
+
"bindings": [
|
|
91
|
+
{
|
|
92
|
+
"symbol": "w_c",
|
|
93
|
+
"description": "the weight of country $c$",
|
|
94
|
+
"key": "weight"
|
|
95
|
+
},
|
|
96
|
+
{
|
|
97
|
+
"symbol": "P_c",
|
|
98
|
+
"description": "the production quantity of the product in country $c$, averaged over the aggregation period",
|
|
99
|
+
"key": "country_production"
|
|
100
|
+
},
|
|
101
|
+
{
|
|
102
|
+
"symbol": "P_{world}",
|
|
103
|
+
"description": "the world production quantity of the product over the same period",
|
|
104
|
+
"key": "world_production"
|
|
105
|
+
},
|
|
106
|
+
{
|
|
107
|
+
"symbol": "w",
|
|
108
|
+
"description": "the weight of the sub-aggregation",
|
|
109
|
+
"key": "weight"
|
|
110
|
+
}
|
|
111
|
+
]
|
|
112
|
+
}
|
|
113
|
+
],
|
|
114
|
+
"hestia_earth/aggregation/docs/general-process.md": [
|
|
115
|
+
{
|
|
116
|
+
"formula": "\\bar{v} = \\sum_i v_i \\times \\frac{w_i}{W}",
|
|
117
|
+
"bindings": [
|
|
118
|
+
{
|
|
119
|
+
"symbol": "\\bar{v}",
|
|
120
|
+
"description": "the aggregated value, rounded to 4 significant figures",
|
|
121
|
+
"key": "value"
|
|
122
|
+
},
|
|
123
|
+
{
|
|
124
|
+
"symbol": "v_i",
|
|
125
|
+
"description": "the value contributed by the underlying Cycle or sub-aggregation $i$",
|
|
126
|
+
"key": "weights",
|
|
127
|
+
"column": "value"
|
|
128
|
+
},
|
|
129
|
+
{
|
|
130
|
+
"symbol": "w_i",
|
|
131
|
+
"description": "the weight of $i$, or `1` where no weighting structure applies",
|
|
132
|
+
"key": "weights",
|
|
133
|
+
"column": "weight"
|
|
134
|
+
},
|
|
135
|
+
{
|
|
136
|
+
"symbol": "W",
|
|
137
|
+
"description": "the total of every $w_i$",
|
|
138
|
+
"key": "total_weight"
|
|
139
|
+
}
|
|
140
|
+
]
|
|
141
|
+
},
|
|
142
|
+
{
|
|
143
|
+
"formula": "\\hat{w}_i = \\frac{w_i}{n_{k(i)} \\times W}",
|
|
144
|
+
"bindings": [
|
|
145
|
+
{
|
|
146
|
+
"symbol": "\\hat{w}_i",
|
|
147
|
+
"description": "the normalised weight of Cycle $i$",
|
|
148
|
+
"display": true
|
|
149
|
+
},
|
|
150
|
+
{
|
|
151
|
+
"symbol": "w_i",
|
|
152
|
+
"description": "the weight of Cycle $i$",
|
|
153
|
+
"display": true
|
|
154
|
+
},
|
|
155
|
+
{
|
|
156
|
+
"symbol": "n_{k(i)}",
|
|
157
|
+
"description": "the number of Cycles sharing Cycle $i$'s weight and group",
|
|
158
|
+
"display": true
|
|
159
|
+
},
|
|
160
|
+
{
|
|
161
|
+
"symbol": "W",
|
|
162
|
+
"description": "the total of every $w_i / n_{k(i)}$",
|
|
163
|
+
"display": true
|
|
164
|
+
}
|
|
165
|
+
]
|
|
166
|
+
},
|
|
167
|
+
{
|
|
168
|
+
"formula": "\\bar{v} = \\sum_i v_i \\times \\frac{w_i}{W_R + W_Z}",
|
|
169
|
+
"bindings": [
|
|
170
|
+
{
|
|
171
|
+
"symbol": "\\bar{v}",
|
|
172
|
+
"description": "the aggregated value",
|
|
173
|
+
"key": "value"
|
|
174
|
+
},
|
|
175
|
+
{
|
|
176
|
+
"symbol": "v_i",
|
|
177
|
+
"description": "the value reported for the term",
|
|
178
|
+
"key": "reporting",
|
|
179
|
+
"column": "value"
|
|
180
|
+
},
|
|
181
|
+
{
|
|
182
|
+
"symbol": "w_i",
|
|
183
|
+
"description": "the weight of a Cycle or sub-aggregation that reports the term",
|
|
184
|
+
"key": "reporting",
|
|
185
|
+
"column": "weight"
|
|
186
|
+
},
|
|
187
|
+
{
|
|
188
|
+
"symbol": "W_R",
|
|
189
|
+
"description": "the total weight of those that report the term",
|
|
190
|
+
"key": "reporting_weight"
|
|
191
|
+
},
|
|
192
|
+
{
|
|
193
|
+
"symbol": "W_Z",
|
|
194
|
+
"description": "the total weight of those that are complete for the area but report no value",
|
|
195
|
+
"key": "zero_filled_weight"
|
|
196
|
+
},
|
|
197
|
+
{
|
|
198
|
+
"symbol": "W",
|
|
199
|
+
"description": "the total of every $w_i$",
|
|
200
|
+
"key": "total_weight"
|
|
201
|
+
}
|
|
202
|
+
]
|
|
203
|
+
},
|
|
204
|
+
{
|
|
205
|
+
"formula": "EVS = \\overline{evs} \\times \\frac{W_P}{W}",
|
|
206
|
+
"bindings": [
|
|
207
|
+
{
|
|
208
|
+
"symbol": "EVS",
|
|
209
|
+
"description": "the aggregated economic value share, rounded to 2 decimal places",
|
|
210
|
+
"key": "value"
|
|
211
|
+
},
|
|
212
|
+
{
|
|
213
|
+
"symbol": "\\overline{evs}",
|
|
214
|
+
"description": "the mean of the reported economic value shares",
|
|
215
|
+
"key": "economicValueShare"
|
|
216
|
+
},
|
|
217
|
+
{
|
|
218
|
+
"symbol": "W_P",
|
|
219
|
+
"description": "the total weight of the sub-aggregations that report this product",
|
|
220
|
+
"key": "product_weight"
|
|
221
|
+
},
|
|
222
|
+
{
|
|
223
|
+
"symbol": "W",
|
|
224
|
+
"description": "the total weight of all sub-aggregations",
|
|
225
|
+
"key": "total_weight"
|
|
226
|
+
}
|
|
227
|
+
]
|
|
228
|
+
}
|
|
229
|
+
]
|
|
230
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@hestia-earth/aggregation-engine",
|
|
3
|
+
"version": "0.22.1",
|
|
4
|
+
"description": "HESTIA Aggregation Engine",
|
|
5
|
+
"main": "cjs/index.js",
|
|
6
|
+
"directories": {
|
|
7
|
+
"test": "tests"
|
|
8
|
+
},
|
|
9
|
+
"scripts": {
|
|
10
|
+
"build:formulas": "node scripts/generate-formulas.js",
|
|
11
|
+
"test": "hestia-validate-jsonld tests/fixtures",
|
|
12
|
+
"test:terms": "hestia-validate-terms tests/fixtures",
|
|
13
|
+
"convert:csv": "hestia-convert-to-csv samples",
|
|
14
|
+
"release": "standard-version -a",
|
|
15
|
+
"postrelease": "git push origin master --follow-tags",
|
|
16
|
+
"build:module": "rm -rf dist && npm run build:formulas && tsc -p tsconfig.dist.json && tsc -p tsconfig.esm.json && npm run build:module:data",
|
|
17
|
+
"build:module:data": "cp -R formulas dist/ && cp package.json README.md LICENSE dist/"
|
|
18
|
+
},
|
|
19
|
+
"repository": {
|
|
20
|
+
"type": "git",
|
|
21
|
+
"url": "git+ssh://git@gitlab.com/hestia-earth/hestia-aggregation-engine.git"
|
|
22
|
+
},
|
|
23
|
+
"keywords": [
|
|
24
|
+
"hestia",
|
|
25
|
+
"aggregation",
|
|
26
|
+
"engine",
|
|
27
|
+
"python"
|
|
28
|
+
],
|
|
29
|
+
"author": "Guillaume Royer <guillaume@hestia.earth>",
|
|
30
|
+
"license": "MIT",
|
|
31
|
+
"bugs": {
|
|
32
|
+
"url": "https://gitlab.com/hestia-earth/hestia-aggregation-engine/issues"
|
|
33
|
+
},
|
|
34
|
+
"homepage": "https://gitlab.com/hestia-earth/hestia-aggregation-engine#readme",
|
|
35
|
+
"devDependencies": {
|
|
36
|
+
"@aws-sdk/client-s3": "^3.965.0",
|
|
37
|
+
"@commitlint/cli": "^17.8.1",
|
|
38
|
+
"@commitlint/config-conventional": "^17.8.1",
|
|
39
|
+
"@hestia-earth/json-schema": "^38.3.1",
|
|
40
|
+
"@hestia-earth/schema": "^38.3.1",
|
|
41
|
+
"@hestia-earth/schema-convert": "^38.3.1",
|
|
42
|
+
"@hestia-earth/schema-validation": "^38.3.1",
|
|
43
|
+
"@hestia-earth/utils": "^0.17.25",
|
|
44
|
+
"axios": "^1.13.2",
|
|
45
|
+
"dotenv": "^8.6.0",
|
|
46
|
+
"fs-extra": "^9.1.0",
|
|
47
|
+
"husky": "^4.3.8",
|
|
48
|
+
"standard-version": "^9.5.0",
|
|
49
|
+
"typescript": "^5.9.3"
|
|
50
|
+
},
|
|
51
|
+
"standard-version": {
|
|
52
|
+
"scripts": {
|
|
53
|
+
"postbump": "node scripts/update-package-version.js",
|
|
54
|
+
"precommit": "git add hestia_earth/aggregation/version.py"
|
|
55
|
+
}
|
|
56
|
+
},
|
|
57
|
+
"husky": {
|
|
58
|
+
"hooks": {
|
|
59
|
+
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
|
|
60
|
+
}
|
|
61
|
+
},
|
|
62
|
+
"module": "esm/index.js",
|
|
63
|
+
"types": "cjs/index.d.ts"
|
|
64
|
+
}
|