Tidy a GHO Data Frame

Selects, renames, and type-casts the most useful columns from a GHO observation table returned by gho_data(), producing a compact tibble in the unified DSIR cleaned-indicator schema — the same schema produced by sdg_clean(), so the two outputs can be combined directly with bind_indicators().

Usage

gho_clean(
  df,
  keep_dimensions = FALSE,
  keep_metadata = FALSE,
  output = c("dsir_data", "tibble")
)

Arguments

df: A data frame returned by gho_data().
keep_dimensions: Logical. Append dim1_type, dim2_type, and dim3_type from the source's Dim1Type, Dim2Type, and Dim3Type? Default FALSE. Types are kept per row: one indicator can use the same position for different dimensions. No type is guessed from a code's spelling, and missing types remain NA. xMart output also retains all named source dimensions as dim_* character columns.
keep_metadata: Logical. Retain source context? Default FALSE. With TRUE, appends provider ("legacy" or "xmart") from recorded retrieval provenance; unknown origins remain NA, never the current session setting. Also appends character columns observation_id, spatial_type, time_type, data_source_type, data_source, updated, parent_location, parent_location_name, time_detail, time_start, and time_end, copied from the raw API fields. Raw Comments are kept as footnotes, a list-column of character vectors. Missing scalar fields are NA; missing list fields are empty character vectors. This option is independent of keep_dimensions. Unit and dimension labels are not inferred. xMart output also retains unit, measure_field, and spatial_type_source. Both backends preserve acquisition provenance in the object metadata, including with the default 15-column output. Plain tibble output also keeps who_provenance. Retaining these fields makes no extra network requests beyond the usual indicator-name lookup.
output: Return a "dsir_data" tibble subclass (default) or a plain "tibble". Both carry acquisition and cleaning metadata as attributes; inspect them with dsir_metadata(). This does not add table columns.

Value

A dsir_data tibble, or a plain tibble when requested, with 15 core columns: source (always "gho"), id, indicator, location, iso3, location_name, year, value, value_num, low, high, series (NA), dim1, dim2, dim3. Sorted by location then year. Empty input returns an empty tibble with the same columns and types. Optional dimension types and metadata follow the core columns.

Details

The mapping (GHO source → unified column) is:

IndicatorCode → id
IndicatorCode resolved against the GHO indicator catalog → indicator (the human-readable name; cached at session level after the first call)
SpatialDim → location; also iso3 when it matches a WHO Member State, otherwise iso3 = NA
TimeDim → year (integer)
Value → value (character; raw)
NumericValue → value_num (numeric)
Low, High → low, high (numeric)
Dim1, Dim2, Dim3 → dim1, dim2, dim3 (character)

The series column is always NA for GHO output (it is an SDG-only concept; GHE uses it for measure codes). The location_name column is populated by looking up location (an ISO3 code or a WHO region code) against the who_countries dataset and a hardcoded set of WHO regional names; other locations use a published SpatialName when available, otherwise they remain NA.

Source columns absent from df (e.g. Low / High for indicators without confidence intervals) are filled with typed NA, so the default output always has the same 15 columns with the same column types.

xMart supplies indicator labels through its official directory. Legacy observations without an IndicatorName use gho_indicators() with the backend recorded in their Provider column or who_provenance attribute, even if the session default has changed since retrieval. Older/imported data without provenance use the session default for this label lookup. For such input, on the first call within an R session, gho_clean() fetches the catalog once and caches it for the rest of the session, so the indicator column carries the full human-readable indicator name. If the catalog cannot be fetched (e.g. no network), gho_indicators() warns and legacy labels use its bundled snapshot without caching it as live data. Codes absent from that snapshot, or unavailable xMart labels, remain NA.

Retrieval metadata

Downloads and directories retain their existing classes and columns. dsir_metadata(x)$sources records the actual backend, endpoint, UTC retrieved_at, retrieval status, cache use, source record count, reported API version and release. Unknown versions and times remain NA. Each source row includes its own server query. query records the public selection, including local filters and reference-country/year restrictions. result describes the function's original return; current is computed from the supplied object. Source counts precede local filtering and GHE measure pivoting, so they can differ from returned row counts.

Result status distinguishes success, empty, failed, incomplete, invalid, partial and unverified. Completeness concerns the requested retrieval, not global indicator coverage. It is NA when the response lacks sufficient completeness information. A successful HTTP response alone does not establish completeness of an observation download.

Cached records retain their original retrieval time and set cache_hit. A historical fallback uses retrieval_status = "bundled_snapshot" and retains the original collection date. It does not prove live availability. Failed SDG list requests still return NULL with a warning; NULL cannot carry metadata. Other empty failure results record no successful retrieval time. Existing WHO who_provenance and catalog_snapshot attributes remain available for compatibility.

Cleaners preserve acquisition metadata even for empty input. This is independent of keep_metadata, which controls optional data columns. as_dsir_data() also retains sources, query and result. These are historical acquisition records, not an audit of arbitrary changes to a plain tibble. Use the S3 object's processing status to track supported transformations. saveRDS() preserves attributes; CSV does not.

Cleaning records live in cleaning, also for output = "tibble" and user-supplied input without acquisition records. They contain the cleaner, package version, UTC cleaning time, input/output sizes and columns, options, and a profile of semantic fields. Each profile records its retained column (or NA), distinct count including missing values, missing count and its constant value, if any. Varying omitted values are not stored row by row. Recorded aliases link equivalent core and named dimensions. Cleaning time never substitutes for retrieval time. These records describe the cleaning input; current coverage and subsequent field status remain separate.

Examples

# \donttest{
gho_data("NCDMORT3070", spatial_type = "country") |>
  gho_clean()
# }