@cyanheads/eurostat-mcp-server 0.11.1 → 0.11.2

package/skills/eurostat-guide/SKILL.md

@@ -4,7 +4,7 @@ description: Use with eurostat_* tools to compare countries or regions, analyse
 license: Apache-2.0
 metadata:
   author: "cyanheads"
-  version: "1.1"
+  version: "1.1.1"
 ---
 
 ## Scope
@@ -30,6 +30,7 @@ Keep codes as identifiers and labels as display text. Resolve codes within the c
 - Before interpreting a GDP comparison, distinguish economic size, per-inhabitant values and price-adjusted comparisons. For comparisons across countries, PPS removes price-level differences; changes in current-price PPS values are not automatically real growth. Consult [Eurostat's PPP guidance](https://ec.europa.eu/eurostat/en/web/purchasing-power-parities/information-data) when choosing the measure.
 - Before a regional time-series comparison, establish the NUTS classification used by the data. A matching code or label alone does not establish unchanged boundaries. Eurostat revises NUTS and historical reconstruction depends on feasibility; consult [NUTS history and changes](https://ec.europa.eu/eurostat/en/web/nuts/history) and the dataset metadata when classifications differ. This server does not supply a concordance operation.
 - Before claiming a series is absent, distinguish an unknown metadata bound, an unlisted page, an unmatched code, an empty combination of otherwise valid codes and a period range that excludes the period. Eurostat keeps only periods wholly inside since_period–until_period, per frequency, so a bound inside a period drops it; a notice or error names the bound to use. Inspect notices and discovery freshness; missing Comext discovery is not evidence that a known DS-* dataset is unavailable.
+- Before comparing coverage across series, separate a period a series lacks from an observation published without a value. A query reports the former as absentCellCount (periods of a frequency a matched series carries, with no cell) and stages no row for it; obsCount and missingObsCount count only published cells. A download stages the former as a row with null obs_value and no flag, status or text (an unflagged ":"), counted in rowCount and missingCount, in absentCellCount when the series carries that frequency elsewhere, and also at periods of a frequency the series has no observation of (the padding of a mixed-frequency slice), which absentCellCount leaves out. Such a row is not an observation, and its period is not coverage; periodRange and timeRange leave it out. A flagged ":" or a text value is an observation.
 - Before calling observations the latest available for each geography, inspect the selected slice's actual periods. The dataset's latest period can have no populated value for that slice. Expand the search period when necessary; do not report an empty latest-period selection as a zero.
 - Before calculating totals or rankings, establish that the retained observations cover the intended population. Inline observations are a preview, not a random sample, and a "Same in all N rows shown" line describes those rows, not the match; a query's truncated=false does not prove the preview includes every matched row. Compare obsCount with the observations received or inspect the staged table. A bulk result with budgetExceeded is an ordered prefix, even when that prefix has been staged successfully. Narrow and refetch before presenting a complete total.
 - Preserve missing numeric values, published text values, observation flags and confidentiality status. A null numeric value is not zero; a PRODCOM text value is not a numeric quantity. Carry relevant provisional, break-in-series or reliability flags into the interpretation.

package/skills/eurostat-guide/references/sql-analysis.md

@@ -28,13 +28,29 @@ The ordering is total only when the selected slice has one row per geo/time pair
 Inspect missingness alongside an aggregate:
 
 ```sql
-SELECT geo, COUNT(*) AS cells, COUNT(obs_value) AS numeric_cells,
+SELECT geo, COUNT(*) AS rows_staged, COUNT(obs_value) AS numeric_cells,
        AVG(obs_value) AS mean_value
 FROM observations_table
 GROUP BY geo
 ORDER BY geo
 ```
 
-AVG ignores null numeric values. Use it only when that average answers the statistical question; do not replace missing observations with zero. For DS-* tables, inspect obs_value_text before interpreting every null numeric cell as missing data. Inspect obs_flag and conf_status alongside the values before drawing conclusions.
+AVG ignores null numeric values. Use it only when that average answers the statistical question; do not replace missing observations with zero.
+
+A table staged by eurostat_query_dataset has a row only for each published cell, so a period a series lacks is not a row; the query's absentCellCount counts those. A table staged by eurostat_download_dataset also holds those periods as rows with null obs_value, obs_flag, conf_status and (on DS-* tables) obs_value_text. To count the null cells that are observations, exclude them:
+
+```sql
+SELECT geo,
+       COUNT(*) AS rows_staged,
+       COUNT(*) FILTER (WHERE obs_value IS NOT NULL OR obs_flag IS NOT NULL
+                          OR conf_status IS NOT NULL) AS observations,
+       COUNT(*) FILTER (WHERE obs_value IS NULL AND obs_flag IS NULL
+                          AND conf_status IS NULL) AS unflagged_null_rows
+FROM observations_table
+GROUP BY geo
+ORDER BY geo
+```
+
+On a DS-* table add OR obs_value_text IS NOT NULL to the observation test and AND obs_value_text IS NULL to the unflagged test; otherwise a text value such as KG counts as an unflagged row. In a mixed-frequency slice, compare each row's frequency dimension (freq on Comext) with the shape of its time code: an unflagged null row at a monthly period of an annual series is padding, not a gap. For DS-* tables, inspect obs_value_text before interpreting every null numeric cell as missing data. Inspect obs_flag and conf_status alongside the values before drawing conclusions.
 
 When a SQL result is truncated, retrieve deterministic pages of an unchanged query with a total ORDER BY and LIMIT/OFFSET. Advance OFFSET by the returned rowCount. Restart at offset zero if the first query was unordered. Expired or changing tables and volatile expressions cannot provide stable paging. Integer counts may arrive as strings to preserve precision; do not coerce them to an unsafe JavaScript number.