# =============================================================================
# R/data.R
#
# Roxygen documentation for datasets shipped with DSIR.
# Datasets themselves are generated by data-raw/who_countries.R.
# =============================================================================


#' WHO Member States with regional and Pacific classifications
#'
#' A tibble of the 194 World Health Organization (WHO) Member States, with
#' standard country identifiers and WHO/Pacific groupings used across DSIR
#' analytical workflows.
#'
#' @format A tibble with 194 rows and 7 columns:
#' \describe{
#'   \item{iso3}{ISO 3166-1 alpha-3 code (3-letter, e.g. `"PHL"`).}
#'   \item{iso2}{ISO 3166-1 alpha-2 code (2-letter, e.g. `"PH"`).}
#'   \item{m49_code}{UN M49 numeric code, stored as a 3-character string with
#'   leading zeros where present (e.g. `"008"` for Albania). Stored as
#'   character because some downstream APIs (notably the UN SDG API) expect
#'   the leading-zero form.}
#'   \item{name_official}{WHO official English name (e.g.
#'   `"Iran (Islamic Republic of)"`). Use for formal documents and reports.}
#'   \item{name_short}{A shorter form suitable for charts and tables (e.g.
#'   `"Iran"`). Equal to `name_official` for countries whose official name
#'   is already concise. See Details.}
#'   \item{who_region}{WHO region code: one of `"AFR"`, `"AMR"`, `"SEAR"`,
#'   `"EUR"`, `"EMR"`, `"WPR"`.}
#'   \item{is_pic}{Logical. `TRUE` for the 14 Pacific Island Country (PIC)
#'   Member States in WPR, `FALSE` otherwise.}
#' }
#'
#' @details
#' **Scope.** WHO has 194 Member States plus 2 Associate Members
#' (Puerto Rico, Tokelau) and reports on additional non-Member areas
#' (e.g. West Bank and Gaza Strip). This dataset includes only the 194
#' Member States. Cook Islands and Niue are full WHO Member States and
#' are included even though they are not UN member states.
#'
#' **Region coverage** (as of May 2025, after WHO EB156 reassignment of
#' Indonesia from SEAR to WPR):
#' \itemize{
#'   \item AFR (African Region): 47
#'   \item AMR (Region of the Americas): 35
#'   \item SEAR (South-East Asia Region): 10
#'   \item EUR (European Region): 53
#'   \item EMR (Eastern Mediterranean Region): 21
#'   \item WPR (Western Pacific Region): 28
#' }
#'
#' **Short names.** `name_short` differs from `name_official` for 13
#' countries where the official name is a parenthetical descriptor or is
#' otherwise long. Examples: `"DPR Korea"`, `"DR Congo"`, `"Lao PDR"`,
#' `"United Kingdom"`. These short forms follow conventions used in WHO
#' regional reports and OECD Health at a Glance: Asia/Pacific.
#'
#' **PICs.** The Pacific Island Countries flag (`is_pic`) marks the 14
#' WHO Member States in the Pacific sub-region: Cook Islands, Fiji,
#' Kiribati, Marshall Islands, Micronesia (Federated States of), Nauru,
#' Niue, Palau, Papua New Guinea, Samoa, Solomon Islands, Tonga, Tuvalu,
#' and Vanuatu. Non-Member Pacific areas (e.g. New Caledonia, French
#' Polynesia, American Samoa) are not included in this dataset.
#'
#' @source
#' \itemize{
#'   \item WHO official region listing:
#'   \url{https://www.who.int/countries}
#'   \item ISO 3166-1 codes and UN M49 numeric codes: UN Statistics Division
#'   \url{https://unstats.un.org/unsd/methodology/m49/}
#' }
#'
#' @examples
#' # All WPR Member States, sorted alphabetically by short name
#' wpr <- who_countries[who_countries$who_region == "WPR", ]
#' wpr <- wpr[order(wpr$name_short), c("iso3", "name_short")]
#' head(wpr)
#'
#' # Filter a data frame to PIC member states
#' # df_pic <- subset(my_data, country_iso3 %in% who_countries$iso3[who_countries$is_pic])
"who_countries"


#' WHO regional Member State ISO3 vectors
#'
#' Convenience character vectors of ISO3 codes for the WHO Member States
#' in each region. Each vector is the regional subset of
#' [`who_countries`]'s `iso3` column, sorted alphabetically.
#'
#' @details
#' These are derived directly from [`who_countries`] and exist for
#' ergonomic filtering, e.g.
#' `dplyr::filter(data, iso3 %in% wpro_cty)`.
#' If you need to update group membership, edit
#' `data-raw/who_countries.R` and re-run that script — the vectors
#' regenerate from the master table.
#'
#' \describe{
#'   \item{`afro_cty`}{47 Member States in the WHO African Region.}
#'   \item{`amro_cty`}{35 Member States in the WHO Region of the Americas.}
#'   \item{`searo_cty`}{10 Member States in the WHO South-East Asia Region.}
#'   \item{`euro_cty`}{53 Member States in the WHO European Region.}
#'   \item{`emro_cty`}{21 Member States in the WHO Eastern Mediterranean
#'   Region.}
#'   \item{`wpro_cty`}{28 Member States in the WHO Western Pacific Region.
#'   Includes Indonesia from May 2025 (per WHO EB156).}
#' }
#'
#' @format Character vectors of ISO 3166-1 alpha-3 codes.
#'
#' @seealso [`who_countries`], [`pic_cty`].
#'
#' @examples
#' length(wpro_cty)        # 28
#' "IDN" %in% wpro_cty     # TRUE — Indonesia in WPR since May 2025
#'
#' @name who_region_vectors
NULL

#' @rdname who_region_vectors
"afro_cty"

#' @rdname who_region_vectors
"amro_cty"

#' @rdname who_region_vectors
"searo_cty"

#' @rdname who_region_vectors
"euro_cty"

#' @rdname who_region_vectors
"emro_cty"

#' @rdname who_region_vectors
"wpro_cty"


#' Pacific Island Country ISO3 codes
#'
#' Character vector of ISO3 codes for the 14 WHO Member States classified
#' as Pacific Island Countries (PICs). Sorted alphabetically.
#'
#' @details
#' All 14 PICs are within the Western Pacific Region, so
#' `all(pic_cty %in% wpro_cty)` is `TRUE`. Non-Member Pacific areas
#' (e.g. New Caledonia, French Polynesia, American Samoa, Tokelau) are
#' not included.
#'
#' The 14 PIC Member States are: Cook Islands, Fiji, Kiribati, Marshall
#' Islands, Micronesia (Federated States of), Nauru, Niue, Palau, Papua
#' New Guinea, Samoa, Solomon Islands, Tonga, Tuvalu, and Vanuatu.
#'
#' @format A character vector of 14 ISO 3166-1 alpha-3 codes.
#'
#' @seealso [`who_countries`], [`wpro_cty`].
#'
#' @examples
#' length(pic_cty)              # 14
#' all(pic_cty %in% wpro_cty)   # TRUE
"pic_cty"
