WHO xMart 与全球卫生估计 • DSIR

DSIR 0.13.0 默认使用 backend = 'auto'，优先查询 WHO 公共 xMart 服务。仅当成功读取的目录未列出该确切代码，或确认整个指标的观测数为零时，才尝试旧版服务。在应用国家、年份或维度筛选前，系统通过一个小型请求核实指标是否有数据。筛选后没有结果或覆盖不完整不会触发回退，也不会合并不同发布版本。显式设置 backend = 'xmart' 或 backend = 'legacy' 始终固定数据服务。全球卫生估计（GHE）始终使用 xMart。下载失败后不会切换服务。构建教程时，下列联网示例仅展示代码，不执行。

本文代码与英文版共用；数据源的代码、字段名和返回标签保持原样。首次使用请先阅读 DSIR 入门。

查询 GHO 代码并保留命名维度

gho_indicators('mortality', backend = 'xmart')
gho_dimensions('NCDMORT3070', 'DIM_SEX', backend = 'xmart')
ncd <- gho_data('NCDMORT3070', area = 'PHL', year_from = 2020,
                year_to = 2021, dimensions = list(DIM_SEX = 'TOTAL'),
                backend = 'xmart')
gho_clean(ncd, keep_dimensions = TRUE, keep_metadata = TRUE)

公共目录提供已发布的数据路径和指标标识。宽表保存命名维度和数值度量组；长表保存明确的维度类型与成员配对。DSIR 将两种结构映射为已有的原始字段。gho_clean() 默认保留 15 列；可选的命名字段保留类别含义，可选元数据保留单位及行级 provider 字段。

GHO 原始观测包含 Provider 列和 who_provenance 属性。即使会话选项后来改变，缺失标签仍按已记录的数据服务查询。无法确定来源的导入数据保持 NA。维度位置可能不同于旧版 Dim1–Dim3，建议使用命名筛选条件。

xMart 目录与旧版目录包含的代码和发布版本可能不同。未知代码会触发警告，不会替换成相似代码。GHO 查询函数（包括更新时间查询）均接受 backend；显式参数优先于 DSIR.who_backend，但不会修改该选项。未设置选项时使用 auto。auto 模式的关键词检索只查询 xMart。使用 gho_indicators(backend = 'legacy') 可以查看旧版独有代码；旧版在线目录请求失败时会使用带有采集日期的内置目录。查询代码、维度、行数、覆盖范围和数据时，应使用同一个后端。

自动回退会发出警告，并在结果的 who_provenance 属性中记录 requested_backend、实际 backend 和 fallback_reason，行数和有无数据的标量结果也包含这些信息。回退保留已知 WHO ISO3／区域代码及年份筛选，但不会转换命名或位置维度，也不会转换 M49／原生地区代码。这些筛选会阻止回退，不会被丢弃。维度查询仅允许 SpatialDim、SpatialDimType、TimeDim 和 TimeDimType 自动回退。使用服务特有的约定时，请显式固定后端。缺少时间戳不会触发切换。每次调用都会重新检查选择条件。

financial <- gho_data('FINANCIALHARDSHIP_PROPORTIONOFPOP', area = 'PHL',
                       backend = 'legacy')
gho_clean(financial, keep_dimensions = TRUE, keep_metadata = TRUE)

# Optional session default; explicit arguments still take precedence.
options(DSIR.who_backend = 'xmart')
gho_indicators('mortality', backend = 'legacy')

查询成功但没有匹配观测时，会显示提示信息；此时 gho_has_data() 返回 FALSE，gho_count() 返回 0L。请求或解析失败时会警告，返回空表或 NA。xMart 目录中的未知代码会触发警告。旧版服务返回 HTTP 404 时，会先小规模查询目录，再判断指标是否不存在；目录查询失败不能证明指标不存在。请求和解析失败均不会触发自动回退。

查询 GHE 可选值

ghe_dimensions('year')
ghe_dimensions('area')
ghe_dimensions('sex')
ghe_dimensions('age')
ghe_dimensions('measure')
ghe_causes('diabetes')
ghe_causes('stroke')

