# KGLD Methodology ## 1. Unit of observation A lake is an entity (`lake_id`). A numeric statement about a lake is a separate measurement (`measurement_id`). A categorical statement is a classification (`classification_id`). This separation prevents a new source from overwriting an older observation. ## 2. Stable IDs - Lake: `KGLD-L####` - Name: `KGLD-N####` - Measurement: `KGLD-M####` - Classification: `KGLD-C####` - Inventory statistic: `KGLD-I####` - Source: `KGLD-S####` - Decision: `KGLD-D####` IDs are never recycled. Names and spellings may change without changing the entity ID. ## 3. Source hierarchy `source_quality_code` is an evidence-source tier, not a truth score. - **Q1** — primary peer-reviewed measurement or official primary statistical publication - **Q2** — curated international database or high-quality scholarly synthesis - **Q3** — institutional/technical report with identifiable method/source trail - **Q4** — scholarly secondary/reference source without primary measurement provenance - **Q5** — general secondary web/reference source; primarily for discovery A Q1 source may still contain an old, approximate, or definition-dependent value. That uncertainty belongs in the measurement row. ## 4. Measurement confidence - **high** — variable, value, unit, source and locator are clear; method/date adequate for intended use - **medium** — credible evidence but important context is missing - **low** — weakly defined or indirect value retained for provenance - **unresolved** — conflicting evidence not yet adjudicated ## 5. Observation dates Area, volume, elevation and depth are treated as potentially time-sensitive. Observation year/date is mandatory for dynamic glacial, ice-dammed and seasonal lakes wherever it can be recovered. Publication year is never substituted for observation year. ## 6. Conflicting values Conflicts are preserved. Do not average or overwrite values simply because one is newer. A `comparability_group` must be assigned before values are adjudicated. Values that use different definitions, vertical datums, mapping thresholds, or observation periods may belong to different groups and therefore are not necessarily conflicts. ## 7. Reference-value selection Only one row should be `selected_reference=true` per lake-variable-comparability group. Selection priority: 1. Direct measurement appropriate to the variable and observation period. 2. Clear observation date and method. 3. Primary/official source over an unattributed secondary repetition. 4. Explicit source locator. 5. More suitable spatial/temporal resolution for the intended reference use. 6. Newer value only when the variable is time-varying and methods are comparable. Every non-trivial selection must be logged in `data/kyrgyzstan_lake_reference_decisions.csv`. ## 8. Ranges and approximate values Source ranges are stored in `value_min` and `value_max`. A midpoint must not be silently converted into a reported value. If a convenience midpoint is stored, it must be labelled as derived in the curator note. Approximate values remain approximate. ## 9. Unit conversions Store canonical units, but document any conversion in `curator_note` or a future derivation field. Never convert without preserving the source unit/value in the provenance note when precision could matter. ## 10. Lake inventories Inventory-level counts are separate from lake entities. Every count should retain: - geographic scope - lake population definition - observation year/period - minimum mapping unit / size threshold - mapping method/sensor where applicable - source and source locator Counts with different thresholds or definitions must not be presented as directly comparable. ## 11. Names and identity resolution Names are stored separately from lake entities. Before merging two names into one `lake_id`, curators should verify location and source context. Names that may refer to a lake complex rather than a single water body remain unresolved until mapped. ## 12. Coordinates and GIS Coordinates use EPSG:4326 in the flat files. Coordinate method, source and estimated precision must be retained. The current point layer is `data/kyrgyzstan_lakes.geojson` and contains only source-traceable representative coordinates. Do not import third-party geometry into a CC BY release without checking license compatibility. ## 13. Release rule for public v1.0 `data/kyrgyzstan_lake_reference.csv` is a full entity-indexed derived view and may retain registry rows with blank core values so that stable lake IDs remain traceable across the package. A lake appears in the simplified `data/kyrgyzstan_lake_reference_public.csv` only when: - identity is sufficiently resolved for public reference use; - at least one core variable (area, elevation, maximum depth or volume) passes the release audit; - the supporting measurement has source-level provenance and a usable source locator; - known high-priority conflicts are disclosed or the contested value is withheld. For v1.0.0 the master registry contains 73 entities and the simplified public reference view contains 63. The release does not claim completeness for all lakes in Kyrgyzstan. ## 14. Public-reference audit Before a public release, each selected reference measurement receives a separate release audit. The audit does not modify or delete evidence. Audit outcomes include: - `PASS_HIGH` - `PASS_WITH_CAVEAT` - `PASS_WITH_CONFLICT_DISCLOSURE` - `HOLD_DYNAMIC_UNDATED` - `HOLD_CONFLICT_UNRESOLVED` - `HOLD_CONTEXT_SPECIFIC` - `HOLD_CRITICAL_CONFLICT` - `HOLD_SCALE_DEPENDENT` - `HOLD_DEFINITION_DEPENDENT` - `HOLD_SCENARIO_POTENTIAL` - `HOLD_SOURCE_TABLE_QUALITY` Only measurements marked `public_reference_eligible=TRUE` are allowed into `data/kyrgyzstan_lake_reference_public.csv`. ## 15. Rights handling Source license and reuse status are tracked separately from scientific source quality. Open licensing does not make a weak measurement scientifically strong, and strong science does not imply permission to copy source text/tables. KGLD avoids redistribution of third-party documents, figures, photographs and source tables. For copyrighted or terms-unclear sources it records compact factual claims, citation metadata and locators. ## 16. Machine-readable package validation The v1.0 release uses a mixed Frictionless Data Package descriptor because the package contains both tabular CSV resources and a GeoJSON point resource. Each CSV in `datapackage.json` is declared as a `tabular-data-resource` with an embedded Table Schema. The schemas describe field types, required constraints, primary keys and the main normalized foreign keys. Semicolon-delimited multi-value relations and polymorphic curation IDs are validated separately in `metadata/kyrgyzstan_lake_validation_report.json`. Core reference range values are normalized into scalar/minimum/maximum columns so that numeric fields remain machine-readable numbers instead of mixed numeric/range strings.