@hestia-earth/guide 0.0.19 → 0.1.2

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 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.1.2](https://gitlab.com/hestia-earth/hestia-guide/compare/v0.1.1...v0.1.2) (2026-01-22)
+
+
+### Features
+
+* **aggregation-engine:** fix `economicValueShare` example ([34025c3](https://gitlab.com/hestia-earth/hestia-guide/commit/34025c37059c332e9c552ba416259eace0c883d6)), closes [#69](https://gitlab.com/hestia-earth/hestia-guide/issues/69)
+* **file-upload:** add links to JSON examples ([62106dd](https://gitlab.com/hestia-earth/hestia-guide/commit/62106dd29d142f45baef1989eed530064ccfac9c))
+
+
+### Bug Fixes
+
+* **index:** fix listPages from local index ([cda52d0](https://gitlab.com/hestia-earth/hestia-guide/commit/cda52d0b4f677350e670a78a26374499c0dee51d))
+* **upload-special-cases:** fix header levels ([23611e0](https://gitlab.com/hestia-earth/hestia-guide/commit/23611e069695a5800a957c27e6b3737afceb0ed1))
+
+### [0.1.1](https://gitlab.com/hestia-earth/hestia-guide/compare/v0.1.0...v0.1.1) (2025-12-27)
+
+## [0.1.0](https://gitlab.com/hestia-earth/hestia-guide/compare/v0.0.19...v0.1.0) (2025-12-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* `listPages` returns a list of `IGuideIndexPage`
+
+### Bug Fixes
+
+* return full index page when listing pages ([92174d5](https://gitlab.com/hestia-earth/hestia-guide/commit/92174d5b00fd926ef0304c8df6502a1146d6c943))
+
 ### [0.0.19](https://gitlab.com/hestia-earth/hestia-guide/compare/v0.0.18...v0.0.19) (2025-12-27)
 
 

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

@@ -1 +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."}
+{"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`. 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 | 84 =(20x1000+100x4000 + 0*0)/(1000 + 4000 + 0) | 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/file-upload/examples/example-1.json

@@ -1 +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 the [schema](/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](/explorer?type=Sources&sortBy=relevance&sortOrder=desc&query=Food%20Security%20Policy%20Project%20(2020))"}
+{"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 the [schema](/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 (Excel)](https://cdn.hestia.earth/examples/MaizePigeonPea_reformatted.xlsx)\n* [Dataset in HESTIA format (JSON)](https://cdn.hestia.earth/examples/MaizePigeonPea_reformatted.json)\n* [Data in the Explorer](/explorer?type=Sources&sortBy=relevance&sortOrder=desc&query=Food%20Security%20Policy%20Project%20(2020))"}

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

@@ -1 +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](/explorer?type=Sources&sortBy=relevance&sortOrder=desc&query=Poore%20%26%20Nemecek%20(2018))"}
+{"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 (Excel)](https://cdn.hestia.earth/examples/Poore%20and%20Nemecek%20(2018)%20Nitrate%20Leaching%20-%20Reformatted.xlsx)\n* [Dataset in HESTIA format (JSON)](https://cdn.hestia.earth/examples/Poore%20and%20Nemecek%20(2018)%20Nitrate%20Leaching%20-%20Reformatted.json)\n* [Data in the Explorer](/explorer?type=Sources&sortBy=relevance&sortOrder=desc&query=Poore%20%26%20Nemecek%20(2018))"}

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

@@ -1 +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](/explorer?type=Sources&sortBy=relevance&sortOrder=desc&query=Engstr%C3%B6m%20et%20al%20(2011))"}
+{"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\nNote: these data are part of a larger dataset.\n\n* [Dataset in HESTIA format (Excel)](https://cdn.hestia.earth/examples/Poore%20and%20Nemecek%20(2018)%20Nitrate%20Leaching%20-%20Reformatted.xlsx)\n* [Dataset in HESTIA format (JSON)](https://cdn.hestia.earth/examples/Poore%20and%20Nemecek%20(2018)%20Nitrate%20Leaching%20-%20Reformatted.json)\n* [Data in the Explorer](/explorer?type=Sources&sortBy=relevance&sortOrder=desc&query=Engstr%C3%B6m%20et%20al%20(2011))"}

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

@@ -1 +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](/explorer?type=Sources&sortBy=relevance&sortOrder=desc&query=Avadi%20et%20al%20(2015))"}
+{"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 (Excel)](https://cdn.hestia.earth/examples/Avadi%20et%20al%20(2015).xlsx)\n* [Dataset in HESTIA format (JSON)](https://cdn.hestia.earth/examples/Avadi%20et%20al%20(2015).json)\n* [Data in the Explorer](/explorer?type=Sources&sortBy=relevance&sortOrder=desc&query=Avadi%20et%20al%20(2015))"}

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

@@ -1 +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)."}
+{"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)."}