官方年份和性别参考表较小。地理列表使用最新年份、全死因、全年龄、男女合计的观测；年龄和死因列表使用按 ISO3 排序的第一个可用 WHO 会员国的一小部分数据，避免对整个数据库进行高成本分组。这些列表用于探索，实际选择的覆盖范围应通过 ghe_coverage() 核实。部分观测中的年龄代码没有对应的官方标签，其标签保持缺失。

死因的 level、cause_group、rankable 和 single_cause 来自数据提供方。数据源没有发布父级代码字段，分组代码不能视作父级代码。不要把某层级的合计与其下级类别再次相加。

下载指定度量

phl_deaths <- ghe_data('PHL', year = 2023, age = 'TOTAL', sex = 'TOTAL',
                       cause = 0, measure = 'deaths')
phl_rates <- ghe_data('PHL', year = 2023, age = 'Y40T44',
                      sex = c('FEMALE', 'MALE'), cause = 0,
                      measure = 'death_rate')
ghe_coverage('PHL', age = 'TOTAL', sex = 'TOTAL', cause = 0)
ghe_clean(phl_rates, keep_dimensions = TRUE)

计数的单位是死亡人数或年数；率以每 10 万人为单位；占比为百分比。计数保留已发布的不确定性区间。API 未提供率和占比的区间，DSIR 不会通过计算补齐缺失界限。

年龄为 TOTAL 的率是粗率，选定五岁年龄组得到的是年龄别率。不同年龄汇总组可能重叠，不能把所有返回年龄组相加作为总数。

measure = NULL 将所有支持的度量分别作为行返回，因此原始行数与最终长表行数不同。覆盖范围统计的是原始观测数。所有筛选条件均为 NULL 的请求会被拒绝；超过一百万条原始行时，需要缩小筛选范围，或显式设置 DSIR.who_max_rows。较大的筛选条件在内部通过带文本请求体的 POST 发送。

可复现下载与估计修订

phl <- snapshot(
  ghe_data('PHL', year = 2023, age = 'TOTAL', sex = 'TOTAL', cause = 0,
            measure = 'deaths'),
  'data/phl_ghe_2023.rds'
)
attr(phl, 'who_provenance')

参考数据缓存在内存中保存，十分钟后失效。snapshot() 仅写入你指定的路径。GHE 新版本可能修订历史年份：WHO 于 2026 年发布的 2023 年估计值，与旧版 2021 年发布数据不能直接视为可比。DSIR 使用 DEX_CMS/GHE_FULL，而非旧版 GHE_FULL_FOCUS 或 GHE_FULL_DD 视图。

WHO 2026 标准人口

从 DSIR 0.11.0 开始，who_std_pop 使用 WHO 2026 标准人口。官方表包含截至 85+ 的 18 个年龄组。四舍五入后的百分比合计为 100.02，DSIR 将其归一化至 100。std_million 是按比例放大到一百万的数值型人数，不作整数舍入。

who_std_pop
#> # A tibble: 18 × 4
#>    age_group age_start weight std_million
#>    <chr>         <int>  <dbl>       <dbl>
#>  1 0-4               0   7.21      72086.
#>  2 5-9               5   7.13      71286.
#>  3 10-14            10   7.11      71086.
#>  4 15-19            15   7.12      71186.
#>  5 20-24            20   7.15      71486.
#>  6 25-29            25   7.08      70786.
#>  7 30-34            30   6.89      68886.
#>  8 35-39            35   6.66      66587.
#>  9 40-44            40   6.35      63487.
#> 10 45-49            45   6.04      60388.
#> 11 50-54            50   5.75      57489.
#> 12 55-59            55   5.41      54089.
#> 13 60-64            60   4.97      49690.
#> 14 65-69            65   4.43      44291.
#> 15 70-74            70   3.77      37692.
#> 16 75-79            75   2.98      29794.
#> 17 80-84            80   2.08      20796.
#> 18 85+              85   1.89      18896.
count <- seq_len(nrow(who_std_pop))
population <- rep(10000, nrow(who_std_pop))
age_standardize(count, population, who_std_pop$weight)
#> [1] 79.68206

原来的标准人口对象已被替换。使用权重前，应将观测年龄归并到已发布的年龄组；本包没有提供 0-4 或 85+ 内部更细的划分。来源：WHO/HSA/DDA/GHE/2026.4，第 6 页表 1。

下一步：卫生指标可视化。