Package 'mongolstats'

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)

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)

Description

Adds a name_std column to an sf boundary object by transliterating, lowercasing, and stripping special characters from place names. This enables reliable joins between NSO data and administrative boundary polygons.

Usage

mn_boundaries_normalize(g, name_col = "shapeName")

Arguments

Value

An sf object with an additional name_std column.

Examples

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

Description

Returns a lightweight tibble of key columns from the GeoBoundaries data, including normalized names, without the full geometry. Useful for building custom crosswalks between NSO data and boundary identifiers.

Usage

mn_boundary_keys(level = "ADM1")

Arguments

Value

A tibble with key columns from GeoBoundaries and normalized names.

Examples

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

Description

Performs a fuzzy string-distance join between a data frame and boundary polygons. Useful when place-name spellings differ slightly between datasets (e.g., "Ulanbatar" vs "Ulaanbaatar").

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")

Description

Performs an exact join between a data frame and boundary polygons using normalized place names. Both sides are normalized via transliteration and lowercasing before joining.

Usage

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

Arguments

Value

An sf object 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")

Description

Clear cached entries

Usage

nso_cache_clear()

Value

No return value, called for side effects.

Examples

nso_cache_clear()

Description

Disable caching

Usage

nso_cache_disable()

Value

No return value, called for side effects.

Examples

nso_cache_disable()

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()

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()

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.

Table Structure Notes

Some NSO tables have unique dimension structures that affect how selections should be constructed:

• Air Quality Monthly Tables (e.g., DT_NSO_2400_015V1 to V6): These tables do not have a Year dimension. Instead, they use a running Month dimension with integer codes (e.g., "0" for the most recent month). Example: selections = list(Month = as.character(0:11)) retrieves the last 12 months.

Examples

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

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)

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

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)

Description

Retrieves the full catalogue of available statistical tables from the National Statistics Office PXWeb API. Uses the embedded index by default for fast startup; call nso_rebuild_px_index() to refresh from the API.

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)

Description

Filters the table catalogue to only those belonging to a given sector or sub-sector path, as returned by nso_sectors() or nso_subsectors().

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])

Description

Returns detailed variable metadata for a single table, including field names, item IDs, and labels in English and Mongolian when available.

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

Description

Performs a case-insensitive keyword search across the table catalogue, matching query against table names in English and/or Mongolian.

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")

Description

Disable offline mode

Usage

nso_offline_disable()

Value

Invisibly, TRUE.

Examples

nso_offline_disable()

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()

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)

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)

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")

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)

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)

Description

Performs a case-insensitive regex search across the table catalogue, optionally filtered to a specific sector. Searches table names in English and/or Mongolian by default.

Usage

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

Arguments

Value

Tibble of matching tables.

Examples

nso_search("population")

Description

Queries the PXWeb API root to return the top-level statistical sectors (e.g., Population, Economy, Environment). Use the returned id column with nso_subsectors() to drill into sub-categories.

Usage

nso_sectors()

Value

A tibble with columns id, type, and text.

Examples

sectors <- nso_sectors()
head(sectors)

Description

Navigates one level deeper in the PXWeb catalogue hierarchy. Pass in a path id obtained from nso_sectors() or a previous nso_subsectors() call to list its children (sub-sectors or tables).

Usage

nso_subsectors(subid)

Arguments

Value

A tibble with columns: id, type, text.

Examples

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

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

Description

Inspects the table metadata to find the time dimension and returns its available period labels (e.g., years or year-months).

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)

Description

Displays a human-readable summary of the query, including the table identifier and the first few dimension selections.

Usage

## S3 method for class 'nso_query'
print(x, ...)

Arguments

Value

x, invisibly.