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

The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

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

从 IRT 软件导入人参数

pf <- read_winsteps_pfile("person.pfile")   # 或 read_conquest_person()
x <- lst_data(demo, id = student_id, group = region) |>
  lst_join_person(pf, dim = "math")

局限与展望

SE 传递假定个体测量误差相互独立;整群抽样的设计效应需要 replicate weights(计划 v0.3)。
plausible values 的 Rubin 合并计划 v0.4。
correction = "latent" 基于正态模型;偏态潜在分布下是近似。

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.