@hestia-earth/guide 0.0.17 → 0.0.18

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 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.18](https://gitlab.com/hestia-earth/hestia-guide/compare/v0.0.17...v0.0.18) (2025-11-11)
+
+
+### Features
+
+* add data-validation pages ([ffeffa2](https://gitlab.com/hestia-earth/hestia-guide/commit/ffeffa280206f9589cfe818dbd4e152b7aa63c44))
+* **aggregation-engine:** update aggregation guide ([71ad72f](https://gitlab.com/hestia-earth/hestia-guide/commit/71ad72f52a0e717516ccb4397ba69307f845ead0)), closes [#52](https://gitlab.com/hestia-earth/hestia-guide/issues/52)
+* **file-upload:** add content from frontend ([0474673](https://gitlab.com/hestia-earth/hestia-guide/commit/04746731a2a92b46d74d64a0a95b075fa44b59f6))
+* **file-upload:** update taglines ([aefc5c5](https://gitlab.com/hestia-earth/hestia-guide/commit/aefc5c5da603629775c7639ec27b2c83c736c2b6))
+* **file-validation:** update schema validation command ([02472b5](https://gitlab.com/hestia-earth/hestia-guide/commit/02472b5461ba4084cc240d54afe2a9010d2f1049))
+* **index:** remove `guide/hestia-101` and `guide/faq` ([e052031](https://gitlab.com/hestia-earth/hestia-guide/commit/e0520313e46c9669babf8002394abfe9528b8f35))
+
+
+### Bug Fixes
+
+* **file-validation:** fix NodeJS version ([50d065b](https://gitlab.com/hestia-earth/hestia-guide/commit/50d065bc9a4ec64d740c36377b42c38498ef44a8))
+* **file-validation:** remove `API_URL` variable ([87f2900](https://gitlab.com/hestia-earth/hestia-guide/commit/87f290073fb6ef26a509e8f9e09e8420655be5a1))
+
 ### [0.0.17](https://gitlab.com/hestia-earth/hestia-guide/compare/v0.0.16...v0.0.17) (2025-10-09)
 
 

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

@@ -1 +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"}
+{"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 the [Data Explorer](/explorer/search?type=Aggregated%20Data).\n\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\nThere is a general process for generating the aggregations, with some changes depending on the `termType` of the product aggregated. Although the logic for aggregating animal products is being developed, there have not yet been any animal product aggregations released. \n\nCurrently, including distributions of the underlying data used to produce the aggregations is being developed, and is already available for some aggregations on the platform.\n\n"}

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

@@ -1 +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 |"}
+{"tags":{},"content":"# Crop aggregation\n\nThe parts of the aggregation process which are specific to `crop` products.\n\n## Aggregation stages\n\nAggregation of crops happens in multiple stages:\n1. First all the public Cycles on the platform corresponding to a certain time period, crop, and country are gathered.\n2. Cycles are then grouped into four groups: `conventional` and `rainfed`; `conventional` and `irrigated`; `organic` and `irrigated`, `organic` and `rainfed`. Data is aggregated within each of these groups, creating up to four sub-aggregations. These groupings mean data can be weighted to take into account substantial differences in farming practices. In the future, further groupings will be included (e.g., greenhouse vs field grown).\n3. These sub-aggregations are then combined into one aggregation, and each of the four sub-aggregation's Cycle and Site information is weighted by the area share of its group, using data from FiBL for organic farming and AQUASTAT for irrigation. Currently, these weightings are country-specific but not crop-specific. \n4. The impact assessments of the four sub-aggregations and the final country aggregation are then recalculated.\n\n**Full example**\n\nCreating an aggregation for `Quinoa, grain - Peru - 2010-2025`.\n\nAll Cycles with `primaryProduct` = `Quinoa, grain`, country=`Peru`, and `endDate` between `2010-2025` are gathered. Four different sub-aggregations can be created:\n\n- `Quinoa, grain - Peru - 2010-2025 - organic - irrigated`\n- `Quinoa, grain - Peru - 2010-2025 - organic - rainfed`\n- `Quinoa, grain - Peru - 2010-2025 - conventional - irrigated`\n- `Quinoa, grain - Peru - 2010-2025 - conventional - rainfed`\n\nThe final aggregation `Quinoa, grain - Peru - 2010-2025` is generated by assigning different weights to each sub-aggregation. According to FIBL, the average share of organic agriculture in Peru between 2010 and 2025 was `2 %`, and according to Aquastat the average share of irrigated land was `30 %`. This means that the following weights are assigned to calculate the weighted mean:\n\n| sub-aggregation | weight | \n|---------------|------|\n| organic-irrigated | 0.6 % |\n| organic-rainfed | 1.4 % |\n| conventional-irrigated | 29.4 % |\n| conventional-rainfed | 68.6 % |\n\n## Primary product\n\n- When aggregating the `primaryProduct`, values are adjusted to have equivalent `Dry matter` before averaging. The`Dry matter` value they are adjusted to, comes from the default value in the glossary, [dryMatter](/glossary/lookups/crop.csv).\n\n## World aggregations\n\n- World aggregations are created by combining verified country aggregations. The country aggregations are weighted by their production volume, based on data from FAOSTAT."}

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

@@ -0,0 +1 @@
+{"tags":{},"content":"# Distributions\n\nThe process of viewing and generating distributions on aggregations.\n\n## Viewing distributions\n\n- Only a few aggregations on the platform currently contain distributions, however the aim for the next release is to have all aggregations containing distribution data.\n- The aggregations that do have distributions can be viewed by clicking on any `value`, and then selecting `Show` next to `distribution` on the tooltip.\n![Tooltip for a value, showing distribution button](/assets/aggregation-engine/show_distribution.png)\n- For emissions with multiple inputs, distributions are generated for the emission associated with each input, and the option to show them is in the right-most column in the tooltip.\n![Tooltip for an emissions value with inputs, showing distribution button](/assets/aggregation-engine/show_distribution.png)\n\n## Generating distributions\n\n- Distributions are generated for the Cycle and Site data in the underlying Cycles by randomly sampling from them 1000 times.\n- Sometimes the data in the underlying Cycles contains statistical information - `min`, `max`, `sd`, `distribution`. This is the case when a single study represents many farms but provides summary statistics instead of the data for each farm. This variation is captured by sampling from the data, assuming it is distributed normally, with a minimum of `0` where this is relevant. If a data point had `min`and `max` but not `sd`, the standard deviation would be estimated by `sd` = `(max - min)/4`.\n- To generate the distributions for the Impact Assessment, Impact Assessments are calculated for each point in the 1000-point distribution of the Cycle emissions and `primaryProduct`. For simplicity, the distribution of the `economicValueShare` is not considered.\n- Covariance matrices are also generated, which record the correlations between every data item in an aggregation. Currently these are not used, however the aim is to work on implementing a statistical method to take these into account when generating the impact assessment distribution. This will ensure the variance of the distribution is not overestimated."}

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

@@ -0,0 +1 @@
+{"tags":{},"content":"# General rules\n\nThe general process that applies to all aggregations, regardless of the `termType`. \n\n## Finding cycles\n\n- Aggregations are triggered for a particular `product`, `region`, and `period`.\n- The `region` can be a country, or the region `World`.\n- The `period` is 20 years in length, examples are `1990-2009` and `2010-2025`.\n- Cycles are found by searching for Cycles where the relevant `product` is the `primaryProduct` of the Cycle. Currently, aggregations can only be created for `products` that are the `primaryProduct` of their Cycle. \n\n## Completeness\n\n- Aggregations happen at the level of completeness areas. For example, all of the fertiliser data for the Cycles where `completeness.fertiliser` = `true` will be aggregated together. If a Cycle has `completeness.fertiliser` = `false`, the fertiliser data from that Cycle will not be aggregated, but data from that Cycle for other completeness areas which are true will be aggregated. This approach allows the pooling of data from many incomplete Cycles to create an overall complete dataset.\n- Blank values occur for two reasons. One is that the user has uploaded a data item with a blank value. The other is that a data item exists in one underlying Cycle but not another. For example, Cycle A has the input `Urea (kg N)` with `value` = `70`, but Cycle B does not have the input `Urea (kg N)` but does have `completeness.fertiliser` = `TRUE`. This means Cycle B effectively has a blank value for the input `Urea (kg N)`.\n- For blank values with an associated completeness area, e.g., `fertiliser`, if the area is complete, any blank values within this completeness area will be treated as having `value` = `0`. If the area is incomplete, the blank values will be skipped.\n- For blank values without an associated completeness area, e.g., `measurement`, the general rule is that any blank values will be skipped. There are exceptions to this detailed in the Percentage terms section.\n\n## Calculation of aggregated values\n\n- Generally, an aggregated value for a data item is a simple mean of the values in the underlying cycles. For example, if there are three underlying cycles with the input `Urea (kg N)` and `value` : `20`, `30`, and `90`, the aggregated `value` for the input `Urea (kg N)` would be `(10 + 20 + 90)/3` = `40.` \n- There are two key exceptions to this, one for the `primaryProduct` in `crop` aggregations, where values are adjusted to the same `Dry matter` before the mean is calculated. The other is when there are weights to consider, and a weighted mean is calculated. For example, weights of country production are used for the world aggregations, and irrigation/organic weightings are used for the `crop` aggregations. More detail on these exceptions can be found in the pages for the relevant `termType`.\n\n## Products\n\n- Cycles without a `value` for the `primaryProduct` are not included in aggregations, this is mainly to exclude experimental data that has been collected for purposes other than yield measurement. However, Cycles with `value` = `0` for the `primaryProduct` are included in the aggregation, this is to take into account crop failures and the immature years of permanent crops.\n- Even if the product completeness area is marked as incomplete, the value of the `primaryProduct` is still aggregated. This is to reduce data loss and to improve the yield estimate.\n- `economicValueShare` is only aggregated for the `primaryProduct`, and includes `values` from cycles with `completeness.product` = `FALSE`. However, it excludes Cycles where the product `value` is `0`. There is an example below of the aggregation of product `value` and `economicValueShare`.\n\n**Full 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## Practices\n\n### Percentage terms\n\n- For data items that have percentage units and are in a `sumIs100Group`, for example `waterRegime`,values are only used 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- For `system` and `standardsAndLabels` data items that are not in a `sumIs100Group`, e.g., `Smallholder system`, blank values in Cycles are treated as having `0` value. This follows the same assumption used for splitting Cycles into `organic`/`conventional`, where Cycles without the practice `organic` are treated as `conventional`, i.e., having `value` = `0` for the `Organic` practice.\n\n### Number terms\n\n- For data items with number units, e.g., `number` or `days`, blank values in Cycles are skipped. This is because for the majority of these terms, the gap-fill for a missing value should not be a `0`, for example with `cropping duration`.\n\n### Boolean terms\n\n- Data items with boolean units, e.g., `Inorganic Nitrogen fertiliser used`, are not included in aggregations.\n\n## Emissions\n\n- Emissions are aggregated from the underlying Cycles, rather than being calculated from the aggregated Cycle. This is because emissions models take into account more information than is aggregated. For example, by considering specific dates or practices with boolean values. This also means user uploaded emissions can be included in the aggregation.\n\n### Tier 1 and Tier 2 emissions\n\n- For a particular emission, when all the underlying Cycles have the same `methodTier`, `tier 1` or `tier 2`, the aggregated emission will have the same `methodTier` in the aggregation. If the underlying Cycles have different `methodTier`, all tier 1 and 2 emissions are aggregated together to produce one emission with `methodTier` = `tier 1`. \n\n### Background emissons\n\n- When aggregating background emissions, emissions are filtered based on the completeness of their `inputs`. For example, the background emissions for `diesel` will only be taken into account if `completeness.electricityFuel` = `True`.\n- A `0` `value` is added for Cycles that do not have an emission for a certain `input`, but are complete. For example, if 2 complete Cycles were aggregated, and one had a background emission of `10` for `diesel`, and the other did not have any background emissions for `diesel`, the total would be `(10 + 0)/2` = `5`. \n- This completeness logic also applies to other emissions associated with specific inputs, e.g., `CO2, to air, fuel combustion`.\n\n**Full 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 |\n\n## Site\n\n### Measurement\n\n- Measurements are aggregated at the depth intervals, `depthUpper` and `depthLower`, of the measurements in the underlying cycles. These can be viewed by clicking the `value` of a measurement. The `value` is a weighted average of the measurements at the different depth intervals.\n\n### Management\n\n- To aggregate site management, all the data items with dates that fall within the aggregation period are first averaged, and then given new start dates based on the aggregation period. For example, if the period is `2010-2025`, the new `startDate` would be `01-01-2010` and the new `endDate` would be `31-12-2025`.\n- The same method is used to aggregate the management terms that fall into previous aggregation periods.\n\n## Impact Assessment\n\n - During an aggregation, the impact assessment is recalculated using the aggregated Cycle, using the same method as any other Impact Assessment on the platform is calculated."}

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

@@ -1 +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."}
+{"tags":{},"content":"# Processed food aggregation\n\nThe parts of the aggregation process that are specific to `processedFood` products.\n\n## Aggregation stages\n\nAggregations for the food processing stage can either be generated at the global level (to maximimise data volume) or the country level. For example, if an aggregation for `Wheat flour (whole)` in `Italy` was triggered with the option to use global processing data, all Cycles describing flour milling, regardless of their region, are combined into one global milling aggregation. The background data in the aggregation (e.g., related to the `crop` that is processed, or related to the electricity production) are replaced with country-specific values. This is allowed because food processing can be relatively similar in terms of its inputs and products in different countries, whereas the impacts of the agricultural inputs and energy can differ significantly. If sufficient country-level processing data is available, the aggregation can be triggered to use this region-specific data.\n\nThe aggregation process is as follows:\n1. When an aggregation is triggered to not use global processing data, all public Cycles that have the `processedFood` as a `primaryProduct` for the country specified are gathered. If it is triggered to use global processing data, all Cycles are gathered regardless of their country.\n2. Cycles are then filtered to those that have a specific list of inputs, based on the [aggregationInputTermIds](/glossary/lookups/processedFood.csv) lookup. For this list of inputs, a HESTIA verified aggregation will be used to fill in the background emissions.\n3. The Cycles are rescaled to 1kg of the `primaryProduct` (more detail below) and then aggregated.\n4. All background emissions are removed from the aggregated Cycle.\n5. The background emissions are recalculated using country-specific data. For the `crop`/`processedFood` inputs, the verified aggregations for the same `period` are used for the background emissions. If no verified aggregation is available for the specified `period`, then the next closest `period` is used. \n6. The impact assessments are then recalculated.\n\n## Rescaling\n\n- All `inputs`, `products`, and `emissions` are rescaled to be relative to 1kg of the `primaryProduct`. In `practices`, only `operation` data items are rescaled."}

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

@@ -1 +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."}
+{"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` minimum\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` minimum\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\nhestia-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` minimum\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\nVALIDATE_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/data-validation/content.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# HESTIA Data Validation\n\nSee the complete list of validations available on the HESTIA format.\n\nEach validation is divided by node type: `Cycle`, `Site`, `ImpactAssessment`, and `Organisation`."}

package/dist/content/guide/data-validation/cycle.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# Cycle validation\n\nHere is the list of validations running on a [Cycle](/schema/Cycle).\n\n## <a href=\"./#validate_functionalUnit_not_1_ha\">Validate functionalUnit</a>\n\nThis validation prevents using `1 ha` as a `functionalUnit` when the `siteType` is:\n- `agri-food processor`;\n- `retailer`.\n\n## <a href=\"./#validate_cycle_dates\">Validate Cycle Dates</a>\n\nThis validation ensures two things:\n1. The `endDate` must be later than `startDate`;\n2. The date format of `endDate` must be the same as `startDate`.\n\n## <a href=\"./#validate_sum_aboveGroundCropResidue\">Validate total of above ground crop residue</a>\n\nIf the Cycle contains `aboveGroundCropResidueTotal` and any of:\n- `aboveGroundCropResidueBurnt`\n- `aboveGroundCropResidueIncorporated`\n- `aboveGroundCropResidueLeftOnField`\n- `aboveGroundCropResidueRemoved`\n\nThen the total must be euqal to the sun of the other terms.\n\n## <a href=\"./#validate_crop_residue_complete\">Validate crop residue when it is marked as complete</a>\n\nWhen `cropResidue` is marked as complete, this validation will make sure that these terms are specified:\n- at least one `cropResidueManagement` practice;\n- the sum of \"above ground crop residue\" products is > 0;\n- and the \"below ground crop residue\" is specified.\n\nIf any of these conditions fail, then the `cropResidue` should not be set as complete.\n\n## <a href=\"./#validate_crop_residue_incomplete\">Validate crop residue when it is marked as incomplete</a>\n\nWhen `cropResidue` is marked as complete, this validation will check if these terms are specified:\n- at least one `cropResidueManagement` practice;\n- the sum of \"above ground crop residue\" products is > 0;\n- and the \"below ground crop residue\" is specified.\n\nIf any of these conditions apply, then the `cropResidue` should be set as complete, and a warning will be given.\n\n## <a href=\"./#validate_cycleDuration\">Validate cycleDuration</a>\n\nWhen the `startDate` and `endDate` of the Cycle are provided, the `cycleDuration` must be equal to the difference in days.\n\n## <a href=\"./#validate_maximum_cycleDuration\">Validate the cycleDuration</a>\n\nThis validation verifies the `cycleDuration` provided in the Cycle is not greater than our `maximumCycleDuration` lookup.\n\n## <a href=\"./#validate_riceGrainInHuskFlooded_minimum_cycleDuration\">Validate \"Rice, grain (in husk), flooded\" has a plausible cycleDuration</a>\n\nUsing the lookup `Rice_croppingDuration_days_min`, this validation will make sure that the `cycleDuration` specified in the Cycle is not below this minimum duration.\n\nNote: the minimum duration depends on the `country` specified on the Site.\n\n## <a href=\"./#validate_crop_siteDuration\">Validate siteDuration for crop only</a>\n\nThis validations ensures that for crop production cycles, if the user sets `siteDuration`, it is only equal to `cycleDuration` when `startDateDefinition = harvest of previous crop`.\n\n## <a href=\"./#validate_siteDuration\">Validate siteDuration with otherSites</a>\n\nRun multiple validation when `otherSites` is specified:\n- If there is a single site, then `siteDuration` == `cycleDuration`.\n- If there is more than one site, then `siteDuration` != `cycleDuration`.\n- If there is more than one site, then `sum(siteDuration, otherSitesDuration)` == `cycleDuration`.\n- There must be as many `otherSites` as `otherSitesDuration`.\n\n## <a href=\"./#validate_durations\">Validate otherSitesDuration and otherSitesArea</a>\n\nThis validation will encourage the user to add the following fields, for a `relative` `functionalUnit` Cycle:\n- `siteDuration`\n- `siteArea`\n- `otherSitesDuration` (when `otherSites` is set)\n- `otherSitesArea` (when `otherSites` is set)\n\n## <a href=\"./#validate_possibleCoverCrop\">Validate using crop as a cover crop</a>\n\nThis validation prevents using a `crop` Product, set as a \"cover crop\" (Practice), that can not be a crover crop. To fix this error, the Product or the Practice needs to be adjusted. This uses the lookup `possibleCoverCrop` on the Product to check if the Product can be a cover crop.\n\n## <a href=\"./#validate_set_treatment\">Validate using treatment with experimentDesign</a>\n\nWhen `experimentDesign` is used, this will encourage the user to set `treatment` as well.\n\n## <a href=\"./#validate_products_animals\">Validate using both liveAnimal and animalProduct products</a>\n\nThis validation will show a warning when both `liveAnimal` and `animalProduct` are added to the Cycle.\n\n## <a href=\"./#validate_stocking_density\">Validate Stocking density</a>\n\nIncite users to add the practice \"Stocking density\" when:\n- the `functionalUnit` is `relative`;\n- the Cycle occurs on `permanent pasture`;\n- the Cycle contains a list of `animals` as `liveAnimal` or `animalProduct`.\n\n## <a href=\"./#validate_linked_impact_assessment\">Validate that every product that should have an ImpactAssessment, actually has one.</a>\n\nIn some cases, the same product could be added multiple times with different unique properties, in which case an ImpactAssessment should exist for each.\n\nNote: on HESTIA, Impact Assessments are automatically generated during upload.\n\n## <a href=\"./#validate_animal_product_mapping\">Validate mapping between the liveAnimal in the Animal blank nodes, and the Cycle Product as animalProduct.</a>\n\nThis validation makes sure that the `liveAnimal` added as `Animal` have a corresponding `animalProduct` in the Cycle `products`.\n\n## <a href=\"./#validate_requires_substrate\">Validate substrate inputs</a>\n\nThis validation ensures that the `substrate` Inputs are added to the Cycle when the `siteType` = `glass or high accessible cover`, and a \"substrate\" practice has been set.\n\n## <a href=\"./#validate_list_min_max_lookup\">Validate the minimum and maximum value of a list of blank nodes, based on lookup values</a>\n\nFor some Terms, HESTIA has defined some minimum and maximum value. If the specified `value` does not fall within these, an error is raised.\n\n## <a href=\"./#validate_list_term_percent\">Validates the percentage of blank nodes</a>\n\nFor all Terms that are in percentages, the value must be between `0` and `100`.\n\n## <a href=\"./#validate_list_sum_100_percent\">Validate a group of blank nodes must sum to 100%</a>\n\nSome Terms are part of a group from the lookup `sumIs100Group`, meaning when summed up, their total value must be exactly `100%` (with a 5% tolerance).\n\n## <a href=\"./#validate_list_percent_requires_value\">Validate the value of some blank nodes when the units is a percentage</a>\n\nFor all Terms that are set as percentages, the `value` must be provided.\n\n## <a href=\"./#validate_list_valueType\">Validate the type of the value of blank nodes</a>\n\nUsing the lookup \"valueType\", this validation will make sure the provided value is of the correct type. Example: a Term that should be either True or False will only accept True/False value.\n\n## <a href=\"./#validate_empty_fields\">Validates empty fields</a>\n\nThis validation returns warnings when fields are added without a value (or using 'no data' for example).\n\n## <a href=\"./#validate_linked_source_privacy\">Validate the privacy of 2 linked Nodes</a>\n\nWhen adding a Source to a Cycle or an ImpactAssessment, this validation ensures that the same level of privacy is used on both.\n\nExample:\n- if the Cycle is set as `dataPrivate`=`true`, the Source it is linked to must also be `dataPrivate`=`true`;\n- if the Cycle is set as `dataPrivate`=`false`, the Source it is linked to must also be `dataPrivate`=`false`.\n\n## <a href=\"./#validate_list_model_config\">Validates a list using the engine models.</a>\n\nThis method uses a configuration to determine which `term` in the elements should run. It does not use the `methodModel` that could be found on each element.\n\n## <a href=\"./#validate_duplicated_term_units\">Validate multiple terms used with different units</a>\n\nSome of the terms in the Glossary have been added with different units, e.g., `kg` / `kg N` / `kg VS`. This validation returns a warning when those terms have been used together in the same Node.\n\n## <a href=\"./#validate_other_model\">Validate usage of \"Other model\"</a>\n\nThe \"Other model\" Term has been added in the eventuality that HESTIA has not added the required model yet. However, to use this Term, the `methodModelDescription` must be set.\n\n## <a href=\"./#validate_nested_existing_node\">Validate when a non-indexed node references indexed nodes</a>\n\nWhen uploading Cycle, Site, etc., the referenced nodes must also be uploaded. Example:\n- if the uploaded Cycle references an existing Site, a warning will be given;\n- if the uploaded Cycle references an uploaded Site, no warning is given.\n\n## <a href=\"./#validate_linked_impactAssessment\">Validate inputs impactAssessment links</a>\n\nThis validation makes sure that some inputs, mapped by the lookup `aggregationInputTermIds` on the primary product, have a corresponding `impactAssessment` linked to them. This validation can throw an error in the following cases:\n- no Impact Assessment has been found for this Input;\n- some Impact Assessment exist for the Input, but it has not been verified;\n- the lookup `aggregationInputTermIds` has not been set correctly. Please verify the primary product of the Cycle,\nand make sure the lookup `aggregationInputTermIds` has been set correctly.\n\n## <a href=\"./#validate_id\">Validate aggregated node id</a>\n\nValidate the node `id` has been correctly formatted. If this validation fails, it indicates an error in the aggregation engine, and an issue must be raised.\n\n## <a href=\"./#validate_duplicated_feed_inputs\">Validate feed inputs are not duplicated</a>\n\nThis validation ensures that the same Input marked with `isAnimalFeed` are not added in both `inputs` and `animals`.\n\n## <a href=\"./#validate_has_pregnancyRateTotal\">Validate specifying the pregnancy rate</a>\n\nUsing the lookup `productTermIdsAllowed` on the Term `pregnancyRateTotal`, this validation will recommend the user to add the property `pregnancyRateTotal` on the Animal blank node.\n\n## <a href=\"./#validate_method_not_relevant\">Validate using the emissionNotRelevant model</a>\n\nThe model `emissionNotRelevant` is reserved for the model `emissionNotRelevant`. This validation will therefore raise a warning when it is being used, and the `methodModel` should be replaced.\n\n## <a href=\"./#validate_methodTier_not_relevant\">Validate using the not relevant methodTier</a>\n\nThe methodTier `not relevant` is reserved for the model `emissionNotRelevant`. This validation will therefore raise a warning when it is being used, and the `methodTier` should be replaced.\n\n## <a href=\"./#validate_methodTier_background\">Validate methodTier for background emissions</a>\n\nOnly specific emissions can use the `methodTier`=`background`. For all emissions that are not allowed to use it, this validation will throw an error, and another `methodTier` must be used instead. Example of emission that can use it: `CO2, to air, inputs production`.\n\n## <a href=\"./#validate_waterRegime_rice_products\">Validate corresponding waterRegime practices with Rice products</a>\n\nThis validation ensures that the correct `waterRegime` practice can be used with the specified Rice product.\n\n## <a href=\"./#validate_croppingDuration_riceGrainInHuskFlooded\">Validate \"Rice, grain (in husk), flooded\" cropping duration</a>\n\nWhen \"Rice, grain (in husk), flooded\" is used as a product, this validation will check the practice `croppingDuration`, and make sure the value is between `Rice_croppingDuration_days_min` and `Rice_croppingDuration_days_max` lookup values.\n\n## <a href=\"./#validate_landCover_match_products\">Validate that at least one landCover practice matches an equivalent Product</a>\n\nWhen adding a `landCover` Practice to a Cycle, the Practice must match a Product. We use the lookup `landCoverTermId` on existing Products to match the 2 together. If no correspondance is found, an error is shown.\n\n## <a href=\"./#validate_practices_management\">Validate Cycle Practices and Site Management</a>\n\nThis validation is to ensure that the same Management and Practices added on the Site and related Cycles, with the same `term` and `startDate` + `endDate`, have the same `value`. Since HESTIA will automatically gap-fill the Management node from the Cycle, removing them will fix this error.\n\n## <a href=\"./#validate_irrigated_complete_has_inputs\">Validate irrigated Cycles with complete water have water inputs</a>\n\nWhen the Cycle `water` completeness is set to `True`, and \"irrigation\" practices are used, there must be at least 1 Input of `termType`=`water`. Otherwise, the completeness should be marked as `False`."}

package/dist/content/guide/data-validation/impact-assessment.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# Impact Assessment validation\n\nHere is the list of validations running on a [Impact Assessment](/schema/ImpactAssessment).\n\n## <a href=\"./#validate_list_min_max_lookup\">Validate the minimum and maximum value of a list of blank nodes, based on lookup values</a>\n\nFor some Terms, HESTIA has defined some minimum and maximum value. If the specified `value` does not fall within these, an error is raised.\n\n## <a href=\"./#validate_list_term_percent\">Validates the percentage of blank nodes</a>\n\nFor all Terms that are in percentages, the value must be between `0` and `100`.\n\n## <a href=\"./#validate_list_sum_100_percent\">Validate a group of blank nodes must sum to 100%</a>\n\nSome Terms are part of a group from the lookup `sumIs100Group`, meaning when summed up, their total value must be exactly `100%` (with a 5% tolerance).\n\n## <a href=\"./#validate_list_percent_requires_value\">Validate the value of some blank nodes when the units is a percentage</a>\n\nFor all Terms that are set as percentages, the `value` must be provided.\n\n## <a href=\"./#validate_list_valueType\">Validate the type of the value of blank nodes</a>\n\nUsing the lookup \"valueType\", this validation will make sure the provided value is of the correct type. Example: a Term that should be either True or False will only accept True/False value.\n\n## <a href=\"./#validate_empty_fields\">Validates empty fields</a>\n\nThis validation returns warnings when fields are added without a value (or using 'no data' for example).\n\n## <a href=\"./#validate_linked_source_privacy\">Validate the privacy of 2 linked Nodes</a>\n\nWhen adding a Source to a Cycle or an ImpactAssessment, this validation ensures that the same level of privacy is used on both.\n\nExample:\n- if the Cycle is set as `dataPrivate`=`true`, the Source it is linked to must also be `dataPrivate`=`true`;\n- if the Cycle is set as `dataPrivate`=`false`, the Source it is linked to must also be `dataPrivate`=`false`.\n\n## <a href=\"./#validate_list_model_config\">Validates a list using the engine models.</a>\n\nThis method uses a configuration to determine which `term` in the elements should run. It does not use the `methodModel` that could be found on each element.\n\n## <a href=\"./#validate_duplicated_term_units\">Validate multiple terms used with different units</a>\n\nSome of the terms in the Glossary have been added with different units, e.g., `kg` / `kg N` / `kg VS`. This validation returns a warning when those terms have been used together in the same Node.\n\n## <a href=\"./#validate_other_model\">Validate usage of \"Other model\"</a>\n\nThe \"Other model\" Term has been added in the eventuality that HESTIA has not added the required model yet. However, to use this Term, the `methodModelDescription` must be set.\n\n## <a href=\"./#validate_nested_existing_node\">Validate when a non-indexed node references indexed nodes</a>\n\nWhen uploading Cycle, Site, etc., the referenced nodes must also be uploaded. Example:\n- if the uploaded Cycle references an existing Site, a warning will be given;\n- if the uploaded Cycle references an uploaded Site, no warning is given.\n\n## <a href=\"./#validate_method_not_relevant\">Validate using the emissionNotRelevant model</a>\n\nThe model `emissionNotRelevant` is reserved for the model `emissionNotRelevant`. This validation will therefore raise a warning when it is being used, and the `methodModel` should be replaced.\n\n## <a href=\"./#validate_methodTier_not_relevant\">Validate using the not relevant methodTier</a>\n\nThe methodTier `not relevant` is reserved for the model `emissionNotRelevant`. This validation will therefore raise a warning when it is being used, and the `methodTier` should be replaced.\n\n## <a href=\"./#validate_methodTier_background\">Validate methodTier for background emissions</a>\n\nOnly specific emissions can use the `methodTier`=`background`. For all emissions that are not allowed to use it, this validation will throw an error, and another `methodTier` must be used instead. Example of emission that can use it: `CO2, to air, inputs production`.\n\n## <a href=\"./#validate_characterisedIndicator_model\">Validate methodModel used by the Indicator</a>\n\nSome `characterisedIndicator` Terms can only be used with specific `model`. This validation uses the lookup [characterisedIndicator-model-mapping.csv](/glossary/lookups/characterisedIndicator-model-mapping.csv) to verify if it is valid."}

package/dist/content/guide/data-validation/organisation.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# Organisation validation\n\nHere is the list of validations running on a [Organisation](/schema/Organisation).\n\n## <a href=\"./#validate_organisation_dates\">Validate Organisation Dates</a>\n\nThis validation ensures that the `endDate` must be later than `startDate`.\n\n## <a href=\"./#validate_list_min_max_lookup\">Validate the minimum and maximum value of a list of blank nodes, based on lookup values</a>\n\nFor some Terms, HESTIA has defined some minimum and maximum value. If the specified `value` does not fall within these, an error is raised.\n\n## <a href=\"./#validate_list_term_percent\">Validates the percentage of blank nodes</a>\n\nFor all Terms that are in percentages, the value must be between `0` and `100`.\n\n## <a href=\"./#validate_list_sum_100_percent\">Validate a group of blank nodes must sum to 100%</a>\n\nSome Terms are part of a group from the lookup `sumIs100Group`, meaning when summed up, their total value must be exactly `100%` (with a 5% tolerance).\n\n## <a href=\"./#validate_list_percent_requires_value\">Validate the value of some blank nodes when the units is a percentage</a>\n\nFor all Terms that are set as percentages, the `value` must be provided.\n\n## <a href=\"./#validate_list_valueType\">Validate the type of the value of blank nodes</a>\n\nUsing the lookup \"valueType\", this validation will make sure the provided value is of the correct type. Example: a Term that should be either True or False will only accept True/False value.\n\n## <a href=\"./#validate_empty_fields\">Validates empty fields</a>\n\nThis validation returns warnings when fields are added without a value (or using 'no data' for example).\n\n## <a href=\"./#validate_linked_source_privacy\">Validate the privacy of 2 linked Nodes</a>\n\nWhen adding a Source to a Cycle or an ImpactAssessment, this validation ensures that the same level of privacy is used on both.\n\nExample:\n- if the Cycle is set as `dataPrivate`=`true`, the Source it is linked to must also be `dataPrivate`=`true`;\n- if the Cycle is set as `dataPrivate`=`false`, the Source it is linked to must also be `dataPrivate`=`false`.\n\n## <a href=\"./#validate_list_model_config\">Validates a list using the engine models.</a>\n\nThis method uses a configuration to determine which `term` in the elements should run. It does not use the `methodModel` that could be found on each element.\n\n## <a href=\"./#validate_duplicated_term_units\">Validate multiple terms used with different units</a>\n\nSome of the terms in the Glossary have been added with different units, e.g., `kg` / `kg N` / `kg VS`. This validation returns a warning when those terms have been used together in the same Node.\n\n## <a href=\"./#validate_other_model\">Validate usage of \"Other model\"</a>\n\nThe \"Other model\" Term has been added in the eventuality that HESTIA has not added the required model yet. However, to use this Term, the `methodModelDescription` must be set.\n\n## <a href=\"./#validate_nested_existing_node\">Validate when a non-indexed node references indexed nodes</a>\n\nWhen uploading Cycle, Site, etc., the referenced nodes must also be uploaded. Example:\n- if the uploaded Cycle references an existing Site, a warning will be given;\n- if the uploaded Cycle references an uploaded Site, no warning is given."}

package/dist/content/guide/data-validation/site.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# Site validation\n\nHere is the list of validations running on a [Site](/schema/Site).\n\n## <a href=\"./#validate_cycle_dates\">Validate multiple Cycles with identical dates related to the same Site</a>\n\nThis validation prevents connecting multiple Cycles to the same Site, during the same period. If multiple products are being produced on the same Site, they should be added together in the same Cycle. Otherwise, different Site must be used.\n\nNote: this applies to the Cycles linked with `.site` and `.otherSites`.\n\n## <a href=\"./#validate_list_min_max_lookup\">Validate the minimum and maximum value of a list of blank nodes, based on lookup values</a>\n\nFor some Terms, HESTIA has defined some minimum and maximum value. If the specified `value` does not fall within these, an error is raised.\n\n## <a href=\"./#validate_list_term_percent\">Validates the percentage of blank nodes</a>\n\nFor all Terms that are in percentages, the value must be between `0` and `100`.\n\n## <a href=\"./#validate_list_sum_100_percent\">Validate a group of blank nodes must sum to 100%</a>\n\nSome Terms are part of a group from the lookup `sumIs100Group`, meaning when summed up, their total value must be exactly `100%` (with a 5% tolerance).\n\n## <a href=\"./#validate_list_percent_requires_value\">Validate the value of some blank nodes when the units is a percentage</a>\n\nFor all Terms that are set as percentages, the `value` must be provided.\n\n## <a href=\"./#validate_list_valueType\">Validate the type of the value of blank nodes</a>\n\nUsing the lookup \"valueType\", this validation will make sure the provided value is of the correct type. Example: a Term that should be either True or False will only accept True/False value.\n\n## <a href=\"./#validate_empty_fields\">Validates empty fields</a>\n\nThis validation returns warnings when fields are added without a value (or using 'no data' for example).\n\n## <a href=\"./#validate_linked_source_privacy\">Validate the privacy of 2 linked Nodes</a>\n\nWhen adding a Source to a Cycle or an ImpactAssessment, this validation ensures that the same level of privacy is used on both.\n\nExample:\n- if the Cycle is set as `dataPrivate`=`true`, the Source it is linked to must also be `dataPrivate`=`true`;\n- if the Cycle is set as `dataPrivate`=`false`, the Source it is linked to must also be `dataPrivate`=`false`.\n\n## <a href=\"./#validate_list_model_config\">Validates a list using the engine models.</a>\n\nThis method uses a configuration to determine which `term` in the elements should run. It does not use the `methodModel` that could be found on each element.\n\n## <a href=\"./#validate_duplicated_term_units\">Validate multiple terms used with different units</a>\n\nSome of the terms in the Glossary have been added with different units, e.g., `kg` / `kg N` / `kg VS`. This validation returns a warning when those terms have been used together in the same Node.\n\n## <a href=\"./#validate_other_model\">Validate usage of \"Other model\"</a>\n\nThe \"Other model\" Term has been added in the eventuality that HESTIA has not added the required model yet. However, to use this Term, the `methodModelDescription` must be set.\n\n## <a href=\"./#validate_nested_existing_node\">Validate when a non-indexed node references indexed nodes</a>\n\nWhen uploading Cycle, Site, etc., the referenced nodes must also be uploaded. Example:\n- if the uploaded Cycle references an existing Site, a warning will be given;\n- if the uploaded Cycle references an uploaded Site, no warning is given.\n\n## <a href=\"./#validate_cycles_overlap\">Prevent overlap between management dates and cycle dates</a>\n\nHESTIA will gap-fill `Management` data from the related Cycles of a Site. Adding data on the same dates of those Cycles could lead to double-counting. We will use the first Cycle `startDate`, or `endDate` - `cycleDuration`, or `endDate` - `maximumCycleDuration` lookup to determine the earliest start date of the gap-filling, and prevent using Management dates that are later than this date. You can make sure this error is not triggered by:\n- removing any Management node that describes the Cycles;\n- using day precision for the Management nodes and the Cycle `startDate` / `endDate` (e.g., `2000-01-01`);\n- making sure the `startDate` or `cycleDuration` of the first Cycle is set (so we don't use `maximumCycleDuration`)."}

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

@@ -0,0 +1 @@
+{"tags":{},"content":"# Core concepts\n\nThis page describes the core concepts when uploading data on HESTIA.\n\n1. Nodes: data in HESTIA is split into nodes and all your data has to fit into one or more of these nodes. Each node has a unique identifier. If the node has already been indexed on the platform, the identifier is `@id` (e.g., `cycle.@id` ). If the node has not been indexed on the platform and you are creating it for the first time, the identifier is `id` in your upload file. You must link your nodes using identifiers (e.g., `cycle.site.id` links a Cycle to a Site).\n2. Glossary of Terms: to support data harmonization sharing we have built a Glossary of Terms containing standard names for things in the agri-food system. Data uploaded must use these Terms . You can suggest new terms here . You can refer to Terms in your upload file using their `@id` or `name`.\n3. Default Units: each Term defines the units that any data must be in (e.g., kilograms of nitrogen). Note that for terms with percentages as units, values should be on a `0` to `100` scale (e.g., `86` for 86%, not `0.86`).\n4. Data Completeness: there are thousands of possible items in the food system, and it would be impractical to create a big database with thousands of items in it and many zeros next to the items that were not used or produced. Therefore, you only need to add data describing things that were used or produced during the Cycle, and then state whether your data are a complete representation of the production Cycle by filling in a Completeness assessment.\n5. Private data: nodes can be marked as `private`, which means they can be uploaded but will only be visible to you, anyone you share the file with, and platform admins."}

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

@@ -0,0 +1 @@
+{"tags":{},"content":"# Deleting indexed data\n\nLearn how to remove data you uploaded on HESTIA.\n\nIf, for any reason, you need to delete data after it has been indexed on the platform, you can email <a mailto=\"community@hestia.earth\">community@hestia.earth</a>. Please provide the identifiers or URLs of the nodes you want removing."}

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

@@ -0,0 +1 @@
+{"tags":{},"content":"# Example uploads\n\nFind some example uploads to get you started."}

package/dist/content/guide/file-upload/examples/example-1.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# A survey of maize-pigeon pea farms in Myanmar\n\n## Dataset\n\nThe [Food Security Policy Project](https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/HLJRHJ) surveyed 935 farms in the southern Shan region of Myanmar in June-October 2018. These farms cultivated maize and/or pigeon peas often using intercropping. Data were captured by interviewing farmers and asking them to recall information about the prior production cycle(s). Data were stored in an Excel spreadsheet after removing personally identifying information such as coordinates.\n\n## Conversion steps\n\n* We added a new row in the Excel sheet below the existing column headers. In this row, we added field names from the schema.\n* We restructured the dataset so each row represents one Cycle. Cycles where maize and pigeon peas were intercropped had two Products.\n* The surveyed farms had already been given a unique identifier, and we used these for `site.id` and `cycle.id`. We then linked cycles to the sites they occurred on using `cycle.site.id`.\n* Added new columns for the data Source, and added bibliographic information to it. Set this as the `defaultSource` for all Cycles and Sites.\n* Added the required fields for Cycles and Sites which were not included in the original spreadsheet. Specifically, we added `endDate` and `functionalUnit` to the Cycle, and `country.name` and `siteType` to the Site.\n* Added a new column called `site.region.name` and matched each of the townships surveyed with the most specific geographical region in the HESTIA Glossary.\n* For each Input and Product, converted the units to those defined in the HESTIA glossary (e.g., kilograms), and then expressed them per functional unit defined by the schema (here `1 ha`).\n* Requested new Terms were added to the Glossary to allow better representation of the data (e.g., Family labour, and Hired labour).\n* Added columns for the data Completeness assessment and filled them in based on the rules defined at https://hestia.earth/schema/Completeness.\n* Initially we set `dataPrivate` to `true` for all nodes, so we could check the data first without it becoming public. When we were ready to share the data publicly, we reuploaded with `dataPrivate` set to `false` .\n\n## Validation\n\nThe upload pipeline detected fields and terms had typos in which we corrected. A full stop symbol (.) was mistakenly used to mark data as not available, and we changed this to a dash (-) which represents no data in HESTIA along with blank cells.\n\n## Downloads\n\n* [Original dataset](https://cdn.hestia.earth/examples/Food%20Security%20Policy%20Project%20(2020)%20Maize%20and%20pigeon%20peas_original.xlsx)\n* [Dataset in HESTIA format](https://cdn.hestia.earth/examples/MaizePigeonPea_reformatted.xlsx)\n* [Data in the Explorer](https://www.hestia.earth/explorer/search?type=Sources&sortBy=relevance&sortOrder=desc&query=Food%20Security%20Policy%20Project%20(2020))"}

package/dist/content/guide/file-upload/examples/example-2.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# A nitrate and ammonia leaching meta-analysis### Dataset\n\nA [meta-analysis](https://dx.doi.org/10.1126/science.aaq0216) consolidated data from 91 studies representing 559 observation of nitrate and ammonium leaching under cropland. The dataset includes possible covariates of leaching such as rainfall and crop yield.\n\n## Conversion steps\n\nWe used the steps as described in the Myanmar example, with the following additional steps:\n\n* To each Source, we only added the title of the article (`bibliography.title`) and/or the DOI (`bibliography.documentDOI`) and let the HESTIA pipeline add the rest of the bibliographic items automatically from the Mendeley library.\n* To each Source, we also added a `metaAnalysisBibliography`.\n* In the meta-analysis, crop yield was expressed as kilograms of dry matter, however in the HESTIA Glossary crops are expressed in kilograms of marketable weight (e.g., `Maize, grain` has a default dry matter of 85.8%). Therefore, to each crop Product we added the Property `Dry matter` from the Glossary with the value 100%. Adding a Property to a blank node overrides the default Property from the Glossary.\n* Some fertilisers were controlled release, or included nitrification or urease inhibitors, and this was specified by adding a Property to the fertiliser.\n* Soil Measurements had defined depth intervals, and these were added using `depthUpper` and `depthLower`.\n* Some Measurements had different Sources to the `defaultSource` of the Site (e.g., a prior study on the same Site may have reported the soil pH), and these were specified for each Measurement, creating a new `source.id` if necessary.\n* Emissions have required fields for `methodModel` and `methodTier`. The method or model used to quantify emissions can change the result and this is a critical field to record, and we identified the correct `methodModel` in the Glossary for each Emission. Methods and models can also be broadly grouped by their specificity and `methodTier` and the value for these Emissions is `measured`.\n\n## Validation\n\nThe bibliographies for seven studies were not available automatically and these were entered manually. Some coordinates were identified as being in the wrong country or region, and these were corrected (either by referring to the original study if the error was in the meta-analysis, or by using other site location data in the original study instead if the error was there). Some more coordinates were identified as erroneous where they did not intersect with known cropland (according to the MODIS land cover map) and some of these were corrected but others were accepted based on visual inspection of high-resolution satellite images. Some estimates of above ground crop residue were automatically identified as too high, were found to include below ground residue, and were corrected.\n\n## Downloads\n\n* [Dataset in HESTIA format](https://cdn.hestia.earth/examples/Poore%20and%20Nemecek%20(2018)%20Nitrate%20Leaching%20-%20Reformatted.xlsx)\n* [Data in the Explorer](https://www.hestia.earth/explorer/search?type=Sources&sortBy=relevance&sortOrder=desc&query=Poore%20%26%20Nemecek%20(2018))"}

package/dist/content/guide/file-upload/examples/example-3.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# A nitrate leaching experiment with time-series data\n\n## Dataset\n\n[Engstrom et al. 2011](https://doi.org/10.1051/agro/2010035) reported results from an experimental field trial in Sweden which assessed the effects of different fertilization levels and crop rotations on nitrate leaching. There were two experiments with nine treatments over two years, resulting in 36 Cycles. Leaching data were provided with monthly frequency. Data were presented in tables and the text.\n\n## Conversion steps\n\nWe largely followed the same steps as the nitrate leaching meta-analysis example, with the following additional steps:\n\n* Data for many Measurements, Inputs, and Emissions were provided as arrays where each value represented the date they occurred on. For upload to HESTIA, arrays can be created in Excel or csv files by separating each value with a semicolon (e.g., `0.443;23.461`). Arrays of associated dates are added in the dates field using the ISO 8601 format (e.g., `2004-09;2004-10`, which represent September 2004 and October 2004 respectively). Missing values in arrays are represented using either a dash or a blank (e.g., `4;-;8, 4;;8`).\n* Long term rainfall and temperature data were provided as the total or average for each month averaged over the period 1961-1990. To represent these data, the `startDate` and `endDate` of the Measurements were specified as 1961 and 1990 respectively. The monthly rainfall and temperature data were added using an array. Arrays of associated dates were added in the dates field using the ISO 8601:2000 format for dates without a year (e.g., `--01;--02;...` , which represent January and February respectively).\n* The values in some arrays are additive (e.g., monthly rainfall sums to annual rainfall), whereas others are not (e.g., monthly temperature averages to annual average temperature). The nitrogen uptake by a plant is an additive over time, which means that the value for each date must be the incremental amount of uptake compared to the previous date. The uptake data in the study were already in this format and were entered directly.\n\n## Validation\n\nSoft validation errors were raised for the twelve rapeseed Cycles recommending that the crop yield was provided, however these data were not available in the study and this error was ignored. Soft validation errors were also raised where soil texture (\"sandy loam\") as provided without a depth interval and based on the article a depth interval of 0-30cm was assigned, and this was corrected.\n\n## Downloads\n\n* [Dataset in HESTIA format (note - these data are part of a larger dataset)](https://cdn.hestia.earth/examples/Poore%20and%20Nemecek%20(2018)%20Nitrate%20Leaching%20-%20Reformatted.xlsx)\n* [Data in the Explorer](https://www.hestia.earth/explorer/search?type=Sources&sortBy=relevance&sortOrder=desc&query=Engstr%C3%B6m%20et%20al%20(2011))"}

package/dist/content/guide/file-upload/examples/example-4.json

@@ -0,0 +1 @@
+{"tags":{},"content":"# An environmental LCA of aquaculture in Peru\n\n## Dataset\n\n[Avadí et al. 2015](https://doi.org/10.1016/j.aquaculture.2014.08.001) assessed the effects of different feeds on the environmental impacts of trout (Oncorhynchus mykiss), tilapia (Oreochromis spp.) and tambaqui (Colossoma macropomum) production in Peru. There was one fish oil and fish meal production Cycle, seven feed blending Cycles, and eight fish production Cycles.\n\n## Conversion steps\n\nWe largely followed the same steps as the Myanmar example, with the following additional steps:\n\n* We created six Sites, two for feed processing in Chile and Peru, one for the trout cage systems, one for the tambaqui pond systems, one for the semi-intensive tilapia system, and one for the intensive tilapia system. Because multiple Sites were surveyed and then aggregated, we specified the `numberOfSites`.\n* We added Infrastructure representing the cages or ponds, and specified the lifespan of the Infrastructure.\n* We created 16 Cycles, linked them to the Sites, and set the functional unit to `relative`. Relative means that the functional unit is defined by the quantity of the Products.\n* The fish processing Cycle creates two Products: fish oil and fish meal. These Products are subsequently used as Inputs into the feed blending Cycles. Cycles cannot be directly linked in HESTIA and must be linked via an Impact Assessment. Therefore, we therefore created the fish processing Cycle with multiple Products, and then created two Impact Assessments for the oil and meal.\n* We created the seven feed blending Cycles and added each Input, its quantity, and the country of origin of each Input. For the fish oil and fish meal, we also linked the Input to the Impact Assessment. We specified the Product of these Cycles as Concentrate feed blend. We used Properties to specify the nutrient composition of the blended feed. We also created seven Impact Assessments for these feed Cycles. The authors provided substantial data to populate these Impact Assessments (such as GHG emissions, ecotoxicity, land occupation) and we added these data.\n* We created the eight aquaculture Cycles and added the Inputs and Products. We linked the Concentrate feed blend Input to the Impact Assessment using `cycle.inputs.0.impactAssessment.id`.\n* The aquaculture Cycles had two Products: fish and excreta. We added them and also added the split between solid and liquid excreta.\n* Following excretion, microorganisms change the mass and composition of excreta, creating Emissions such as NH3 and CH4. A share of that excreta is sedimented at the bottom of the pond and it is often removed and stored in an excreta management system. Here, microorganisms convert it into a different Product again. To represent the transformations of excreta, we added Transformation blank nodes to the Cycles. Specifically, the name of the first Transformation is the first excreta management system, `Excretion into water body`, and the Input is `Excreta, solid and liquid, fish/crustaceans (kg N)`. The second excreta management system was not specified in the paper, so a generic term was used which was `Liquid/Slurry`, and we assumed that the amount sedimented was inputted into that system.\n\n## Validation\n\nThe phosphorus excreted was negative in the study, which was raised as a hard validation error. On inspection of the data the authors were including phosphorus uptake by the fish from sediment and water as a negative amount in the excreta. This should be entered as an Input to the fish, but insufficient data were provided to split the excreta from the uptake, so to resolve this, we simply did not add the phosphorus content of the excreta.\n\n## Downloads\n\n* [Dataset in HESTIA format](https://cdn.hestia.earth/examples/Avadi%20et%20al%20(2015).xlsx)\n* [Data in the Explorer](https://www.hestia.earth/explorer/search?type=Sources&sortBy=relevance&sortOrder=desc&query=Avadi%20et%20al%20(2015))"}

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

@@ -1 +1 @@
-{"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..."}
+{"tags":{},"content":"# Preparing a dataset\n\nThis page contains information and some short videos that walk you though how to prepare your dataset for uploading.\n\n## Structuring the file\n\n* Column headers should follow the following format: `node` + `.` + `field`. For example `cycle.description`.\n* Every node you create must have an identifier. If the node exists in HESTIA, use an `@id` and then use the HESTIA identifier, for example `cycle.inputs.1.term.@id` = `electricityGridMarketMix`. If the data are new, use a temporary `id`, for example `site.id` = `site-1`.\n* Nodes are linked using their identifiers, for example to link a Site to a Cycle, use `site.cycle.id` = `site-1`.\n* To add blank nodes to a node (e.g., Inputs to a Cycle), the column header includes a number for each blank node, for example `cycle.inputs.0.term.name`, `cycle.inputs.0.value`, `cycle.inputs.1.term.name`, `cycle.inputs.1.value`.\n* Avoid rows that contain data but do not have an identifier, or columns that contain data but have no column header.\n* You can use an empty cell or a `-` to indicate no data.\n* To add arrays, separate elements using a `;` (e.g., `cycle.inputs.0.value` = `3;7.2;1.0`)\n\n## Adding Data\n\n### Adding a Source\n\n* We can automatically get bibliographic information for if you provide the `title` of the article or the `documentDOI`. It has to exist in [Mendeley](https://www.mendeley.com) for this to work.\n* If it does not exist in Mendeley, you need to provide all the required bibliographic fields as defined in the schema.\n\n![How to add a Source](/assets/file-upload/prepare-file/source.mp4)\n\n### Adding an Organisation\n\n* You don't need to add an Organisation, but they can be useful to group Sites (e.g., a farm (Organisation) might manage three fields (Sites)).\n\n### Adding a Site\n\n* A Site requires a [`defaultSource`](/Site). Link to the Source you have just added using the `id`.\n* If you added an Organisation, link the Site to the Organisation using the `id`.\n* Add the `siteType` which is a mandatory field (e.g., cropland).\n* Add the `country`, which is a required field. Data must be at least country specific to pass validation.\n* If the data has more geographic specificity than the `country` level, add the `region`. The `region` you specify should be the most specific region available in the Glossary. We use the [GADM database](https://gadm.org/) for our regions.\n* Add the `latitude` and `longitude` if you have them.\n* Add any other fields for which you have data, including Measurements and Infrastructure.\n* For many data items, you can add values as a single value or an array. For arrays, you can use the `dates` field to specify on which date the `value` occurred.\n\n![How to add a Site](/assets/file-upload/prepare-file/site.mp4)\n\n### Adding a Cycle\n\n* A Cycle also requires a `defaultSource`. Link to the Source you added earlier using the `id`.\n* Link the Cycle to the Site you created.\n* A Cycle requires a data Completeness assessment. Refer to the Schema to understand this.\n* Add Inputs, Products, Practices, and Emissions.\n* You can add specific Sources to each Input, Product, Practice, and Emission, if the Source is different to the `defaultSource`.\n\n#### Adding a Transformation:\n\n* The Transformation blank node in HESTIA is used to describe the transformation of one Product to a new Product in the same Cycle. In animal uploads, this blank node is used to display data on how excreta (\"manure\") from animals is managed.\n* There are many management practices used, as per the list of terms in the Glossary. Each transformation should have a unique identifier (a `transformationId`). If excreta is managed in multiple systems within one Cycle, the share of excreta which is managed in each system can be indicated through the `transformedShare`.\n\n### Adding an Impact Assessment\n\n* Impact Assessments can be uploaded without Cycles and Sites, and therefore have more required fields. However, its best practice to upload a corresponding Cycle and Site and link it to the Impact Assessment."}

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

@@ -0,0 +1 @@
+{"tags":{},"content":"# Special upload cases\n\nThis page gives examples of special cases to upload.\n\n## Multiple cropping\n\n* If there are multiple harvests during the same year (excluding the case of successive gathering), a new Cycle should be created for each harvest. This is in line with the [FAO's](http://faostat.fao.org/) approach.\n\n### Successive gathering\n\n* If there is successive gathering from a crop during a year, only one Cycle should be created with one Product for that crop. This again follows the [FAO's](http://faostat.fao.org/) approach.\n* The `value` for the Product can either be the sum of the total harvest in the year, or an array in which each value in the array represents a gathering event.\n\n### Failed or unharvested crops\n\n* If crops are not harvested, e.g., due to crop disease or changing market conditions, the Site area should not change and is recorded as normal, and this represents the area cultivated or sown.\n* Area harvested should also be specified, as this will either be zero in cases of no harvest or less than area under cultivation in cases of partial harvest. Crop yield should be specified and set to zero if the crop failed completely or was not harvested. This also follows the [FAO's](https://www.fao.org/faostat/en/#data/QCL/metadata) approach.\n\n### Short fallows and similar cases\n\n* Periods between the harvest of one crop and sowing of another which last less than a year should not have their own Cycle. This follows FAOSTAT conventions. Instead any Inputs or Practices related to these periods should be included in the Cycle of the main crop that follows. This means Cycles cover the period from the harvest of the preceding crop to the harvest of the current crop, which is our recommendation for all temporary crop Cycles.\n* The land cover during this period can either be specified by adding a Management blank node to the Site, or by creating a Product in the Cycle. Any term from the land cover glossary can be used. A Property should be added to each Management node or Product to state whether the land cover is either a Cover crop, Catch crop, Ground cover crop, or Short fallow crop.\n* Add the duration of the short fallow period if available by using the `startDate` and `endDate` fields on `Management` or `Product`.\n* Note that long fallow periods, lasting greater than one year, should have their own Cycle. This follows FAOSTAT conventions.\n\n### Multiple types of seed\n\n* In HESTIA, we do not directly differentiate seed, saplings, or other immature plants by the species of plant. When uploading, each Input must be unique.\n* If seed, saplings, etc. from different species or varieties of plant were Inputs into the same Cycle, e.g., in the case of intercropping, create an Impact Assessment for each species and link it to the Input. Additionally, add a `description` to the Input to provide more information.\n\n### Animal feed\n\n* The study may give data for the specific constituents of a feed blend fed to animals. If so, create a separate Cycle to represent the blending of multiple feed ingredients into a single concentrate feed. The Inputs to this Cycle can be crops, animal products, or other blended feeds, and the Product is the feed blend. Create an `impactAssessment.id` for the concentrate feed blend. This can then be linked to the feed blend Input of the animal production Cycle using the `impactAssessment.id`.\n\n### Cycles across multiple Sites\n\n* A Cycle may occur on multiple Sites (e.g., if animals move between pasture and housing). In this case, create two or more Sites and link them to the Cycle using `cycle.site.id` and `cycle.otherSites.id`. The duration which animals spend on each Site can be indicated through the `cycle.siteDuration` and `cycle.otherSitesDuration`.\n\n### Cropping Cycles across multiple years\n\n* Sometimes, crop production data in a research article or database are averaged across multiple Cycles.\n* Following FAOSTAT conventions, for annual crops, a Cycle should be the period from harvest of the previous crop to harvest of the current crop. For permanent crops, Cycles should last one year. We will raise an error on any uploads with `cycleDuration` that does not match this. Animal or other production Cycles do not need to adhere to these conventions.\n* To handle this in your upload:\n    * Ideally split the Cycle up into a Cycle for each harvest to harvest period or each year using the underlying data.\n    * If this is not possible, upload a Cycle representing the period from harvest to harvest which is an average over the data. Set the dates as the average date. Set the `cycleDuration` as an average over the Cycles. Use the `uploadNotes` field to document this.\n    * If this is not possible, duplicate the Cycle for each year. For example, if your data are an average over three harvests, duplicate the Cycle three times and change the `startDate`, `endDate`, and `cycleDuration` to reflect three separate periods from harvest to harvest. Use the `uploadNotes` field to document this.\n\n### Hot carcass weight\n\n* Sometimes, production quantities of animal products are provided in terms of hot carcass weight, whereas the terms in the Glossary are in cold carcass weight.\n* To handle this, convert the data from hot carcass weight to cold carcass weight using a sensible assumption (e.g., 2% to 5% mass loss). Upload the data using the terms in kg `cold carcass weight`. Then add the Property `Processing conversion, hot carcass weight to cold carcass weight` to the Input or Product defining the conversion you used.\n\n### Cover crop\n\n* Cover crops should be added in the Practice node of a Cycle using the `landCover` term corresponding to the plant (for example, Alfalfa plant), with the value being the percentage area of your Site covered by the cover crop.\n* A Property should be added to them to clarify that they are cover crops. There are four different terms in the Glossary relating to cover crops: Cover crop, Catch crop, Ground cover, and Short fallow crop (the difference between each term is explained in the term's definition in the Glossary). These terms are Properties and can be added to a crop, forage, or landCover term with `value = true` to specify that the term is a cover crop.\n* If the cover crop is harvested (this is only possible for `Catch crop`) or if the amount of biomass generated by the cover crop is known, the `crop` or `forage` term corresponding to the plant (for example, Rye, grain) should also be added in the Product node of a Cycle (in addition to the `landCover` term in the Practice node), with the value being the harvested yield or biomass created.\n* If you have further information about cover crops for years preceding the first Cycle taking place on your Site, you can add this information in the Management node of your Site using terms from the `landCover` glossary.\n* It is good practice to add a startDate and endDate specifying the time interval during which a cover crop is on the ground when `landCover` terms are used (when `crop` or `forage` terms are used in Product nodes, the startDate and endDate relate to the crop's harvest, not to the actual period during which the crop is on the ground).\n\nYou can download a simple example [here](https://cdn.hestia.earth/examples/Example%20cover%20crop%20upload.xlsx).\n\n### Sites with multiple cycles\n\n* Sometimes, multiple cycles occur on the same site.\n* To handle this in your upload, ideally change the `endDate` for each Cycle. If this is not possible, duplicate the Site for each Cycle. If the Site has an area, divide the area between the number of Cycles on that Site. For example, if your data consists of three cycles, with no specific calendar year associated with each of them, duplicate the Site three times and change the `area` to be a third of its orginial value, keeping the `startDate`, `endDate`, and `cycleDuration` of all three Cycles the same. Use the `uploadNotes` field to document this.\n\n### One time inputs for permanent crops\n\n* Permanent crop cycles can have inputs that only occur once, usually at the start of the Cycle, e.g. Saplings or Lime.\n* The impacts of these inputs should be split equally between all possible cycles in the Plantation lifespan. The number of possible cycles is the Plantation lifespan divided by the average `cycleDuration`, which is usually one year for plantations.\n* If you do not know the Plantation lifespan you can use the HESTIA suggested value, which can be found by opening the Glossary term page and looking for Plantation lifespan in the crop lookup table.\n* For seed inputs, such as Saplings, you should use the term Saplings, depreciated amount per Cycle, as an input to each crop Cycle in your upload, with the value being the total number of Saplings used over the entire Plantation lifespan divided by the number of possible cycles.\n* For other inputs, such as Lime, you should create a Cycle with the product Prepared plantation with a value of 1 ha. This Cycle should have `functionalUnit` 1 ha, and include all other one-time inputs.\n* Like with Saplings, you should use Prepared plantation, depreciated amount per Cycle as an Input to each crop Cycle in your upload, with the value being 1 ha divided by the number of possible cycles.\n* For the impact assessments to be linked, you will need to link the `impactAssessment.id` for the product Prepared plantation to the input Prepared plantation, depreciated amount per Cycle. You will also need to do this for Saplings inputs if you have a nursery Cycle with Saplings products.\n\nYou can download a simple example [here](https://cdn.hestia.earth/examples/Example%20plantation%20upload.xlsx)."}