# Data dictionary

Units are tonnes (t) and US dollars (USD). Missing values are empty, never zero.

## annual_mirror.json / .csv

| Field | Type | Unit | Description |
|---|---|---|---|
| `year / period` | integer / string |  | Calendar year, or month as YYYY-MM |
| `mn.t` | integer | t | Mongolia: Tonnes reported by this side |
| `mn.usd` | integer | USD | Mongolia: US dollars reported by this side (Mongolia FOB, China CIF) |
| `mn.t_source` | string |  | Mongolia: Source id the tonnes come from |
| `mn.usd_source` | string |  | Mongolia: Source id the dollars come from |
| `mn.basis` | string |  | Mongolia: hs_partner (customs data by partner), curated_official, curated_press or nso_share_adjusted |
| `mn.t_source_url` | string |  | Mongolia: Link to the exact request or publication |
| `mn.share` | number | ratio | China's share applied to Mongolia's all-destination total |
| `mn.t_low / mn.t_high` | integer | t | Range for share-adjusted figures: lowest recent share up to 100% of exports |
| `mn.alt_t_nso_share_adjusted` | integer | t | The share-adjusted NSO figure, shown for comparison when another source was chosen |
| `cn.t` | integer | t | China: Tonnes reported by this side |
| `cn.usd` | integer | USD | China: US dollars reported by this side (Mongolia FOB, China CIF) |
| `cn.t_source` | string |  | China: Source id the tonnes come from |
| `cn.usd_source` | string |  | China: Source id the dollars come from |
| `cn.basis` | string |  | China: hs_partner (customs data by partner), curated_official, curated_press or nso_share_adjusted |
| `cn.t_source_url` | string |  | China: Link to the exact request or publication |
| `cn.excluded_estimated_t` | integer | t | UN Comtrade's estimated weight, shown but never compared |
| `gap.t` | integer | t | China minus Mongolia. Positive: China recorded more coal arriving than Mongolia recorded leaving |
| `gap.t_pct` | number | % | gap.t as a percentage of Mongolia's figure |
| `gap.usd / gap.usd_pct` | integer / number | USD / % | The same for US dollars |
| `unit_value.mn_fob` | number | USD/t | Mongolia's export price per tonne (FOB) |
| `unit_value.cn_cif` | number | USD/t | China's import price per tonne (CIF) |
| `unit_value.spread` | number | USD/t | CIF minus FOB; normally positive because of freight and insurance |
| `unit_value.inverted` | boolean |  | True when China's price is more than 5% below Mongolia's |
| `comparability` | string |  | comparable (both customs, same basis), approximate, one_sided, none |
| `notes` | string[] |  | Note codes; text in notes.json |

## monthly_mirror.json / .csv

