mongolstats: Mongolian NSO PXWeb Data and Boundaries

Description

A tidyverse-friendly client for the National Statistics Office of Mongolia PXWeb API (data.1212.mn) with helpers to discover tables, variables, and fetch statistical data. Also includes utilities to retrieve Mongolia administrative boundaries (ADM0-ADM2) as 'sf' objects from open sources for mapping and spatial analysis.

Main Functions

nso_data

Fetch statistical data from a table

nso_itms, nso_tables

List available tables

nso_itms_search

Search tables by keyword

mn_boundaries

Get administrative boundaries

Author(s)

Maintainer: Temuulen Enebish temuulen@gmail.com

See Also

Useful links:

• https://temuulene.github.io/mongolstats/

• https://data.1212.mn/pxweb/

• Report bugs at https://github.com/temuulene/mongolstats/issues

List PXWeb children under a path

Description

List PXWeb children under a path

Usage

.px_list(paths = character(), lang = .px_lang())

Get PXWeb table metadata

Description

Get PXWeb table metadata

Usage

.px_meta(paths, table, lang = .px_lang())

Convert a query to a PXWeb body

Description

Convert a query to a PXWeb body

Usage

as_px_query(x, lang = .px_lang())

Arguments

Value

A list suitable to send as JSON body to PXWeb.

Examples

q <- nso_query("DT_NSO_0300_001V2", list(Year = "2023"))
body <- as_px_query(q)

Mongolia administrative boundaries (sf)

Description

Downloads Mongolia boundaries for ADM0/ADM1/ADM2 from the GeoBoundaries API and returns an sf object. Results can be cached by the caller as needed.

Usage

mn_boundaries(level = c("ADM0", "ADM1", "ADM2"))

Arguments

Value

An sf object with polygons for the requested level.

Examples

# Get aimag (province) boundaries
aimags <- mn_boundaries("ADM1")
head(aimags)

Add normalized name columns to boundaries

Description

Add normalized name columns to boundaries

Usage

mn_boundaries_normalize(g, name_col = "shapeName")

Arguments

Value

sf with name_std column added.

Examples

aimags <- mn_boundaries("ADM1")
aimags <- mn_boundaries_normalize(aimags)
head(aimags$name_std)

Boundary keys/crosswalk helper

Description

Boundary keys/crosswalk helper

Usage

mn_boundary_keys(level = "ADM1")

Arguments

Value

tibble with key columns from GeoBoundaries and normalized names.

Examples

keys <- mn_boundary_keys("ADM1")
head(keys)

Fuzzy join data to boundaries by name

Description

Fuzzy join data to boundaries by name

Usage

mn_fuzzy_join_by_name(
  data,
  name_col,
  level = "ADM1",
  boundaries = NULL,
  max_distance = 2,
  method = c("osa", "lv", "jw", "dl")
)

Arguments

Value

sf with best fuzzy matches joined.

Examples

# Join even with minor spelling differences
pop_data <- data.frame(aimag = c("Ulanbatar", "Darhan"), pop = c(1500000, 100000))
sf_joined <- mn_fuzzy_join_by_name(pop_data, "aimag", level = "ADM1")

Join data to boundaries by (normalized) names

Description

Join data to boundaries by (normalized) names

Usage

mn_join_by_name(data, name_col, level = "ADM1", boundaries = NULL)

Arguments

Value

sf with joined data.

Examples

pop_data <- data.frame(aimag = c("Ulaanbaatar", "Darkhan-Uul"), pop = c(1500000, 100000))
sf_joined <- mn_join_by_name(pop_data, "aimag", level = "ADM1")

Clear cached entries

Description

Clear cached entries

Usage

nso_cache_clear()

Value

No return value, called for side effects.

Examples

nso_cache_clear()

Disable caching

Description

Disable caching

Usage

nso_cache_disable()

Value

No return value, called for side effects.

Examples

nso_cache_disable()

Enable or configure caching

Description

Caches table lists and codebooks on disk to speed up repeated calls. Optionally set a time-to-live (TTL) for cache entries.

