@hestia-earth/guide 0.0.16 → 0.0.17

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 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.17](https://gitlab.com/hestia-earth/hestia-guide/compare/v0.0.16...v0.0.17) (2025-10-09)
+
+
+### Features
+
+* **aggregation:** add first draft ([b4ddf1c](https://gitlab.com/hestia-earth/hestia-guide/commit/b4ddf1c6eda07367649a78d33b3a66336eb5b25d))
+* **aggregation:** update content, crop, processedFood ([3247848](https://gitlab.com/hestia-earth/hestia-guide/commit/32478484826745bf7be11918c54dd2429ebd29af)), closes [#31](https://gitlab.com/hestia-earth/hestia-guide/issues/31)
+* **applying-models:** add documentation and logs ([f166178](https://gitlab.com/hestia-earth/hestia-guide/commit/f1661780ddb4ac60656a98cce84fa5a14ba0501b))
+* **applying-models:** add file validation ([bc4c76d](https://gitlab.com/hestia-earth/hestia-guide/commit/bc4c76deeee50ce391aa80b526b33f0cfc69c168))
+* **applying-models:** add utils page ([a9e094a](https://gitlab.com/hestia-earth/hestia-guide/commit/a9e094a81cb9e20600e811ba19abc5bbddab10ac))
+* **applying-models:** update faqs ([d264628](https://gitlab.com/hestia-earth/hestia-guide/commit/d26462873805a0f27d5d370cb22c57e55f17763b))
+* **data-explorer:** add content where empty ([78a214e](https://gitlab.com/hestia-earth/hestia-guide/commit/78a214e64b9addb0f0b5195e333fa78911604edf))
+* **data-explorer:** add menu pages and content for some pages ([3a71a71](https://gitlab.com/hestia-earth/hestia-guide/commit/3a71a71b74a51deb1dc0f0d17149f5e12e257ced))
+* **file-upload:** add content on remaining pages ([571da1a](https://gitlab.com/hestia-earth/hestia-guide/commit/571da1a15e70e503a50e92337a11b62cbad6c030))
+* **file-upload:** add videos for uploading site and source ([24acb4a](https://gitlab.com/hestia-earth/hestia-guide/commit/24acb4ace988709f04223de4d92a9576baa90094))
+* **hestia-api:** add access page ([f76e6cb](https://gitlab.com/hestia-earth/hestia-guide/commit/f76e6cbd32d02001c79d209abd9277564defa0db))
+* **hestia-api:** add examples to the Data API ([f3e706a](https://gitlab.com/hestia-earth/hestia-guide/commit/f3e706ac162800ed8eb689bb722f5a25ef05ddf3))
+* **hestia-api:** add page about the Data API ([0fbf02b](https://gitlab.com/hestia-earth/hestia-guide/commit/0fbf02ba0c5436a00d33fb366acf6780e9f05e15))
+* **index:** replace `api-solid` with `api` icon ([58466e2](https://gitlab.com/hestia-earth/hestia-guide/commit/58466e268a769c28f76a1a03dc1b33c0aaa70952))
+* **user-files:** add content ([4369651](https://gitlab.com/hestia-earth/hestia-guide/commit/43696512fe92cbf5cfa5feb0c2dd66a01411df4b))
+
+
+### Bug Fixes
+
+* **aggregation-engine:** fix incorrect link to Data Explorer ([25c675b](https://gitlab.com/hestia-earth/hestia-guide/commit/25c675b870d6b0ed8116ab627e0f7879fa20be1a))
+* **hestia-api:** fix typo in params ([025a704](https://gitlab.com/hestia-earth/hestia-guide/commit/025a70414f2a135b1517ee64a1353d06cde9fbda))
+* **index:** update icon for `community-edition` ([0dc344c](https://gitlab.com/hestia-earth/hestia-guide/commit/0dc344c0c1aa9b0a1465d8700225480a6794e74c))
+* **index:** update icons ([502ce24](https://gitlab.com/hestia-earth/hestia-guide/commit/502ce24239e56b071a393b0c9726e1b4bbaa92b6))
+* **models:** handle return `model` and `model` instead of `methodModel` ([d6d36aa](https://gitlab.com/hestia-earth/hestia-guide/commit/d6d36aa4aaa955cab83f272bcf7909c7556ef347))
+
 ### [0.0.16](https://gitlab.com/hestia-earth/hestia-guide/compare/v0.0.15...v0.0.16) (2025-04-15)
 
 

package/README.md

@@ -60,10 +60,62 @@ This is the content of the page.
 /tag ~Beginners~
 ```
 
+### Linking pages together
+
+To link pages together via the "Related Topics" section on a page, you can add `/tag ~tag name~` on the pages you want to link together. Example:
+- add `/tag ~soc modelling~` on page 1
+- add `/tag ~soc modelling~` on page 2
+- add `/tag ~soc modelling~` on page 3
+
+On page 1, page 2 and 3 will appear under "Related Topics". Similarly, on page 2, page 1 and 3 will appear under "Related Topics".
+
+### Adding links to other pages
+
+Links to other pages, on the website, or to external websites, can be added with standard markdown syntax:
+
+```markdown
+[link title](https://some-website.com/link)
+[link title](https://hestia.earth/guide/other-page)
+# this also works as long as it is a page on the website
+[link title](/guide/other-page)
+[link title](/schema/Cycle)
+```
+
+### Adding a table
+
+Normally, to add a table, you just need to use the default markdown table style:
+
+| Header | Header |
+| - | - |
+| cell1 | cell2 |
+
+However in some cases, you might need finer control over the structure (like merging multiple cells with `colspan` attribute). In that case, tables need to be wrapped manullay using:
+```html
+<div class="table-container is-responsive">
+  <table class="table is-fullwidth is-hoverable is-striped">
+    <!-- Insert content here -->
+  </table>
+</div>
+```
+
+Note: to add multiple tables one after another, **insert only 1 empty line** between the 2 tables:
+
+```
+| Header | Header |
+| - | - |
+| cell1 | cell2 |
+
+| Header | Header |
+| - | - |
+| cell1 | cell2 |
+```
+
+If you insert 2 lines, the display may brake.
+
 ### Adding collapsible groups
 
 Collapsible blocks (hides the content with a toggle icon) can be added using html code as following:
-```markdown
+```html
 <div class="collapsibles">
   <div class="collapsible-group">
     <div class="collapsible-header">
@@ -81,32 +133,10 @@ Collapsible blocks (hides the content with a toggle icon) can be added using htm
 </div>
 ```
 
-### Adding step-by-step content
-
-Step by step content (title including a step number and a content):
-```markdown
-<div class="step">
-  <div class="step--header">
-    <div>1</div>
-    <div>This is the first step</div>
-  </div>
-  <div class="step--image">
-    <img src="/assets/step-1.png" />
-  </div>
-  <div class="step--content">
-    <p>Content goes here</p>
-  </div>
-</div>
-```
-
-Note: the `steps--image` is optional.
-
-### Adding images or videos
+### Adding a video or an image
 
-To add an image or a video to a page:
-- add the file under the `src/assets` folder. Note: you can use sub-directories to organise the files.
-- make sure to use a simple name, without special characters. So only letters and numbers, dashes or underscores.
-- in the content of the page, use:
+1. Copy your image in the `guide-assets` folder
+1. Reference your image in the markdown:
 ```markdown
-![Text to describe the image](/assets/<path_to_the_file.png|.mpg>)
+![Image title](/assets/my-image.png)
 ```

package/dist/content/guide/aggregation-engine/animalProduct.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# Animal product aggregation\n\nEven though we have started working on the logic for aggregating animal products, we have not released any animal product aggregations on HESTIA yet.\n\nWe will document the process when it is finalised."}

package/dist/content/guide/aggregation-engine/content.json

@@ -0,0 +1 @@
+{"tags":{"citation":["[Poore, J., & Nemecek, T. (2018). Reducing food's environmental impacts through producers and consumers. Science (New York, N.Y.), 360(6392), 987–992](https://doi.org/10.1126/science.aaq0216)"]},"content":"# HESTIA Aggregated Data\n\nLearn about how HESTIA is generating aggregated data, available in our [Data Explorer](https://hestia.earth/explorer/search?type=Aggregated%20Data).\nThe aim of aggregated data is to represent the average impact of producing a product, in a specific region and time period.\n\nAggregated data is validated by our team by checking the data is consistent with other sources, such as Poore, J., & Nemecek, T. (2018).\n\nThe process to aggregate data is different depending on the `termType` of the Product that we aggregate. Select which type you are interested to learn more.\n\n"}

package/dist/content/guide/aggregation-engine/crop.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# Crop aggregation\n\nAggregation of crops happens in multiple stages:\n1. We first get all public data on the platform corresponding to a certain time period, crop, and country.\n1. We then group the cycles into four groups: conventional and rainfed; conventional and irrigated; organic and irrigated; organic and rainfed. We aggregate data for each of those groups, creating four aggregations. This grouping helps us control for imbalances in our sample by stratifying at a level where differences in farming practices are substantial. We are working on adding further groupings in the future (e.g., greenhouse vs field grown).\n1. We then create a combined aggregation, by weighting each of the four aggregations by the area share of each group using data from FiBL for organic farming and AQUASTAT for irrigation.\n\nExample:\n\nWe have 8 Cycles on the platform for a specific product:\n- 2 are organic and irrigated.\n- 2 are organic and rainfed.\n- 2 are non-organic and irrigated.\n- 2 are non-organic and rainfed.\n\nWe create the following aggregated Cycles:\n- An organic - irrigated aggregation.\n- An organic - rainfed aggregation.\n- A non-organic - irrigated aggregation.\n- A non-organic - rainfed aggregation.\n- A final aggregation that combines all 4 of the above, assigning different weights for each aggregation, based on the area of production of each group for the particular country.\n\nIf one of the aggregations (e.g., organic - irrigated) is missing, we change the weighting structure so that it always sums to 100% and only takes the weighted average of the remaining groups.\n\n## General rules\n\n- We aggregate at the level of completness areas. For example, we will aggregate all of the fertiliser data for the Cycles where `completeness.fertiliser` = `true`. If a Cycle has `completeness.fertiliser` = `false`, we will not use any of the fertiliser data from that Cycle, but we will use data from that Cycle for other completness areas which are true. This approach allows us to pool data from many incomplete Cycles to create an overall complete dataset.\n- For data items with percentage units, we only use the values if the total value across the same `sumIs100Group` lookup, is equal to 100%. This is to make sure the total aggregated value will also sum to 100%, as our validation would otherwise mark the data as invalid.\n\n## Special rules\n\n### Aggregation of products\n\nThe following rules apply when aggregating the products:\n- When searching for Cycles to aggregate, we only include Cycles that have the `crop` as a `primary` Product.\n- We aggregate primary products that are marked as incomplete (e.g., `completeness.product=False`). However, we only use the `economicValueShare` of incomplete products if there is a `value` provided.\n- We rescale the product `value` when the `dryMatter` is different from HESTIA default `dryMatter` of the primary product, so all data can be compared at an equivalent `dryMatter`.\n\nFull example:\n\n| cycle.id | cycle.products.wheatGrain.value | cycle.products.wheatGrain.economicValueShare | cycle.completness.products |\n|------------------------|-------------------------------------|--------------------------|------|\n| 1 | 1000 | 20 | TRUE |\n| 2 | 5000 | - | TRUE |\n| 3 | 4000 | 100 | TRUE |\n| 4 | - | 90 | FALSE |\n| 5 | 2000 | - | FALSE |\n| 6 | 6000 | 95 | FALSE |\n| 7 | 0 | 0 | TRUE |\n| aggregated | 3000 =(1000+5000+4000+2000+6000+0)/6 | 90 =(20x1000+100x4000+95*6000)/11000 | TRUE |\n\n### Aggregation of background emissions\n\nWhen aggregating background emissions:\n- We filter the emissions based on the completeness of their `inputs`. For example, the background emissions for `diesel` will only be taken into account if `completeness.electricityFuel` is `True`.\n- We will add `0` values for Cycles that do not have an emission for a certain `input`, but are complete. For example, if we aggregated 2 compelete Cycles, and one has a background emission of `10` for `diesel`, the other one does not have any, the total will be `(10+0)/2` = `5`.\n\nFull example:\n\n| cycle.id | cycle.0.product.term.name | cycle.0.product.primary | cycle.emissions.0.term.name | cycle.emissions.0.value | cycle.emissions.0.inputs | cycle.emissions.1.term.name | cycle.emissions.1.value | cycle.emissions.1.inputs | cycle.emissions.2.term.name | cycle.emissions.2.value | cycle.emissions.2.inputs | cycle.emissions.3.term.name | cycle.emissions.3.value | cycle.emissions.3.inputs | completeness.fertiliser | completeness.pesticideVetinaryDrug | completeness.electricityFuel | cycle.emissions.0.term.name | cycle.emissions.0.value |\n|----------|---------------------------|-------------------------|--------------------------------|-------------------------|---------------------------------------------------|--------------------------------|-------------------------|----------------------------|--------------------------------|-------------------------|--------------------------|--------------------------------|-------------------------|--------------------------|-------------------------|------------------------------------|-------------------|--------------------------------|--------------------------|\n| 1 | Wheat, grain | TRUE | CO2, to air, inputs production | 30 | Inorganic Nitrogen fertiliser, unspecified (kg N) | CO2, to air, inputs production | 10 | Pesticide unspecified (AI) | CO2, to air, inputs production | 10 | Maize, grain | CO2, to air, inputs production | 10 | Diesel, Urea (kg N) | TRUE | TRUE | TRUE | - | - |\n| 2 | Wheat, grain | TRUE | CO2, to air, inputs production | - | Inorganic Nitrogen fertiliser, unspecified (kg N) | CO2, to air, inputs production | 30 | Pesticide unspecified (AI) | CO2, to air, inputs production | - | Maize, grain | CO2, to air, inputs production | - | Diesel, Urea (kg N) | FALSE | TRUE | TRUE | - | - |\n| 3 | Wheat, grain | TRUE | CO2, to air, inputs production | 0 | Inorganic Nitrogen fertiliser, unspecified (kg N) | CO2, to air, inputs production | 0 | Pesticide unspecified (AI) | CO2, to air, inputs production | 0 | Maize, grain | CO2, to air, inputs production | 0 | Diesel, Urea (kg N) | TRUE | TRUE | TRUE | - | - |\n| 4 | Wheat, grain | TRUE | CO2, to air, inputs production | - | Inorganic Nitrogen fertiliser, unspecified (kg N) | CO2, to air, inputs production | - | Pesticide unspecified (AI) | CO2, to air, inputs production | - | Maize, grain | CO2, to air, inputs production | - | Diesel, Urea (kg N) | FALSE | FALSE | FALSE | - | - |\n| aggregated | Wheat, grain | TRUE | CO2, to air, inputs production | 15 = (30 + 0)/2 | Inorganic Nitrogen fertiliser, unspecified (kg N) | CO2, to air, inputs production | 13.3 = (10 + 30 + 0)/3 | Pesticide unspecified (AI) | CO2, to air, inputs production | 5 = (10 + 0)/2 | Maize, grain | CO2, to air, inputs production | 5 = (10 + 0) /2 | Diesel, Urea (kg N) | TRUE | TRUE | TRUE | CO2, to air, inputs production | 38.3 = 15 + 13.3 + 5 + 5 |"}

package/dist/content/guide/aggregation-engine/processedFood.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# Processed food aggregation\n\nCurrently we generate aggregations for the food processing stage only at the global level to maximise data volume. For example, we pool in data describing flour milling in many countrie to generate a global milling aggregation. We then replace the background data in that aggregation (e.g., related to the crop or animal product that is processed, or related to electricity production) with country specific values. The justification for this is that food processing is relatively similar in terms of its inputs and products in different countries whereas the impacts of the agricultural inputs and energy can differ significantly by country.\n\nThe aggregation process is as follows:\n1. For a given processed food, we find we find all Cycles that has the processed food as a product, regardless of the country.\n1. We then filter those Cycles to those that have a specific list of inputs, based on the `aggregationInputTermIds` lookup. This means we identify processing Cycles where the input is what requires processing, and the product is the processed food.\n1. We aggregate all data, applying the same rules as when aggregating crop Cycles.\n1. We remove all background emissions from the aggregated Cycle.\n1. We recalculate the background emissions using the models provided in the HESTIA engine models library, like we would do on the HESTIA platform, using country-specific data where appropriate."}

package/dist/content/guide/applying-models/faq.json

@@ -1 +1 @@
-{"tags":{},"content":"# FAQ"}
+{"tags":{},"content":"# FAQs\n\n<div class=\"collapsibles is-medium\">\n  <div class=\"collapsible-group\">\n    <div class=\"collapsible-header\">\n      <span>Why does HESTIA have multiple models for each emissions and resource use?</span>\n    </div>\n    <div class=\"collapsible-content\">\n      <p>Different models have different data requirements. In general, more accurate models require more data such as Site Measurements or data on the Practices used. We have generally coded up multiple models at different tiers for the same emission or resource use (see the definitions of tiers in the <a href=\"https://hestia.earth/schema/Emission#methodTier\">schema</a>). We try to run the highest tier model first, and if that fails, try a lower tier model next. This approach means we run an accurate model if possible, but if not, run a less accurate model to calculate as many emissions and resource uses as possible.</p>\n      <p>For example, if a model fails for a Tier 2 emission, we might still be able to calculate the emission using a lesser tier, like Tier 1.</p>\n    </div>\n  </div>\n\n  <div class=\"collapsible-group\">\n    <div class=\"collapsible-header\">\n      <span>My Impact Assessment finished recalculating, but there are no emissions or resource use visible. Why?</span>\n    </div>\n    <div class=\"collapsible-content\">\n      <p>If the product of the Impact Assessment has no economic value share, or no value, and HESTIA was not able to gap-fill it, the emissions or resource use will not be calculated.</p>\n      <p>In this case, please look at the Recalculation logs of the products in \"Cycle: Inputs & Products\" section to determine why HESTIA was not able to gap-fill the product fields.</p>\n    </div>\n  </div>\n\n  <div class=\"collapsible-group\">\n    <div class=\"collapsible-header\">\n      <span>One of the emission on my Cycle failed to calculate. Why? How can I resolve this?</span>\n    </div>\n    <div class=\"collapsible-content\">\n      <p>Each model has a different set of requirements, which can be viewed in the <a href=\"https://hestia.earth/guide/models\">models documentation</a> for each model. If a requirement is not met, then the model will fail. Sometimes, when some data is missing, we are not able to get a specific lookup used by the model, which means the model will fail.</p>\n      <p>Some steps you can take to understand or fix it:</p>\n      <ul>\n        <li>Make sure all requirements of the model are met in your data. Some of these requirements can be gap-filled, so you can look at those requirements first. We often have models to gap fill these, such as geospatial models to gap fill Site Measurements, so check the results of these gap-fills first.</li>\n        <li>Check the lookups used by the model. Some of these lookups can be missing for the data you are using, in which case they would need to be added to <a href=\"https://gitlab.com/hestia-earth/hestia-glossary/-/issues\">our glossary</a> first.</li>\n        <li>Check the logs of the model, by clicking on the model name in the \"Recalculation logs\" tab. If you see any line that says \"None\" or \"False\", it could indicate something is missing or incorrect.</li>\n        <li>If you are still unable to determine the source of the problem, please log an issue <a href=\"https://gitlab.com/hestia-earth/hestia-engine-models/-/issues\">here</a> for us to rewiew.</li>\n      </ul>\n    </div>\n  </div>\n\n  <div class=\"collapsible-group\">\n    <div class=\"collapsible-header\">\n      <span>I have uploaded several cycles on the platform, covering different countries and crops. How do I see which cycle has possible failing emission models?</span>\n    </div>\n    <div class=\"collapsible-content\">\n      <p>Unfortunately at the moment, we do not have any report on failed models at the Cycle or File level, so you will need to review the Cycles one by one to find potential issues.</p>\n    </div>\n  </div>\n</div>"}

package/dist/content/guide/applying-models/file-validation.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# Validate CSV/JSON files\n\nHESTIA provides some functions to validate a CSV / JSON / JSON-LD files formatted following the [HESTIA format](/upload#excelCsv).\n\n## Validating a CSV file\n\nTo validate a CSV file, you will first need to convert it to JSON.\nThis can be done using the HESTIA's `utils` package:\n\n1. Install `NodeJS` version `12`\n2. Install the utils library globally: `npm install --global @hestia-earth/schema-convert`\n3. Drop your CSV files into a specific `folder` then run:\n```bash\nhestia-convert-to-json folder\n```\n\nYou will find in the `folder` the list of CSV files converted to JSON with the `.json` extension.\nThese files can be then used for validation described below.\n\n## Validating the Terms\n\nWhen uploading data on the HESTIA platform, you will need to use our [Glossary of Terms](/glossary).\nYou can follow these steps to install a package to validate the terms:\n\n1. Install `NodeJS` version `12`\n2. Install the utils library globally: `npm install --global @hestia-earth/utils`\n3. Drop your JSON / JSON-LD files into a specific `folder` then run:\n```bash\nAPI_URL=<APIUrl> hestia-validate-terms folder\n```\n\nErrors will appear in the console if any have been found.\n\n## Validating the Schema\n\nWhen uploading data on the HESTIA platform, you will need to follow our [Schema](/schema).\nYou can follow these steps to install a package to validate the schema:\n\n1. Install `NodeJS` version `12`\n2. Install the schema validation library globally: `npm install --global @hestia-earth/schema-validation`\n3. Drop your JSON / JSON-LD files into a specific `folder` then run:\n```bash\nhestia-validate-jsonld '' folder\n```\n\nErrors will appear in the console if any have been found.\n\n## Validating the Data\n\nOne important step when uploading data on the HESTIA platform is making sure the data is consistent using the [Data Validation package](https://gitlab.com/hestia-earth/hestia-data-validation).\nYou can follow these steps to install a package to validate the data:\n\n1. Install `Python` version `3` minimum\n2. Install the data validation library: `pip install hestia_earth.validation`\n3. Drop your JSON / JSON-LD files into a specific `folder` then run:\n```bash\nAPI_URL=<APIUrl> VALIDATE_SPATIAL=false VALIDATE_EXISTING_NODES=true hestia-validate-data folder\n```\n\nErrors will appear in the console if any have been found."}

package/dist/content/guide/applying-models/introduction.json

@@ -1 +1 @@
-{"tags":{},"content":"# Introduction"}
+{"tags":{},"content":"# Introduction\n\nHESTIA provides a set of models for running calculations or retrieving data using external datasets and internal lookups. These models can:\n- Gap fill climate and soil data (e.g., using satellite data).\n- Gap fill farm activity data (e.g., the quantity of crop residue produced).\n- Quantify land use change, on-farm resource use, and on-farm emissions.\n- Quantify the life cycle impacts of products from input production to the farm or processor gate.\n- Quantify indicators like greenhouse gas emissions, eutrophication, and biodiversity impact.\n\n## How to use the models\n\nHESTIA will automatically run all relevant models available, for every data uploaded on the [platform](https://hestia.earth).\n\nIf you would like to find other ways to run the models, outside of the platform, please [click here](https://hestia.earth/calculation/lca-models) to find out more.\n\n## Orchestration\n\nThe models in HESTIA are run using what we call the \"orchestrator\". It is responsible for:\n- Defining the order in which the models are run: to run some emissions, we need to make sure some products are present. Some models, that would gap-fill those products, would need to run before the emission model.\n- Defining the criteria for running the model: some emission and resource use models will not run if the user has added data at a higher tier to the model we have (e.g., measured data, tier 3 modelled data).\n- Defining the criteria for updating the data, based on the result of the model: in some cases, a model can run, but the result will not be used, because an existing value is already present. The orchestrator will therefore \"skip\" the result of the model.\n- Defining the order in which we run the different nodes: the calculations happen in multiple stages, accross the Site, Cycle and ImpactAssessment that are linked together. The order is as follows:\n    1. Run the Site models set for stage 1 calculations;\n    2. Run the Cycle models set for stage 1 calculations;\n    3. Run the Site models set for stage 2 calculations;\n    4. Run the Cycle models set for stage 2 calculations;\n    5. Run the Impact Assessment models set for stage 1 calculations;\n\nThe complete configuration of the models, and how to run them, is defined in the files [here](https://gitlab.com/hestia-earth/hestia-engine-models/-/tree/develop/config)."}

package/dist/content/guide/applying-models/logs.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# Understanding the Recalculation logs\n\nEach model that runs, and either succeeds or fails, will generate logs. The logs are parsed and displayed in the platform (for more technical users, a button \"Open Full Logs\" is available).\n\n![Recalcultion logs of Inputs & Product](/assets/applying-models/logs/logs-inputs-products.png)\n\nThe interface above is a representation of the logs. Each blank node in the Site, Cycle, or Impact Assessment can have their own logs. The recalculation log table will parse the logs and represent them in a more user-friendly interface.\n\n## What is included in the logs?\n\nWe include the following information:\n- the different blank node present in the Node, e.g., Cycle inputs, products, emissions; Site measurement or management; Impact Assessment resource use or impacts.\n- for each blank node, the different models or ways we can gap-fill or recalculate the blank node data _or some of its properties_.\n- the original and recalculated `value`\n- more logs on each model that ran.\n\n## What is *not* included in the logs?\n\nThe logs currently do not indicate clearly how to fix the issue, when they did not run. It only shows what was written in them by each model.\n\nTo be able to understand and fix the data for a model, you will need to:\n- look at the logs\n- look at the requirements of the model itself\n- look at the implementation of the model\n\nWe are currently working on solutions to make this process easier and more automated."}

package/dist/content/guide/applying-models/utils.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# HESTIA Utils\n\nThe utils library contains useful functions to work with HESTIA data.\n\n## Pivoting Headers by Terms\n\nAfter downloading data as CSV from the HESTIA platform, the format will look like this:\n\n| site.@id | site.measurements.0.term.@id | site.measurements.0.value | site.measurements.1.term.@id | site.measurements.1.value | site.measurements.2.term.@id | site.measurements.2.value | site.dataPrivate |\n|-----|-----|-----|-----|-----|-----|-----| -----|\n| xvflr | sandContent | 90 | siltContent | 6 | clayContent | 4 | false |\n| gght | sandContent | 90 | siltContent | 6 | clayContent | 4 | false |\n\nIt is possible to pivot some data based on the `term.@id` and move them as columns, such as:\n\n| site.@id | site.measurements.sandContent.value | site.measurements.siltContent.value | site.measurements.clayContent.value | site.dataPrivate |\n| ----- |-----|-----|------| -----|\n| xvflr | 90 | 6 | 4 | false |\n| gght | 90 | 6 | 4 | false |\n\n### Usage\n\n1. Install `Python` version `3` minimum\n2. Install the data validation library: `pip install hestia_earth.utils`\n3. Run:\n```bash\nhestia-pivot-csv source.csv dest.csv\n```\n\nThe `dest.csv` file will be pivoted."}

package/dist/content/guide/data-explorer/download.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# Downloading and sharing data\n\nComing soon..."}

package/dist/content/guide/data-explorer/faq.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# Troubleshooting & FAQs\n\nComing soon..."}

package/dist/content/guide/data-explorer/filters.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# Searching and filtering for data\n\n## Step by step to filtering data\n\nThe Filter Panel, located on the left of the screen, allows you to refine your search and pinpoint the exact data you need.\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>1</div>\n    <div>Select data type</div>\n  </div>\n  <div class=\"step--image\">\n    <img src=\"/assets/data-explorer/filters/filter-step-1.png\" width=\"320\" />\n  </div>\n  <div class=\"step--content\">\n    Start by selecting  what type of data you are looking for under ‘Select data type’.\n  </div>\n</div>\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>2</div>\n    <div>Select a category or subcategory</div>\n  </div>\n  <div class=\"step--image\">\n    <img src=\"/assets/data-explorer/filters/filter-step-2.png\" width=\"320\" />\n  </div>\n  <div class=\"step--content\">\n    <p>Under ‘Filter available data by’, click on a main category to select all items within it, or expand a category to reveal its subcategories and select specific items.</p>\n  </div>\n</div>\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>3</div>\n    <div>Search within subcategories</div>\n  </div>\n  <div class=\"step--image\">\n    <img src=\"/assets/data-explorer/filters/filter-step-3.png\" width=\"360\"/>\n  </div>\n  <div class=\"step--content\">\n    <p>Use the search bar within each subcategory to quickly find specific items.</p>\n  </div>\n</div>\n\nTip: If you need help understanding a filter option, hover over the information icon beside the section header.\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>4</div>\n    <div>View updated results </div>\n  </div>\n  <div class=\"step--content\">\n    <p>The result listings will automatically update to reflect your selected filters, though longer queries may take a few seconds to load.</p>\n  </div>\n</div>\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>5</div>\n    <div>Save your filters or access previous searches</div>\n  </div>\n    <div class=\"step--image\">\n    <img src=\"/assets/data-explorer/filters/filter-step-5.png\" width=\"360\" />\n  </div>\n  <div class=\"step--content\">\n    <p>If you are signed in, click the “save”icon at the top right of the filter panel to save your current filter settings for future use or access your previously used filters by clicking on the “clock” icon.</p>\n  </div>\n</div>\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>6</div>\n    <div>Clear filters</div>\n  </div>\n    <div class=\"step--image\">\n    <img src=\"/assets/data-explorer/filters/filter-step-6.png\" width=\"360\" />\n  </div>\n  <div class=\"step--content\">\n    <p>To remove a filter, simply uncheck the box next to the selected item or click the \"Clear All\" at the top left of the categories.</p>\n  </div>\n</div>\n\n## Step by step to searching for data\n\nLocated at the top of the screen, the search bar allows you to quickly find specific data related to keywords, products, regions, or other terms.\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>1</div>\n    <div>Selecting a data type</div>\n  </div>\n  <div class=\"step--image\">\n    <img src=\"/assets/data-explorer/filters/search-step-1.png\" width=\"360\" />\n  </div>\n  <div class=\"step--content\">\n    <p> Choose the appropriate data type from the dropdown menu. This tells the system where to look for your search term.</p>\n  </div>\n</div>\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>2</div>\n    <div>Dynamic filter adjustment</div>\n  </div>\n  <div class=\"step--image\">\n    <img src=\"/assets/data-explorer/filters/search-step-2.png\" width=\"360\" />\n  </div>\n  <div class=\"step--content\">\n    <p>Selecting a data type will automatically update the same data type within the Filter Panel. This ensures you’re only seeing relevant filters for the type of data you’re searching for. </p>\n  </div>\n</div>\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>3</div>\n    <div>Entering Your search term</div>\n  </div>\n  <div class=\"step--image\">\n    <img src=\"/assets/data-explorer/filters/search-step-3.png\" width=\"800\" />\n  </div>\n  <div class=\"step--content\">\n    <p>Type your search term into the search bar.</p>\n  </div>\n</div>\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>4</div>\n    <div>Search Query in Filter </div>\n  </div>\n  <div class=\"step--image\">\n    <img src=\"/assets/data-explorer/filters/search-step-4.png\" width=\"width=\"360\" />\n  </div>\n  <div class=\"step--content\">\n    <p>When entering your search query in the search bar the search term will also be shown under ‘All filters apply to your search:’ in the filter panel. This ensures that all filters applied at this point are related to your search query.</p>\n  </div>\n</div>\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>5</div>\n    <div>View Updated Results</div>\n  </div>  \n  <div class=\"step--content\">\n    <p>The result listings will automatically update to reflect your search term and selected data type. </p>\n  </div>\n</div>"}

package/dist/content/guide/data-explorer/navigating.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# Navigating the interface\n\nBefore you begin exploring the Data Explorer, let's clarify a few key terms you’ll encounter throughout the platform:\n- **Cycles**: describes the production of a crop, animal, animal product, or processed food, during a typical production period. The data can represent one or many farms or food processors.\n- **Aggregated data**: The aggregated datasets are weighted averages of specific production Cycles also stored in HESTIA. We aggregate for each country and crop at 15-to-20-year intervals.\n- **Sources**: Sources are generally peer-reviewed published studies or databases. They contain data on one or many production Cycles.\n- **Site**: The area on which a cycle occurred. Typically, a field for growing crops or grazing animals, an aquaculture pond, a building, or semi-natural vegetation. Sites can also be whole farms, regions, or countries.\n\nWhen you first open the platform, you’ll see the main screen as shown below. This screen provides a central hub for accessing and exploring agricultural data.\n\n![Key functions and features of the Data Explorer](/assets/data-explorer/navigating/key-features.png)\n\nThe data explorer is divided into several key areas:\n- **Search Bar (A)**: The Search Bar at the top of the screen allows you to search for specific keywords in cycles, aggregated data, sites and sources.\n- **Filter Panel (B)**: Located on the left side of the screen, the Filter Panel allows you to narrow your search by selecting specific criteria.\n- **Aggregated Data Chart (C)**: On the Aggregated Data pages, a chart is displayed to provide summarized insights.\n- **Result Listings (D)**: These provide a concise overview of available data that matches your search or filter criteria."}

package/dist/content/guide/data-explorer/results.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# Understanding the data results\n\nComing soon..."}

package/dist/content/guide/data-explorer/what-is-it.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# What is the Data Explorer?\n\nThe [Data Explorer](https://www.hestia.earth/explorer) offers you a streamlined pathway to a comprehensive collection of agricultural data from the HESTIA platform. Powerful filtering and search tools allow you to quickly pinpoint the information most relevant to your work.\n\nKey features:\n- **Browse Organized Results:** Quickly scan available data through visually organized listings.\n- **Explore Detailed Analyses:** Click through from each listing to a dedicated page with comprehensive data for a specific product cycle, aggregation, site or source.\n- **Powerful Filtering:** Narrow your search using filters such as products, regions, or environmental impacts to find the data you need.\n- **Aggregated Data Overviews:** An interactive chart offers a summarized perspective on broader agricultural trends and patterns, also filterable for targeted insights.\n- **Data Download Capabilities:** Download data sets for in-depth analysis and integration into your research.\n- **Clear Data Provenance:** Easily trace data back to its original sources, including publications and research institutions.\n- **Save Your Searches:** Create a profile and login to save frequently used searches for quick access and future reference.\n\nWith the help of the [Data Explorer](https://www.hestia.earth/explorer), you can gain valuable insights into agricultural practices and their environmental consequences. It empowers informed decision-making, supports sustainable solutions, and facilitates a deeper understanding of our global food systems."}

package/dist/content/guide/file-upload/content.json

@@ -1 +1 @@
-{"tags":{},"content":"# Uploading data\n\nStep-by-step instructions on how to securely upload your datasets to the platform."}
+{"tags":{},"content":"# Uploading data\n\nInformation and step-by-step instructions on how to securely upload your datasets to the platform."}

package/dist/content/guide/file-upload/contributing.json

@@ -1 +1 @@
-{"tags":{},"content":"# Why contribute?"}
+{"tags":{},"content":"# Why contribute?\n\nHESTIA is an open-source data platform that makes food production and impact data freely available for others to use. By contributing, you will be helping to increase the volume and representativeness of the data we make available.\n\nTo contribute to the publicly available data on the platform, your uploads need to be reviwed by a member of our team. To discuss this with us, please contact community@hestia.earth.\n\nYou are also able to upload your data privately on the platform (see [Uploading your file](/guide/file-upload/uploading)). This allows you to use HESTIA's models, and there is no requirement for the data to be reviewed."}

package/dist/content/guide/file-upload/getting-started.json

@@ -1 +1 @@
-{"tags":{},"content":"# Getting started"}
+{"tags":{},"content":"# Getting started\n\nOnce you've created an account with HESTIA (see [Managing your account](/guide/user-account)) you are able to upload your datasets.\n\nThe [Preparing your dataset](/guide/file-upload/prepare-file) section contains short videos on how to format your upload. There is also more detailed information in [How to Upload](https://www.hestia.earth/upload).\n\nAfter you've prepared your dataset, you can look at the [Uploading your file](/guide/file-upload/uploading) section for step-by-step instructions on how to upload your data.\n\nThe [Getting through the upload pipeline](/guide/file-upload/making-changes) section provides information on how to get your upload to pass HESTIA's validations; these check whether the data is correctly formatted."}

package/dist/content/guide/file-upload/making-changes.json

@@ -1 +1 @@
-{"tags":{},"content":"# Getting through the upload pipeline"}
+{"tags":{},"content":"# Getting through the upload pipeline\n\nAll uploads go through HESTIA's upload pipeline, where a series of checks are performed to ensure the data is correctly formatted.\n\nThe Refresh button at the bottom of the page can be used to reload the page so you can see the latest stage of your upload.\n\n![Refresh your page](/assets/file-upload/making-changes/refresh.png)\n\nOn the right-hand navigator, as well as the upload pipeline, there is also a summary of file issues. Errors will appear in red, and must be fixed before your file can be uploaded. Warnings will appear in orange; they are not required to be fixed, but it is recommended that you double check your data to ensure that the information provided is correct. Both have descriptions that explain why the issue has occurred.\n\n![File issues](/assets/file-upload/making-changes/file-issues.png)\n\nClicking on an error or warning will take you to its location in File Issues. This makes it easier to see where in your upload something needs to be fixed.\n\nBelow is an explanation of each stage of the upload pipeline, with some examples of common issues that can occur. If you are unable to fix issues that appear in the pipeline, you can email us at community@hestia.earth for assistance.\n\n## Data Compatibility\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>1</div>\n    <div>Convert to CSV format</div>\n  </div>\n  <div class=\"step--content\">\n   This step checks if your file is able to be converted into CSV format. You are allowed to upload files in CSV, JSON, and Excel. We recommend using Excel as this allows you to preserve the original formatting of your file.\n  </div>\n</div>\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>2</div>\n    <div>Convert to HESTIA format</div>\n  </div>\n  <div class=\"step--content\">\n    This step checks that your file is able to be converted into the HESTIA format. Common issues here are misspelled or duplicated column headers.\n  </div>\n</div>\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>3</div>\n    <div>Check Existing Nodes</div>\n  </div>\n  <div class=\"step--content\">\n    This step checks whether the terms used in your upload are in HESTIA's glossary. Common issues are misspelled terms or outdated ones that are no longer in the updated version of the glossary. If a term has been recently renamed, the error message will suggest the new term you should use.\n  </div>\n</div>\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>4</div>\n    <div>Add bibliogrpahy</div>\n  </div>\n  <div class=\"step--content\">\n    This step is where HESTIA uses the provided DOI to fill in the bibliography of your source. A common issue is if HESTIA cannot find the DOI in Mendeley, then you will have to manually add the bibliography information in the Source section of your upload.\n  </div>\n</div>\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>5</div>\n    <div>Add Metadata</div>\n  </div>\n  <div class=\"step--content\">\n    This step adds some fields to your data, e.g., default values, auto-generated fields like <code>name</code>, site <code>area</code> based on the <code>boundary</code> provided. It also creates Impact Assessments for the Cycle products, where none have been uploaded.\n  </div>\n</div>\n\n## Data Validation\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>1</div>\n    <div>Validate Schema</div>\n  </div>\n  <div class=\"step--content\">\n    This step checks whether your upload is consistent with HESTIA's schema. A common issue here is missing required files, e.g., if you've added the <code>sd</code> of a value but not specified the <code>statsDefinition</code>.\n  </div>\n</div>\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>2</div>\n    <div>Validate Data</div>\n  </div>\n  <div class=\"step--content\">\n    <p>This step checks the data itself against a range of validators on the HESTIA platform. Some could be fairly simple, e.g., you've specified a negative number as a value for an Input, and the value must be positive. Some can be more complex, e.g., ensuring the sum of tillage practices adds up to <code>100</code>.</p>\n    <p>At this stage you can also see warnings for your dataset. Common warnings are that you haven't specified a tillage practice or the amount of residue produced for a cropland site, or that a value, e.g., <code>Dry matter</code>, is substantially outside our default value.</p>\n  </div>\n</div>\n\n## Submission & Indexing\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>1</div>\n    <div>Submission</div>\n  </div>\n  <div class=\"step--image\">\n    <img src=\"/assets/file-upload/making-changes/comments-tasks.png\" />\n  </div>\n  <div class=\"step--content\">\n    Once your file has been submitted, if it is a public upload it will be reviewed by a member of our team. They may leave changes in the Comment & Tasks section, which you will need to make before your upload can be indexed.\n  </div>\n</div>\n\n<div class=\"step\">\n  <div class=\"step--header\">\n    <div>2</div>\n    <div>Indexing</div>\n  </div>\n  <div class=\"step--content\">\n    When a member of our team is happy with your upload, they will index it so that it can appear on the platform. If it is a private upload, the indexing process will happen automatically and you will not need to wait for review.\n  </div>\n</div>"}

package/dist/content/guide/file-upload/prepare-file.json

@@ -1 +1 @@
-{"tags":{},"content":"# Preparing a dataset"}
+{"tags":{},"content":"# Preparing a dataset\n\nThis page contains some short videos that walk you though how to prepare your dataset for uploading.\n\n## Adding Data\n\n### Source\n\n![How to add a Source](/assets/file-upload/prepare-file/source.mp4)\n\n### Site\n\n![How to add a Site](/assets/file-upload/prepare-file/site.mp4)\n\n### Cycle\n\nComing soon..."}

package/dist/content/guide/hestia-api/content.json

@@ -1 +1 @@
-{"tags":{},"content":"# Using the API\n\nA guide for developers looking to integrate and automate workflows with our platform’s API."}
+{"tags":{},"content":"# Using the API\n\nA guide for developers looking to integrate and automate workflows with our platform's APIs."}

package/dist/content/guide/hestia-api/data-api.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# Using the HESTIA Data API\n\nThe data api allows anyone to access all public data stored in HESTIA, in a \"compacted\" (or pivoted) format.\n\nThe API does not require creating an account.\n\nYou can test the API, and see all endpoints available, [on the Swagger docs](https://data.hestia.earth/swagger/).\n\nThe API is used on the [Data Explorer](https://hestia.earth/explorer).\n\n## Aggregated Data\n\nYou can use the Data API to retrieve aggregated data, exactly the same way the [Data Explorer](https://hestia.earth/explorer) is doing it.\n\nHere are some examples usage:\n- Get the releases available in HESTIA:\n```bash\n$ curl -X 'GET' \\\n  'https://api.hestia.earth/settings/dataReleases' \\\n  -H 'accept: application/json' \\\n```\n- Get the first 50 Aggregated data for the `v1` release on `2025-05-01`:\n```bash\n$ curl -X 'GET' \\\n  'https://data.hestia.earth/aggregated-nodes?offset=0&limit=50&sortBy=name&sortOrder=asc' \\\n  -H 'accept: application/json' \\\n  -H 'X-Data-Version: 2025-05-01'\n```\n- Search for aggregated data, for `Wheat, grain` and `Maize, grain`, in `France` and `United Kingdom`:\n```bash\n$ curl -X 'GET' \\\n  'https://data.hestia.earth/aggregated-nodes?filter=regions%3DUnited%20Kingdom%7CFrance%3Bproducts%3DWheat%2C%20grain%7CMaize%2C%20grain&offset=0&limit=50&sortBy=name&sortOrder=asc' \\\n  -H 'accept: application/json'\n```\n\nNotes:\n- if you do not set the `X-Data-Version` header, the latest available data will be returned;\n- the limit for a single request is `50` results. If the `count` in the response is greater than `50`, you can paginate using the `offset` parameter. Example: `limit=50&offset=100` will return the results from `100` to `150`."}

package/dist/content/guide/hestia-api/main-api.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# Using the HESTIA API\n\nThe HESTIA API allows you to interact with your account, and your uploaded files.\n\n## Creating an account\n\nTo create an account, go to [this page](/users/signup) and enter your information.\n\n## Retrieving the access token\n\nOnce your account is created, you will get a personnal access token. You have several ways to retrieve the token:\n\n1. Go to [your profile](/profile) and copy the key in the section `API Key`.\n2. Use cURL from a terminal:\n```bash\ncurl -X POST \"https://api.hestia.earth/users/signin\" \\\n  -H \"Content-Type: application/json\" \\\n  --data '{\"email\":\"email@email.com\",\"password\":\"pwd\"}' | jq '.token'\n```\n3. Using Python:\n```python\nimport json\nimport requests\n\nheaders = {'Content-Type': 'application/json'}\nbody = json.dumps({\"email\":\"email@email.com\",\"password\":\"pwd\"})\ntoken = requests.post('https://api.hestia.earth/users/signin', body, headers=headers).json().get('token')\nprint(token)\n```\n4. Using JavaScript in the browser:\n```javascript\n(async () => {\n  const url = 'https://api.hestia.earth/users/signin';\n  const headers = {\n    'Content-Type': 'application/json'\n  };\n  const body = JSON.stringify({ email: 'email@email.com', password: 'pwd' });\n  const response = await fetch(url, { method: 'POST', headers, body });\n  const { token } = await response.json();\n  console.log(token);\n})();\n```\n4. Using JavaScript with NodeJS:\n```javascript\nconst axios = require('axios');\n\n(async () => {\n  const url = 'https://api.hestia.earth/users/signin';\n  const body = { email: 'email@email.com', password: 'pwd' };\n  const { data: { token } } = await axios.post(url, body);\n  console.log(token);\n})();\n```\n\nYou can now test the API [on the Swagger docs](https://api.hestia.earth/swagger/)."}

package/dist/content/guide/user-files/content.json

@@ -1 +1 @@
-{"tags":{},"content":"# Managing your files\n\nDiscover how to organize, filter, and maintain your data collections effectively."}
+{"tags":{},"content":"# Managing your files\n\nDiscover how to organize, filter, and maintain your data collections effectively.\n\n## Using My Datasets\n\nAll of your datasets can be found under `My Datasets`. Here you can see the name of each dataset, its status, when it was last uploaded, and when it was last indexed.\n\n![My Datasets location](/assets/user-files/content/my-datasets.png)\n\nThe gear icon allows you to filter your datasets by their status. By filtering by `Outdated only`, you can see which of your datasets need to be updated to align with the current schema and glossary.\n\n![Filter options](/assets/user-files/content/filter.png)\n\nThe arrow icon allows you to change the order in which your datasets appear. It defaults to `Upload Date` from newest to oldest, but you can also sort by `Filename`, `Folder`, and `Status`. Clicking the sorting option a second time will reverse the order of the datasets, e.g., sorting by `Upload Date` from oldest to newest.\n\n![Sorting options](/assets/user-files/content/sort.png)\n\nThe three dots next to each dataset can be used to do the following actions:\n- Upload new version: this will take you to the `Data Upload` page where you can upload an updated version of your dataset.\n- Share: this allows you to share your dataset with another HESTIA account holder, and can be used to share private uploads with other users.\n- Rename Dataset: this allows you to change the name of a dataset, however if the uploads are already validated it will not be possible to rename the dataset.\n- Delete Dataset: this can be used to delete your dataset, however this is not possible if it has been indexed. If you need to delete an indexed dataset, you can email us at community@hestia.earth.\n\n![Dataset actions](/assets/user-files/content/actions.png)"}