# Focused 205-city clue dataset

`cities_game_metrics_205.csv` preserves the same 205 GeoNames IDs, city coordinates and row order. The focused dataset contains the requested geographic clues and five environmental metrics. Geography-only audit inputs are retained under `city_metrics/geographic_baseline_205.csv`.

The first clue uses the typical average temperature for the player's current calendar month, from the stored NASA POWER/MERRA-2 2001–2025 climate profile. This includes day and night and is not a daytime-only or current-year average. No source API request is needed to build the lookup or play the game.

`monthly_climate_205.csv` contains **2,460 city/month rows** with Celsius/Fahrenheit temperatures, month names and example clue wording. `monthly_climate_205.json` contains all twelve months for each city and the month-selection rule. Select the player's local calendar month when a mission starts, and keep that month fixed for the whole mission. Do not bake today's month into the permanent dataset. The main CSV includes `first_clue_temperature_basis` and `first_clue_month_selection` to make this rule explicit.

The local game and its embedded copies use this finalized dataset, including the retained geographic themes and five environmental measures. The first clue uses the offline monthly climate profile. Rounds 1–5 retain shield placement; the final round uses direct circular city buttons. Previous live-condition collector code, snapshots, credentials, mixed exports and obsolete reports have been removed at the user's request.

## Retained geographic clues

- Distance to mapped coastline.
- Distance to mapped international land boundary: only Natural Earth's `International boundary (verify)` feature class, consistent with the earlier audited metric. This is distance to the nearest qualifying boundary anywhere, including in another country for an island city; it is not necessarily the city's own national boundary.
- Distance to mapped equator.
- Distance to **Tropic of Cancer** and **Tropic of Capricorn** separately.
- Distance to **Arctic Circle** and **Antarctic Circle** separately.
- Distance to mapped International Date Line.
- Northern/Southern and Eastern/Western hemispheres, calculated from the signs of the exact reference latitude and longitude.

All feature distances have kilometer and mile columns. They use generalized Natural Earth 1:10 million geometry and WGS84 surface geodesics; they are not travel distances. The named latitude-line geometry is the source's mapped geometry, not a newly calculated astronomical line. Polygon coverage has distance zero. The date line follows its mapped bends, not simply longitude 180 degrees.

Country, city and original map labels are retained for identification. A coordinate exactly on the equator or prime meridian would be labeled as that line rather than assigned a side; none of these 205 cities requires that exception.

## Five new metrics

| Metric / main field | Definition | Source and reference period |
| --- | --- | --- |
| `elevation_m`, `elevation_ft` | Nearest 15-arc-second surface-model pixel at the reference coordinates; orthometric height relative to EGM2008 | NOAA ETOPO 2022 v1 |
| `annual_precipitation_mm`, `annual_precipitation_inches` | Sum of each climatological monthly mean corrected precipitation rate multiplied by that month's average calendar days over 2001–2025 | NASA POWER / MERRA-2, January 2001–December 2025 |
| `seasonal_temperature_difference_c`, `_f` | Warmest minus coldest of the twelve climatological monthly mean 2 m air temperatures; this is an annual monthly temperature range | NASA POWER / MERRA-2, January 2001–December 2025 |
| `surrounding_tree_cover_pct` | Area of WorldCover tree-cover class 10 divided by valid non-water land area within a WGS84 geodesic 20 km circle, times 100 | ESA WorldCover 2021 v200, native approximately 10 m pixels |
| `population_density_per_km2`, `_per_mi2` | Sum of GHS-POP resident counts in 1 km cells whose centers are within a WGS84 geodesic 25 km circle, divided by the full geodesic circle area including water | GHS-POP R2023A, 2020 population estimates |

**The requested rainfall addition is represented as total precipitation.** NASA `PRECTOTCORR` includes rain and snow water equivalent. It is not liquid-only rainfall. The dataset explicitly records that distinction and should use “annual precipitation” in future game clues. Monthly source rates are available in the raw checkpoints, and monthly totals are included in the CSV. Summing the displayed monthly totals can differ from the annual field by a few thousandths of a millimeter because of output rounding.

NASA's returned climatology for every city was January 2001–December 2025. This is a 25-year source climatology, not the 1991–2020 standard normal. Average month lengths account for the six leap years in the source period: the average year contains 365.24 days. Meteorological fields are averages over a roughly 0.5° × 0.625° MERRA-2 grid, not measurements at a city weather station. Nearby cities may share climate values. The original request coordinates are retained; POWER echoes them rounded to three decimal places.

Temperature differences convert with `difference_F = difference_C × 1.8`, without adding 32. Actual monthly temperatures use `F = C × 1.8 + 32`. Warmest/coldest month names and monthly means support interpretation and auditing.

Tree cover is **the fraction of land classified as tree cover**, not a continuous tree-canopy fraction and not the land-cover class of the city-center pixel. The denominator excludes WorldCover class 80 water; the alternative `tree_cover_pct_of_full_buffer` includes water in its denominator. The primary class-10 metric does not include class-95 mangroves. Pixel areas are weighted on the WGS84 ellipsoid. Boundary pixels are checked against exact geodesic distances; native class pixels are used without overview downsampling. WorldCover's classification is imperfect and dated to 2021.

Population density uses a consistent 25 km neighborhood, **not a city administrative or metropolitan boundary**. Water remains in the density denominator, so coastal cities are comparable under this stated full-disk definition but can have lower density than under a land-only definition. Raster cells use center inclusion rather than fractional boundary allocation. The 2020 estimates are not a 2026 census. Ocean/nodata population cells contribute no residents; the report retains source cell counts for auditing.

Elevation is modeled terrain/surface height at a nearby raster pixel, not a surveyed municipal elevation or building height. The CSV records source-pixel offset and below-sea-level flags. Negative values are retained where present; they are not replaced with zero.

## Commercial reuse and attribution

The selected sources permit commercial reuse under their listed terms. See [DATA_LICENSES.md](city_metrics/DATA_LICENSES.md) for source-specific licenses, citations, and the records of the checked pages. The derived data retains source attribution requirements. No noncommercial-only sources such as WorldClim are included. The NASA source is the explicitly approved replacement for credential-required ERA5-Land.

## Coverage and validation

Read `city_metrics/validation_report.json` and `city_metrics/VALIDATION_REPORT.md` for actual completion counts and checks. The checks cover all 205 IDs, coordinate agreement, source request coordinates, all twelve climate months, derivation formulas, unit conversions, hemisphere signs, feature selection, pixel offsets, missing data, numerical ranges and the offline 12-month clue lookup. ETOPO elevation is also compared with the independent DEM field in the saved GeoNames source as a plausibility check.

Complete coverage and reproducible processing do not establish error-free real-world observations. These are source-aligned model, census-disaggregation and land-classification estimates with different reference dates. Their numerical precision is not an accuracy guarantee.

## Reproduction

From the main folder, use the existing geospatial Python environment with `rasterio`, `certifi`, and NumPy installed:

```
.venv-geo/bin/python collect_city_metrics.py climate --workers 4
.venv-geo/bin/python collect_city_metrics.py elevation --workers 3
.venv-geo/bin/python collect_city_metrics.py tree_cover --workers 3
.venv-geo/bin/python collect_city_metrics.py population --workers 3
.venv-geo/bin/python build_game_city_metrics.py
.venv-geo/bin/python validate_game_city_metrics.py
```

The population step requires the cached GHS-POP 2020 1 km raster already extracted under `city_metrics/cache/`. Source URLs and the full population archive checksum are in the metadata. Collection is resumable with per-city checkpoints. These scripts rebuild data only. Rebuild the local game assets separately after changing the dataset.