Usage

nso_cache_enable(dir = NULL, ttl = NULL)

Arguments

Value

Cache directory path (invisibly).

Examples

# Enable caching in a temporary directory (for demo purposes)
cache_dir <- nso_cache_enable(dir = tempdir())

# Check status
nso_cache_status()

# Disable when done
nso_cache_disable()

Cache status

Description

Report current cache configuration and basic stats.

Usage

nso_cache_status()

Value

A list with enabled, dir, and has_cache.

Examples

nso_cache_status()

Fetch statistical data for a table (PXWeb)

Description

Fetch statistical data for a table (PXWeb)

Usage

nso_data(
  tbl_id,
  selections,
  labels = c("none", "en", "mn", "both"),
  value_name = getOption("mongolstats.value_name", "value"),
  include_raw = getOption("mongolstats.attach_raw", FALSE)
)

Arguments

Value

A tibble with one column per dimension and a numeric value column.

Examples

# Fetch population data
pop <- nso_data(
  tbl_id = "DT_NSO_0300_001V2",
  selections = list(Year = "2023")
)
head(pop)

List values for a table dimension

Description

Returns codes and optional labels for a specific dimension.

Usage

nso_dim_values(tbl_id, dim, labels = c("code", "en", "mn", "both"))

Arguments

Value

A tibble with at least code; may include label_en and/or label_mn.

Examples

values <- nso_dim_values("DT_NSO_0300_001V2", "Year")
head(values)

List dimensions for a PXWeb table

Description

Returns one row per dimension with basic metadata.

Usage

nso_dims(tbl_id)

Arguments

Value

A tibble with columns: dim (display name), code (dimension code), is_time (logical), and n_values (number of values for the dimension).

Examples

dims <- nso_dims("DT_NSO_0300_001V2")
dims

Fetch a query and return a tibble

Description

Executes an nso_query and returns a tidy tibble with one column per dimension and a numeric value column. Use labels to add ⁠_en⁠/⁠_mn⁠ columns for each dimension.

Usage

nso_fetch(
  x,
  labels = c("code", "en", "mn", "both"),
  value_name = getOption("mongolstats.value_name", "value"),
  include_raw = getOption("mongolstats.attach_raw", FALSE)
)

Arguments

Value

A tibble.

Examples

q <- nso_query("DT_NSO_0300_001V2", list(Year = "2023"))
data <- nso_fetch(q)
head(data)

List available NSO tables (PXWeb)

Description

Returns a tibble of all available tables in the NSO PXWeb catalog.

Usage

nso_itms()

nso_tables()

Value

A tibble with columns: px_path, px_file, tbl_id, tbl_eng_nm, tbl_nm, strt_prd, end_prd, list_id.

Examples

# List all available tables
tables <- nso_itms()
head(tables)

List tables under a sector or sub-sector (PXWeb path)

Description

List tables under a sector or sub-sector (PXWeb path)

Usage

nso_itms_by_sector(list_id)

Arguments

Value

A tibble of tables matching the specified sector path.

Examples

sectors <- nso_sectors()
tables <- nso_itms_by_sector(sectors$id[1])

Get variable codes for a table (PXWeb)

Description

Get variable codes for a table (PXWeb)

Usage

nso_itms_detail(tbl_id)

nso_variables(tbl_id)

Arguments

Value

A tibble with variable metadata.

Examples

vars <- nso_itms_detail("DT_NSO_0300_001V2")
vars

Search tables by keyword (PXWeb)

Description

Search tables by keyword (PXWeb)

Usage

nso_itms_search(query, fields = c("tbl_eng_nm", "tbl_nm"))

Arguments

Value

A tibble of matching tables.

Examples

# Search for population tables
nso_itms_search("population")

Disable offline mode

Description

Disable offline mode

Usage

nso_offline_disable()

Value

Invisibly, TRUE.

Examples

nso_offline_disable()

Enable offline mode

Description

When enabled, HTTP requests are prevented and functions that require the network will raise a clear offline error. Cached metadata can still be used if already available via nso_cache_enable().

Usage

