LISTC 入门:从样本数据到带标准误的透视统计表

LISTC 把测评/调查样本数据变成像 Excel 数据透视表一样可自由定制的统计表——不同的是,每个单元格都带有测量学上正确的标准误 (抽样方差 + 由个体 IRT 标准误传递的测量方差)。

本文覆盖三种用法:统计人员的函数 API、调查人员的配置模板, 以及给 AI agent 的机器可读输出。

准备示例数据

library(LISTC)
set.seed(2026)
n <- 3000
demo <- data.frame(
  student_id = sprintf("S%05d", seq_len(n)),
  region = sample(c("东部", "中部", "西部"), n, TRUE, c(.4, .35, .25)),
  gender = sample(c("男", "女"), n, TRUE),
  w_final = runif(n, 0.5, 2),
  th_math = rnorm(n),
  se_math = runif(n, 0.25, 0.45),
  raw_total = rpois(n, 40)
)

第一步:声明变量角色

lst_data() 给数据框贴上”角色”标签。theta 与 theta_se 必须按维度成对声明:

x <- lst_data(demo,
  id = student_id,
  group = c(region, gender),
  weight = w_final,
  theta = c(math = th_math),
  theta_se = c(math = se_math),
  score = raw_total
)
x
#> <listc_data> 3000 行 x 7 列
#>   id: student_id
#>   group: region, gender
#>   weight: w_final
#>   score: raw_total
#>   theta: math=th_math
#>   theta_se: math=se_math

第二步:定义透视表

行、列、单元格统计量自由组合;margins = TRUE 追加合计行列:

lv <- c(待提高 = -Inf, 合格 = -0.5, 良好 = 0.5, 优秀 = 1.2)
tab <- lst_table(x,
  rows = region, cols = gender,
  values = list(
    平均能力 = st_mean(math),
    优秀率 = st_prop_above(math, cutoff = 1.2, method = "prob"),
    等级 = st_level_prop(math, breaks = lv, method = "prob"),
    人数 = st_count()
  ),
  margins = TRUE
)
tab
#> <listc_table> region x gender | 统计量: 平均能力, 优秀率, 等级, 人数 | format = est_se
#> 
#>  region  女_平均能力 男_平均能力 合计_平均能力      女_优秀率      男_优秀率
#>    东部  0.02 (0.05) 0.01 (0.04)   0.01 (0.03) 13.64% (1.37%) 12.38% (1.28%)
#>    中部  0.09 (0.05) 0.03 (0.05)   0.06 (0.04) 14.10% (1.49%) 14.63% (1.49%)
#>    西部 -0.08 (0.06) 0.04 (0.07)  -0.02 (0.04) 11.60% (1.61%) 15.63% (1.91%)
#>    合计  0.02 (0.03) 0.02 (0.03)   0.02 (0.02) 13.30% (0.86%) 13.94% (0.87%)
#>     合计_优秀率 女_等级_待提高   女_等级_合格   女_等级_良好   女_等级_优秀
#>  13.01% (0.94%) 31.44% (1.83%) 37.31% (1.72%) 17.61% (1.26%) 13.64% (1.37%)
#>  14.37% (1.05%) 28.37% (1.89%) 38.45% (1.86%) 19.08% (1.39%) 14.10% (1.49%)
#>  13.58% (1.25%) 32.90% (2.39%) 37.86% (2.22%) 17.63% (1.61%) 11.60% (1.61%)
#>  13.62% (0.61%) 30.74% (1.15%) 37.84% (1.10%) 18.12% (0.81%) 13.30% (0.86%)
#>  男_等级_待提高   男_等级_合格   男_等级_良好   男_等级_优秀 合计_等级_待提高
#>  31.20% (1.81%) 37.38% (1.71%) 19.03% (1.28%) 12.38% (1.28%)   31.32% (1.29%)
#>  32.06% (1.99%) 34.12% (1.81%) 19.19% (1.39%) 14.63% (1.49%)   30.25% (1.38%)
#>  31.21% (2.40%) 35.54% (2.24%) 17.62% (1.62%) 15.63% (1.91%)   32.07% (1.69%)
#>  31.51% (1.17%) 35.79% (1.09%) 18.76% (0.81%) 13.94% (0.87%)   31.13% (0.82%)
#>  合计_等级_合格 合计_等级_良好 合计_等级_优秀 女_人数 男_人数 合计_人数
#>  37.34% (1.21%) 18.33% (0.90%) 13.01% (0.94%)     600     609      1209
#>  36.24% (1.30%) 19.14% (0.98%) 14.37% (1.05%)     530     531      1061
#>  36.72% (1.58%) 17.63% (1.14%) 13.58% (1.25%)     367     363       730
#>  36.81% (0.77%) 18.44% (0.57%) 13.62% (0.61%)    1497    1503      3000

