📊 statistics

ICCDesign: An R Package for the Design and Analysis of ICC-Based Reliability Studies with Continuous Responses

本文介绍了 `ICCDesign` R 程序包，该程序包通过在由 McGraw 和 Wong (1996) 引导的统一框架内，将样本量规划、点估计、置信区间计算以及自动可靠性评估进行整合，为具有连续响应变量的基于 ICC 的可靠性研究提供了一个集成的设计与分析工作流。

原作者： Ziyu Liu, Ruilin Ma, Yundan Zhang, Chenge Gao

发布于 2026-06-02

📖 1 分钟阅读☕ 轻松阅读

CC BY 4.0

原作者： Ziyu Liu, Ruilin Ma, Yundan Zhang, Chenge Gao

原始论文采用 CC BY 4.0 许可（http://creativecommons.org/licenses/by/4.0/）。 ✨ 这是对下方论文的AI生成解释。它不是由作者撰写或认可的。如需技术准确性，请参阅原始论文。阅读完整免责声明

想象一下你是一名选秀节目的评委，你的评审团里还有另外五名评委。你想知道：这些评委之间的意见一致程度如何？ 他们对同一位歌手给出的分数是否相同？还是说一个评委热爱摇滚，而另一个却讨厌摇滚？

在科学和医学领域，研究人员每天都要面临这个完全相同的问题。他们需要一个叫做**组内相关系数（Intraclass Correlation Coefficient, ICC）**的工具来衡量他们的“评委”（或评分者）是否可靠。但直到现在，使用这个工具就像是在尝试按照一份用三种不同语言编写的说明书，并使用来自三个不同盒子的螺丝来组装一件家具。

这就是名为 ICCDesign 的新工具解决这一混乱问题的故事。

问题所在：缺少零件的拼图

几十年来，科学家们不得不为了完成一项工作而在不同的计算机程序之间跳来跳去：

一个程序告诉你要研究多少人（样本量）。
另一个程序计算一致性得分。
第三个程序检查这个得分是“好”还是“坏”。

更糟糕的是，“一致性”得分并不只有一种。根据你的研究设置（评委对每个人都是相同的吗？他们是一组随机抽取的评委，还是一个特定的团队？），有 10 种不同的方式来计算这个得分。选错了一种方式，就像是用尺子去测量房间而不是用卷尺——结果看起来是一个数字，但却是错误的答案。

解决方案：ICCDesign

本文作者——来自华东师范大学的一个团队——开发了一个名为 ICCDesign 的新 R 语言包。把它想象成可靠性研究中的**“瑞士军刀”**。你不再需要同时应付三种不同的工具，现在你拥有了一个全能的一站式工作站。

以下是它为何特别之处，通过简单的类比来解释：

1. 选择正确公式的“GPS”

这个领域最大的头疼问题是不知道该用哪 10 个公式中的哪一个。

旧方式： 你必须阅读厚厚的教科书，弄清楚你的研究设计，然后祈祷自己选对了数学公式。
ICCDesign 方式： 它自带一个内置的四步决策框架。它就像一个 GPS，会问你四个简单的问题：
1. 评分者对每个人进行评分吗？
2. 评委是随机样本还是固定团队？
3. 我们看的是单个得分还是平均值？
4. 我们需要他们在精确数值上达成一致，还是仅仅在模式上达成一致？
根据你的回答，该程序会自动选择正确的公式。如果你选择了一个需要警示的复杂组合，该程序会轻轻拍拍你的肩膀说：“嘿，用这个时要小心！”

2. “一站式”工作流

以前，研究人员必须在不同的软件窗口之间切换，复制并粘贴数字，这是出错和输入错误的温床。

ICCDesign 方式： 它在一个地方处理整个流程。你输入数据，它进行清洗（就像厨师在切菜前先洗菜），计算得分，检查置信区间（“误差范围”），甚至为你写出一份通俗易懂的报告。

3. 规划阶段的“水晶球”