nso_offline_enable()

Value

Invisibly, TRUE.

Examples

# Enable offline mode
nso_offline_enable()

# Check the option was set
getOption("mongolstats.offline")

# Disable to restore normal operation
nso_offline_disable()

Set or get mongolstats options

Description

Convenience wrapper around base::options() for mongolstats.

Usage

nso_options(...)

Arguments

Value

Invisibly, the previous values of the options changed, or a list of current values when called with no arguments.

Examples

# Get all current mongolstats options
nso_options()

# Set an option (save old value for restoration)
old <- nso_options(mongolstats.default_labels = "en")

# Restore original value
options(old)

Fetch multiple tables and bind (PXWeb)

Description

Fetch multiple tables and bind (PXWeb)

Usage

nso_package(
  requests,
  labels = c("none", "en", "mn", "both"),
  parallel = getOption("mongolstats.parallel", FALSE),
  value_name = getOption("mongolstats.value_name", "value")
)

Arguments

Value

A tibble combining data from all requested tables, with a tbl_id column identifying the source table.

Examples

reqs <- list(
  list(tbl_id = "DT_NSO_0300_001V2", selections = list(Year = "2023"))
)
combined <- nso_package(reqs)

Create period codes

Description

Utilities to construct NSO period codes and sequences. For monthly data, use YYYYMM; for yearly, use YYYY.

Usage

nso_period_seq(start, end, by = c("Y", "M"))

Arguments

Value

Character vector of period codes.

Examples

# Generate yearly sequence
nso_period_seq("2020", "2024", by = "Y")

# Generate monthly sequence
nso_period_seq("202401", "202406", by = "M")

Create a PXWeb query object

Description

Builds a lightweight query object that records a table id and selections. Use nso_fetch() to execute it, or as_px_query() to inspect the underlying PXWeb body.

Usage

nso_query(tbl_id, selections = list())

Arguments

Value

An object of class nso_query.

Examples

# Create a query object (does not require network)
q <- nso_query("DT_NSO_0300_001V2", list(Year = "2023", Sex = "Total"))
print(q)

Rebuild PXWeb index and optionally write to a file

Description

Crawls the PXWeb API to rebuild the table index. If path is provided, the index is written to that file; otherwise only the in-memory index is refreshed.

Usage

nso_rebuild_px_index(path = NULL, write = !is.null(path))

Arguments

Value

A tibble containing the rebuilt table index.

Examples

# Rebuild in-memory index only (takes time to crawl API)

idx <- nso_rebuild_px_index()
head(idx)

Search NSO tables

Description

Search NSO tables

Usage

nso_search(query, sector = NULL, fields = c("tbl_eng_nm", "tbl_nm"))

Arguments

Value

Tibble of matching tables.

Examples

nso_search("population")

List top-level categories (PXWeb NSO root)

Description

List top-level categories (PXWeb NSO root)

Usage

nso_sectors()

Value

tibble with id, type, text

Examples

sectors <- nso_sectors()
head(sectors)

List children for a given path (PXWeb)

Description

List children for a given path (PXWeb)

Usage

nso_subsectors(subid)

Arguments

Value

A tibble with columns: id, type, text.

Examples

sectors <- nso_sectors()
nso_subsectors(sectors$id[1])

Table metadata as per-dimension codebooks

Description

Returns a tibble with one row per dimension and a codes list-column, where each element is a tibble of codes and labels (code, label_en, label_mn). Useful for manual query assembly and for inspecting available categories per dimension.

Usage

nso_table_meta(tbl_id)

Arguments

Value

A tibble with columns: dim (display name), code (dimension code), is_time (logical), n_values (integer), and codes (list of tibbles).

Examples

meta <- nso_table_meta("DT_NSO_0300_001V2")
meta

Get valid periods for a table (PXWeb)

Description

Get valid periods for a table (PXWeb)

Usage

nso_table_periods(tbl_id)

Arguments

Value

Character vector of period labels (e.g., years)

Examples

periods <- nso_table_periods("DT_NSO_0300_001V2")
head(periods)