@hestia-earth/guide 0.0.15 → 0.0.16

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.0.16](https://gitlab.com/hestia-earth/hestia-guide/compare/v0.0.15...v0.0.16) (2025-04-15)
+
+
+### Features
+
+* **applying-models:** add monte carlo simulation ([f164dff](https://gitlab.com/hestia-earth/hestia-guide/commit/f164dff912ee410cce10278d265ab23e25ce3519))
+
 ### [0.0.15](https://gitlab.com/hestia-earth/hestia-guide/compare/v0.0.14...v0.0.15) (2025-04-10)
 
 

package/dist/content/guide/applying-models/monte-carlo.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# Monte Carlo simulation\n\nMonte Carlo simulation is a method of approximating the uncertainty of model outputs in which multiple uncertain inputs interact with one another in complex ways.\n\nRather than taking an analytical approach, the Monte Carlo method involves running the model repeatedly using a different combination of randomly sampled inputs each time. Once the Monte Carlo has run, a single result value can be calculated by computing the mean of the simulation outputs, plus additional descriptive statistics including the standar deviation (sd) the minimum value (min) and the maximum value (max).\n\nAs the number of iterations increases, the approximation of the distribution of the model results converges towards the truth. The standard number of iterations for bootstrapping and Monte Carlo simulations is 10,000.\n\nYou can read more about Monte Carlo simulations in the SciPy documentation: [Resampling and Monte Carlo Methods](https://docs.scipy.org/doc/scipy/tutorial/stats/resampling.html).\n\n## General approach\n\nModels, such as `ipcc2019.organicCarbonPerHa.tier1` and `ipcc2019.organicCarbonPerHa.tier2`, that use Monte Carlo simulation to calculate descriptive statistics should use numpy arrays to allow for efficient calculations.\n\nData should be prepare in 2-dimensional arrays where each column represents an iteration:\n\n|   |   |   |   |\n|---|---|---|---|\n| Iteration 1 | Iteration 2 | ... | Iteration N |\n\nand each row represents a timestep (for models that run on timeseries of data):\n\n|   |\n|---|\n| Timestep 1 |\n| Timestep 2 |\n| ... |\n| Timestep N |\n\nTherefore, the final array should be arranged like this:\n\n|   |   |   |   |\n|---|---|---|---|\n| Timestep 1, Iteration 1 | Timestep 1, Iteration 2 | ... | Timestep 1, Iteration N |\n| Timestep 2, Iteration 1 | Timestep 2, Iteration 2 | ... | Timestep 2, Iteration N |\n| Timestep 3, Iteration 1 | Timestep 3, Iteration 2 | ... | Timestep 3, Iteration N |\n| ... | ... | ... | ... |\n| Timestep N, Iteration 1 | Timestep N, Iteration 2 | ... | Timestep N, Iteration N |\n\n## Array builders\n\nThe functions provided in the `hestia_earth.models.utils.array_builders` provide ways of creating arrays through the random sampling of different distributions.\n\n## Final values and descriptive statistics\n\nFinal model results (_i.e.,_ a single value for `value`, `sd`, `min` and `max` to be added to a HESTIA node) should be calculated by performed row-wise analysis of the array returned by the model.\n\nTo get the `value` of a node, we calculate the mean of each row.\n\n|   |   |   |   |\n|---|---|---|---|\n| Timestep 1, Result 1 | Timestep 1, Result 2 | ... | Timestep 1, Result N |\n| Timestep 2, Result 1 | Timestep 2, Result 2 | ... | Timestep 2, Result N |\n| Timestep 3, Result 1 | Timestep 3, Result 2 | ... | Timestep 3, Result N |\n| ... | ... | ... | ... |\n| Timestep N, Result 1 | Timestep N, Result 2 | ... | Timestep N, Result N |\n\nBecomes:\n\n|   |\n|---|\n| Timestep 1, Row-wise mean |\n| Timestep 2, Row-wise mean |\n| ... |\n| Timestep N, Row-wise mean |\n\n## Deterministic sampling\n\nThe problem with using random number generation in our models is the fact that they will return slightly different results each time they are run. This would cause issues with our model unit testing (_i.e.,_ does the model return the expected result based on a known input) and reconcilliation (_i.e.,_ does the deployed model return the same results every time an upload's impact assement is re-calculated).\n\nFor our models run as Monte Carlo simulations, we need resampling to be randomised but deterministic, such that the model returns exactly the same results each time it is re-run. This is achieved by seeding the random number generation with the hashed value of a HESTIA node's id (e.g., `abcd1234`) + the name of the model (e.g., `ipcc2019`) + the term id being calculated (e.g., `organicCarbonPerHa`).\n\nThis means that two [Sites](/schema/Site) with different ids, but identical `measurements` and `management`, will return slightly different results, but these results will be the same each time the model runs on each [Site](/schema/Site).\n\nIn most cases, the node passed to the `gen_seed` function will be the node the model is running on. Notable exceptions are models that calculate emissions from carbon stock changes or natural vegetation burning. These models, which are run on [Cycles](/schema/Cycle), generate a seed using the id of the [Site](/schema/Site) the [Cycle](/schema/Cycle) takes place on. This ensures the calculated emissions are stable when the model runs for each [Cycle](/schema/Cycle) that takes place on the same [Site](/schema/Site).\n\n## Discussion\n\nThe randomness inherent to Monte Carlo simulation means that sometimes small emissions are allocated to [Cycles](/schema/Cycle) with ostensibly stable carbon stocks. Users might expect the emissions from carbon stock changes for these cycles to be 0. Care must be taken to understand that the annual values of those stable carbon stocks have an associated uncertainty, expressed by the `sd` field of the node. Resampling of carbon stocks using the mean (`value`) and `sd` for each year in the inventory will introduce slight inter-year variability, which will propagate through to the final emission calculated."}