as_long() 返回 tidy 长表,包含 SE 的三个分量 (se_sampling / se_measurement / se_total),可直接进入 tidyverse 流程做二次计算:

head(as_long(tab))
#> # A tibble: 6 × 10
#>   region gender statistic category estimate se_sampling se_measurement se_total
#>   <chr>  <chr>  <chr>     <chr>       <dbl>       <dbl>          <dbl>    <dbl>
#> 1 中部   女     平均能力  <NA>       0.0861      0.0466         0.0165   0.0495
#> 2 东部   男     平均能力  <NA>       0.0127      0.0412         0.0153   0.0440
#> 3 东部   女     平均能力  <NA>       0.0159      0.0434         0.0153   0.0460
#> 4 西部   男     平均能力  <NA>       0.0357      0.0623         0.0196   0.0653
#> 5 中部   男     平均能力  <NA>       0.0261      0.0492         0.0162   0.0518
#> 6 西部   女     平均能力  <NA>      -0.0838      0.0574         0.0195   0.0606
#> # ℹ 2 more variables: n <int>, sum_w <dbl>

方法说明:prob 与 correction 怎么选

method = "hard":按点估计硬分类。简单,但分数线附近的误分类会使等级占比有偏。
method = "prob"(推荐):利用每个人的 theta ± SE 计算落入各等级的概率再聚合,对测量误差稳健。
correction 取决于能力值的估计方法:
- EAP + 后验标准差(如 flexMIRT/mirt 的 EAP 输出): 保持默认 "none"。概率化公式此时就是后验概率,聚合结果已经校准——蒙特卡洛实验显示不需要额外校正。
- WLE/ML + 抽样标准误(如 Winsteps/ConQuest 的 WLE): 用 "latent"。无偏估计的观测分布比潜在分布更散,naive 概率化会高估极端等级占比;"latent" 先做经验贝叶斯收缩 (可靠性 rho 自动估计,也可用 rho = 显式给定)。

lst_table(x, rows = region, values = list(
  优秀率_latent = st_prop_above(math, cutoff = 1.2,
                                method = "prob", correction = "latent")
))
#> <listc_table> region x  | 统计量: 优秀率_latent | format = est_se
#> 
#>  region  优秀率_latent
#>    东部 10.34% (0.84%)
#>    中部 11.56% (0.95%)
#>    西部 11.00% (1.13%)

第三步:输出

lst_to_excel(tab, "results.xlsx", overwrite = TRUE) # 中文样式 + 结论 sheet
lst_to_json(tab)                                    # 给 AI agent / 二次分析
lst_interpret(tab)                                  # 规则化自动解读文字

调查人员:配置模板 + 一键运行

不写 R 代码的同事可以填 Excel 配置簿:

lst_config_template("LISTC配置.xlsx") # 生成模板,按"说明"sheet 填写
lst_run("LISTC配置.xlsx")             # 一键出全部结果

YAML/JSON 配置与之等价(AI agent 通常生成这种), schema 见 system.file("schema/config.schema.json", package = "LISTC"), 面向 LLM 的 API 文档见 system.file("llms.txt", package = "LISTC")。