在开始研究之前，你需要知道要招募多少人。

旧方式： 你可能会靠猜，或者使用一个只适用于特定场景的计算器。
ICCDesign 方式： 它有一个“水晶球”功能。你可以告诉它：“我希望我有 80% 的把握确保我的结果是准确的，”或者“我希望误差范围如此之小，”然后它会告诉你确切需要多少人。它还可以反向操作：“我有 30 个人；我的结果能有多准确？”

4. “红绿灯”报告

数学计算完成后，该程序不仅仅给你一个像“0.72”这样的数字。它会根据专家指南将这个数字转化为一个简单的等级：

< 0.50： 差（红灯）
0.50 – 0.75： 中等（黄灯）
0.75 – 0.90： 好（绿灯）
> 0.90： 极好（击掌欢呼）

如果结果处于边缘位置（例如一个可能是“好”也可能是“中等”的分数），该程序会添加一张便签说：“我们还不确定，你可能需要更多的数据。”

5. “无代码”仪表盘

对于那些害怕计算机代码的人，该程序包含了一个 Shiny Web App。这是一个你可以运行在电脑上的、具有交互性的彩色网站。你可以拖放你的数据，点击按钮做出选择，并立即看到结果，而无需编写任何一行代码。

它能做什么（以及不能做什么）

论文非常明确地界定了这个工具的边界：

它能： 处理连续型数值（如身高、体重或测试分数）、假设每人只有一个评分、并遵循著名统计学家（McGraw, Wong, Shrout, Fleiss）设定的标准规则。
它不能： 完美处理缺失数据（它只是删除了不完整的行）、处理“是/否”这类分类回答，或修复数据不平衡的研究（例如一个人有 5 名评委，而另一个人只有 2 名评委的情况）。

总结

ICCDesign 是一个让测量可靠性不再混乱的新工具。它将一个复杂、碎片化的过程变成了一个流畅、受引导的体验。它帮助研究人员停止纠结于应该使用哪种数学方法，转而开始关注他们的数据究竟意味着什么。

该工具是免费、开源的，现在任何人都可以使用。

ICCDesign 技术摘要：一个用于 ICC 设计与分析的 R 程序包

问题陈述

组内相关系数（ICC）是医学、心理学和行为科学领域可靠性研究中的基石统计量。然而，其在实际应用中面临两个显著障碍。首先，由 McGraw 和 Wong (1996) 建立的理论框架根据模型假设（单向 vs. 双向，随机效应 vs. 混合效应）和设计选择（单次评分 vs. 平均评分，绝对一致性 vs. 一致性），将 ICC 分为十种不同的设计组合（六种标准形式和四种附加组合）。选择正确的形式要求研究人员应对复杂的设计问题，然而现有的指南往往未能通过软件界面实现操作化。其次，目前的 R 生态系统中，ICC 分析工具是碎片化的。用于点估计的工具（如 irr, psych）、样本量计算工具（如 ICC.Sample.Size）以及可靠性评估工具分布在不同的程序包中。这种碎片化迫使研究人员在不同工具之间切换，增加了分析错误以及在规划阶段与分析阶段之间设计规范不一致的风险。

方法论

ICCDesign 程序包（版本 0.1.0）为连续响应数据提供了一个集成工作流，假设每个受试者-评分者单元只有一个评分。该方法论基于方差分析（ANOVA）框架，并遵循 Shrout 和 Fleiss (1979) 以及 McGraw 和 Wong (1996) 的分类系统。

1. 统计模型与估计：
该程序包实现了三种统计模型：

单向随机效应： 适用于评分者并非在受试者中作为共同集合的设计。
双向随机效应： 适用于受试者由同一组从更广泛人群中抽取的评分者进行评分的设计。
双向混合效应： 适用于评分者构成特定固定组的设计。

点估计使用基于方差分析（ANOVA）的均方（MSR, MSC, MSE, MSW）公式进行计算。该程序包支持所有十种设计组合，包括“谨慎使用”的情景（即计算程序共享但设计解释不同的情况，例如双向随机模型与混合模型下的一致性）。