| Field | Type | Unit | Description |
|---|---|---|---|
| `year / period` | integer / string |  | Calendar year, or month as YYYY-MM |
| `mn.t` | integer | t | Mongolia: Tonnes reported by this side |
| `mn.usd` | integer | USD | Mongolia: US dollars reported by this side (Mongolia FOB, China CIF) |
| `mn.t_source` | string |  | Mongolia: Source id the tonnes come from |
| `mn.usd_source` | string |  | Mongolia: Source id the dollars come from |
| `mn.basis` | string |  | Mongolia: hs_partner (customs data by partner), curated_official, curated_press or nso_share_adjusted |
| `mn.t_source_url` | string |  | Mongolia: Link to the exact request or publication |
| `mn.share` | number | ratio | China's share applied to Mongolia's all-destination total |
| `mn.t_low / mn.t_high` | integer | t | Range for share-adjusted figures: lowest recent share up to 100% of exports |
| `mn.alt_t_nso_share_adjusted` | integer | t | The share-adjusted NSO figure, shown for comparison when another source was chosen |
| `cn.t` | integer | t | China: Tonnes reported by this side |
| `cn.usd` | integer | USD | China: US dollars reported by this side (Mongolia FOB, China CIF) |
| `cn.t_source` | string |  | China: Source id the tonnes come from |
| `cn.usd_source` | string |  | China: Source id the dollars come from |
| `cn.basis` | string |  | China: hs_partner (customs data by partner), curated_official, curated_press or nso_share_adjusted |
| `cn.t_source_url` | string |  | China: Link to the exact request or publication |
| `cn.excluded_estimated_t` | integer | t | UN Comtrade's estimated weight, shown but never compared |
| `gap.t` | integer | t | China minus Mongolia. Positive: China recorded more coal arriving than Mongolia recorded leaving |
| `gap.t_pct` | number | % | gap.t as a percentage of Mongolia's figure |
| `gap.usd / gap.usd_pct` | integer / number | USD / % | The same for US dollars |
| `unit_value.mn_fob` | number | USD/t | Mongolia's export price per tonne (FOB) |
| `unit_value.cn_cif` | number | USD/t | China's import price per tonne (CIF) |
| `unit_value.spread` | number | USD/t | CIF minus FOB; normally positive because of freight and insurance |
| `unit_value.inverted` | boolean |  | True when China's price is more than 5% below Mongolia's |
| `comparability` | string |  | comparable (both customs, same basis), approximate, one_sided, none |
| `notes` | string[] |  | Note codes; text in notes.json |
| `mn.t_ytd / cn.t_ytd` | integer | t | Year-to-date totals, when every month is available |
| `gap.t_ytd / gap.t_ytd_pct` | integer / number | t / % | Year-to-date gap |
| `cn.t_ytd_reported` | integer | t | China's reported cumulative figure (January and February are published together) |
| `rolling_12m` | object | t | 12-month totals, when all 12 months are comparable |

## observations.csv / .parquet

| Field | Type | Unit | Description |
|---|---|---|---|
| `source_id` | Literal['comtrade_mn', 'comtrade_cn', 'nso_month', 'nso_year', 'nso_country_year', 'nso_production', 'nso_balance', 'gacc_curated', 'mn_customs_curated', 'mrpam', 'derived'] |  | Pipeline source identifier |
| `reporter` | Literal['MNG', 'CHN'] |  | Country whose statistics office reported the figure |
| `partner` | Literal['CHN', 'MNG', 'WLD'] |  | Trading partner; WLD = all destinations |
| `flow` | <class 'str'> |  | X export, M import, production, sales, or a coal-balance item |
| `commodity` | <class 'str'> |  | HS code (2701, 2701xx) or 'coal' for national items |
| `freq` | Literal['A', 'M'] |  | A annual, M monthly |
| `period` | <class 'str'> |  | '2022' or '2022-07' |
| `measure` | Literal['weight_t', 'value_usd', 'weight_t_ytd', 'value_usd_ytd'] |  | weight_t, value_usd, or year-to-date variants |
| `value` | <class 'float'> | t or USD | Tonnes or USD; never null (missing rows are absent) |
| `unit` | Literal['t', 'USD'] |  |  |
| `valuation` | Literal['FOB', 'CIF'] | None |  | Value rows only: exports FOB, imports CIF |
| `year` | <class 'int'> |  |  |
| `month` | int | None |  |  |
| `is_estimated` | <class 'bool'> |  | UN Comtrade estimated the quantity or net weight |
| `is_aggregate` | <class 'bool'> |  | UN Comtrade isAggregate flag |
| `is_cumulative_derived` | <class 'bool'> |  | Monthly value derived as a difference of year-to-date totals |
| `is_curated` | <class 'bool'> |  | Hand-entered from a cited publication |
| `is_share_adjusted` | <class 'bool'> |  | All-destination total multiplied by China's share |
| `confidence` | Literal['official', 'press', 'derived'] |  |  |
| `derivation_note` | str | None |  |  |
| `source_table` | str | None |  |  |
| `source_url` | <class 'str'> |  |  |
| `raw_file` | str | None |  |  |
| `retrieved_at` | <class 'str'> |  |  |
| `source_updated_at` | str | None |  |  |
| `vintage` | <class 'str'> |  |  |
| `citation` | str | None |  |  |