2. 推断与假设检验：

置信区间 (CIs)： 程序包计算基于 F 分布的置信区间。对于标准形式，使用 Type 1 区间。对于双向模型中的绝对一致性，采用 Satterthwaite 型近似来修正自由度。所有报告的边界均被截断至可解释范围 $[0, 1]$ 。
假设检验： 它实现了针对两种情景的单侧 F 检验：一是默认的针对零值的检验（ $H_0: ICC = 0$ ），二是可选的针对用户指定最小可靠性阈值的检验（ $H_0: ICC = \rho_0$ ）。

3. 样本量规划：
基于 Zou (2012)，程序包提供三种规划模式：

下界保证 (Lower Bound Assurance)： 确定最小样本量 ( $n$ )，以确保置信区间下界以指定的保证概率超过目标阈值。
置信区间半宽 (Confidence Interval Half-Width)： 计算达到期望的 CI 精密度（半宽）且具有给定保证所需的 $n$ 。
逆向保证 (Inverse Assurance)： 计算固定样本量下的保证概率。

4. 可靠性评估：
自动评分采用 Koo 和 Li (2016) 提出的标准，该标准应用于置信区间的下界而非点估计值。如果置信区间跨越了“良好”可靠性阈值 (0.75)，系统会发出不确定性标记。

主要贡献

ICCDesign 程序包引入了一个统一的界面，整合了整个可靠性研究的工作流。其主要贡献包括：

全面的覆盖： 它实现了 McGraw 和 Wong (1996) 框架下所有十种 ICC 设计组合（包括四种额外的“谨慎使用”组合）的点估计、基于 ANOVA 的置信区间和假设检验。
四步决策框架： 一个结构化的参数系统引导用户从研究设计规范（评分者一致性、效应类型、评分单位、一致性类型）过渡到适当的 ICC 形式。该系统针对特殊情况提供明确的反馈（备注 NOTES 或警告 WARNINGS），例如在计算程序之间的自动映射或对固定评分者绝对一致性推断的限制。
集成的规划与分析： 该程序包将样本量规划（通过 Zou 的闭式公式）与数据分析统一起来，确保在整个研究生命周期内设计规范的一致性。
自动化的报告与可视化： 它生成标准化的文本格式分析报告，并包含一个交互式的 Shiny Web 应用程序，允许用户在不编写 R 代码的情况下完成完整的工作流。
数据预处理工具： 一个专门的函数 (icc_preprocess_data) 在分析前验证数据格式、维度和缺失值，从而增强透明度和数据质量控制。

结果与能力

本文通过使用内置的模拟数据集展示了程序包的功能。示例涵盖了：

预处理宽格式数据。
计算各种 ICC 形式（例如 ICC(1,1), ICC(2,1), ICC(3,k)）。
进行自定义阈值的假设检验。
处理带有适当用户通知的“谨慎使用”组合。
执行用于下界保证、CI 宽度和逆向保证的样本量计算。
启动 Shiny 应用程序以进行无代码工作流。

与现有程序包（irr, psych, ICC.Sample.Size, irrNA）的比较表明，ICCDesign 是唯一提供全覆盖设计组合、自动化决策引导、专用预处理以及统一规划与分析界面的工具。

意义与声明

作者将 ICCDesign 定位为不是一种新的统计估计方法的提议，而是将既定程序整合为一个凝聚的、用户友好的界面。这项工作的意义在于解决当前工具的碎片化以及缺乏选择正确 ICC 形式的操作指导的问题。通过将设计规范、样本量规划、估计、推断和报告整合到单个程序包中，ICCDesign 旨在减少操作错误并提高可靠性研究的严谨性。该程序包在 GitHub 上以 GPL (>= 3) 许可协议提供，未来计划提交至 CRAN 并扩展对缺失数据和自助法（bootstrap）区间的支持。