performance

检验你的模型是否优秀！

在构建回归模型时，评估模型拟合质量至关重要。了解模型对数据的拟合程度以及应报告哪些拟合指标非常重要。虽然已经存在用于创建诊断图或计算拟合度量的函数，但这些功能大多分散在不同的包中。对于不同类型的模型，目前尚无统一且一致的方法来评估模型质量。

performance 包的主要目标是填补这一空白，提供用于计算模型质量指标和拟合优度的工具。这些指标包括 R 平方 (R²)、均方根误差 (RMSE) 或组内相关系数 (ICC) 等，同时也包含用于检查（混合）模型是否存在过度离散、零膨胀、收敛问题或奇异性的函数。

安装

performance 包可在 CRAN 上获取，而其最新的开发版本则可在 R-universe（由 rOpenSci 提供）上获得。

类型	来源	命令
发布版	CRAN	install.packages("performance")
开发版	R-universe	install.packages("performance", repos = "https://easystats.r-universe.dev")

下载完成后，可以使用以下命令加载该包：

library("performance")

提示

与其使用 library(performance)，不如使用 library(easystats)。这样可以同时使用 easystats 生态系统中的所有功能。

若要保持更新，请使用 easystats::install_latest()。

引用

在出版物中引用 performance 包时，请使用以下命令：

citation("performance")
#> 要在出版物中引用 'performance' 包，请使用：
#> 
#>   Lüdecke 等，(2021). performance: 用于评估、比较和检验统计模型的 R 包。开放源码软件期刊，6(60)，3139。
#>   https://doi.org/10.21105/joss.03139
#> 
#> 对于 LaTeX 用户，BibTeX 条目如下：
#> 
#>   @Article{,
#>     title = {{performance}: 用于评估、比较和检验统计模型的 {R} 包},
#>     author = {Daniel Lüdecke、Mattan S. Ben-Shachar、Indrajeet Patil、Philip Waggoner 和 Dominique Makowski},
#>     year = {2021},
#>     journal = {开放源码软件期刊},
#>     volume = {6},
#>     number = {60},
#>     pages = {3139},
#>     doi = {10.21105/joss.03139},
#>   }

文档

在 youtube 上有一段关于该包的精彩介绍。

performance 工作流程

评估模型质量

R 平方

performance 提供了一个通用的 r2() 函数，可用于计算多种不同模型的 R 平方值，包括混合效应模型和贝叶斯回归模型。

r2() 返回一个列表，其中包含与给定模型“最适当”的 R 平方相关的值。

model <- lm(mpg ~ wt + cyl, data = mtcars)
r2(model)
#> # 线性回归的 R2
#>        R2: 0.830
#>   adj. R2: 0.819

model <- glm(am ~ wt + cyl, data = mtcars, family = binomial)
r2(model)
#> # 逻辑回归的 R2
#>   Tjur's R2: 0.705

library(MASS)
data(housing)
model <- polr(Sat ~ Infl + Type + Cont, weights = Freq, data = housing)
r2(model)
#>   Nagelkerke's R2: 0.108

此外，还可以通过诸如 r2_bayes()、r2_coxsnell() 或 r2_nagelkerke() 等函数直接访问不同的 R 平方度量（完整函数列表请参见 此处）。

对于混合模型，会返回条件 R 平方和边际 R 平方。边际 R 平方仅考虑固定效应的方差，表示模型方差中有多少是由固定效应部分解释的。而条件 R 平方则同时考虑固定效应和随机效应，表示模型方差中有多少是由“完整”模型解释的。

对于频率学派的混合模型，r2()（或 r2_nakagawa()）会计算随机效应方差的平均值，因此 r2() 也适用于具有更复杂随机效应结构的混合模型，例如随机斜率或嵌套随机效应（Johnson 2014；Nakagawa、Johnson 和 Schielzeth 2017）。

set.seed(123)
library(rstanarm)

model <- stan_glmer(
  Petal.Length ~ Petal.Width + (1 | Species),
  data = iris,
  cores = 4
)

r2(model)
#> # 兼容区间内的贝叶斯 R2
#> 
#>   有条件的 R2: 0.954（95% CI [0.951, 0.957]）
#>      边际的 R2: 0.414（95% CI [0.204, 0.644]）

library(lme4)
model <- lmer(Reaction ~ Days + (1 + Days | Subject), data = sleepstudy)
r2(model)
#> # 混合模型的 R2
#> 
#>   有条件的 R2: 0.799
#>      边际的 R2: 0.279

组内相关系数 (ICC)

与 R 平方类似，ICC 也提供了关于已解释方差的信息，可以被理解为“群体中由分组结构所解释的方差比例”（Hox 2010）。

icc() 可以计算各种混合模型对象的 ICC，包括 stanreg 模型。

library(lme4)
model <- lmer(Reaction ~ Days + (1 + Days | Subject), data = sleepstudy)
icc(model)
#> # 组内相关系数
#> 
#>     调整后的 ICC: 0.722
#>   未调整的 ICC: 0.521

以及 brmsfit 类型的模型。

library(brms)
set.seed(123)
model <- brm(mpg ~ wt + (1 | cyl) + (1 + wt | gear), data = mtcars)

icc(model)
#> # 组内相关系数
#> 
#>     调整后的 ICC: 0.930
#>   未调整的 ICC: 0.771

模型诊断

检查过度离散

当数据中的观测方差高于模型假设所预期的方差时，就会出现过度离散现象（对于泊松分布而言，方差大致等于因变量的均值）。check_overdispersion() 函数用于检查计数模型（包括混合效应模型）是否存在过度离散。

library(glmmTMB)
data(Salamanders)
model <- glm(count ~ spp + mined, family = poisson, data = Salamanders)
check_overdispersion(model)
#> # 过度离散检验
#> 
#>        离散比 =    2.946
#>   Pearson卡方统计量 = 1873.710
#>                 p值 =  < 0.001

解决过度离散的方法有两种：一是对离散参数进行建模（并非所有软件包都支持），二是选择不同的分布族（如准泊松分布或负二项分布，参见 Gelman 和 Hill, 2007）。

检查零膨胀

在（准）泊松模型中，如果观测到的零值数量多于模型预测的零值数量，则表明存在零膨胀现象，即模型对零值的拟合不足。在这种情况下，建议使用负二项分布模型或零膨胀模型。

可以使用 check_zeroinflation() 函数来检查拟合模型中是否存在零膨胀现象。

model <- glm(count ~ spp + mined, family = poisson, data = Salamanders)
check_zeroinflation(model)
#> # 零膨胀检验
#> 
#>    观测零值：387
#>   预测零值：298
#>             比率：0.77

检查奇异模型拟合

“奇异”模型拟合是指方差-协方差矩阵的某些维度被估计为恰好为零。这种情况通常发生在随机效应结构过于复杂的混合效应模型中。

check_singularity() 函数用于检查混合效应模型（类为 lme, merMod, glmmTMB 或 MixMod）是否为奇异，并在模型拟合为奇异时返回 TRUE。

library(lme4)
data(sleepstudy)

# 准备数据
set.seed(123)
sleepstudy$mygrp <- sample(1:5, size = 180, replace = TRUE)
sleepstudy$mysubgrp <- NA
for (i in 1:5) {
  filter_group <- sleepstudy$mygrp == i
  sleepstudy$mysubgrp[filter_group] <-
    sample(1:30, size = sum(filter_group), replace = TRUE)
}

# 拟合一个奇怪的模型
model <- lmer(
  Reaction ~ Days + (1 | mygrp / mysubgrp) + (1 | Subject),
  data = sleepstudy
)

check_singularity(model)
#> [1] TRUE

修复奇异拟合问题的方法可以参考 这里。

检查异方差性

线性模型假设误差方差是恒定的（同方差性）。

check_heteroscedasticity() 函数用于评估这一假设是否被违反：

data(cars)
model <- lm(dist ~ speed, data = cars)

check_heteroscedasticity(model)
#> 警告：检测到异方差性（误差方差非恒定）(p = 0.031)。

模型检验的综合可视化

performance 包提供了许多用于检查模型假设的函数，例如 check_collinearity()、check_normality() 或 check_heteroscedasticity()。要进行全面的模型检验，可以使用 check_model()。

# 定义一个模型
model <- lm(mpg ~ wt + am + gear + vs * cyl, data = mtcars)

# 检查模型假设
check_model(model)

模型性能摘要

model_performance() 函数用于计算回归模型的性能指标。根据模型对象的不同，常见的指标可能包括 R²、AIC、BIC、RMSE、ICC 或 LOOIC。

线性模型

m1 <- lm(mpg ~ wt + cyl, data = mtcars)
model_performance(m1)
#> # 模型性能指标
#> 
#> AIC     |    AICc |     BIC |    R2 | R2 (调整后) |  RMSE | Sigma
#> ---------------------------------------------------------------
#> 156.010 | 157.492 | 161.873 | 0.830 |     0.819 | 2.444 | 2.568

逻辑回归模型

m2 <- glm(vs ~ wt + mpg, data = mtcars, family = "binomial")
model_performance(m2)
#> # 模型性能指标
#> 
#> AIC    |   AICc |    BIC | Tjur's R2 |  RMSE | Sigma | Log_loss | Score_log | Score_spherical |   PCP
#> -----------------------------------------------------------------------------------------------------
#> 31.298 | 32.155 | 35.695 |     0.478 | 0.359 | 1.000 |    0.395 |   -14.903 |           0.095 | 0.743

线性混合效应模型

library(lme4)
m3 <- lmer(Reaction ~ Days + (1 + Days | Subject), data = sleepstudy)
model_performance(m3)
#> # 模型性能指标
#> 
#> AIC      |     AICc |      BIC | R2 (条件) | R2 (边际) |   ICC |   RMSE |  Sigma
#> ----------------------------------------------------------------------------------
#> 1755.628 | 1756.114 | 1774.786 |      0.799 |      0.279 | 0.722 | 23.438 | 25.592

模型比较

compare_performance() 函数可用于比较多个模型（包括不同类型）的性能和质量。

counts <- c(18, 17, 15, 20, 10, 20, 25, 13, 12)
outcome <- gl(3, 1, 9)
treatment <- gl(3, 3)
m4 <- glm(counts ~ outcome + treatment, family = poisson())

compare_performance(m1, m2, m3, m4, verbose = FALSE)
#> # 模型性能指标比较
#> 
#> 名称 |   模型 |  AIC (权重) | AICc (权重) |  BIC (权重) |   RMSE |  Sigma | Score_log
#> -----------------------------------------------------------------------------------------------
#> m1   |      lm |  156.0 (<.001) |  157.5 (<.001) |  161.9 (<.001) |  2.444 |  2.568 |          
#> m2   |     glm |   31.3 (>.999) |   32.2 (>.999) |   35.7 (>.999) |  0.359 |  1.000 |   -14.903
#> m3   | lmerMod | 1764.0 (<.001) | 1764.5 (<.001) | 1783.1 (<.001) | 23.438 | 25.592 |          
#> m4   |     glm |   56.8 (<.001) |   76.8 (<.001) |   57.7 (<.001) |  3.043 |  1.000 |    -2.598
#> 
#> 名称 | Score_spherical |    R2 | R2 (adj.) | Tjur's R2 | Log_loss |   PCP | R2 (cond.) | R2 (marg.)
#> ---------------------------------------------------------------------------------------------------
#> m1   |                 | 0.830 |     0.819 |           |          |       |            |           
#> m2   |           0.095 |       |           |     0.478 |    0.395 | 0.743 |            |           
#> m3   |                 |       |           |           |          |       |      0.799 |      0.279
#> m4   |           0.324 |       |           |           |          |       |            |           
#> 
#> 名称 |   ICC | Nagelkerke's R2
#> ------------------------------
#> m1   |       |                
#> m2   |       |                
#> m3   | 0.722 |                
#> m4   |       |           0.657

模型性能综合指数

还可以轻松计算模型性能的综合指数，并按从好到坏的顺序对模型进行排序。

compare_performance(m1, m2, m3, m4, rank = TRUE, verbose = FALSE)
#> # 模型性能指标比较
#> 
#> 名称 |   模型 |   RMSE |  Sigma | AIC 权重 | AICc 权重 | BIC 权重 | 性能得分
#> -----------------------------------------------------------------------------------------------
#> m2   |     glm |  0.359 |  1.000 |       1.000 |        1.000 |       1.000 |           100.00%
#> m4   |     glm |  3.043 |  1.000 |    2.96e-06 |     2.06e-10 |    1.63e-05 |            37.67%
#> m1   |      lm |  2.444 |  2.568 |    8.30e-28 |     6.07e-28 |    3.99e-28 |            36.92%
#> m3   | lmerMod | 23.438 | 25.592 |    0.00e+00 |     0.00e+00 |    0.00e+00 |             0.00%

模型性能指标的可视化

最后，我们提供了便捷的可视化功能（需安装 see 包）。

plot(compare_performance(m1, m2, m4, rank = TRUE, verbose = FALSE))

模型检验

test_performance()（及其贝叶斯版本 test_bf）会根据输入内容执行最相关且适当的检验（例如，模型是否嵌套等）。

set.seed(123)
data(iris)

lm1 <- lm(Sepal.Length ~ Species, data = iris)
lm2 <- lm(Sepal.Length ~ Species + Petal.Length, data = iris)
lm3 <- lm(Sepal.Length ~ Species * Sepal.Width, data = iris)
lm4 <- lm(Sepal.Length ~ Species * Sepal.Width + Petal.Length + Petal.Width, data = iris)

test_performance(lm1, lm2, lm3, lm4)
#> 名称 | 模型 |     BF | Omega2 | p (Omega2) |    LR | p (LR)
#> ------------------------------------------------------------
#> lm1  |    lm |        |        |            |       |       
#> lm2  |    lm | > 1000 |   0.69 |     < .001 | -6.25 | < .001
#> lm3  |    lm | > 1000 |   0.36 |     < .001 | -3.44 | < .001
#> lm4  |    lm | > 1000 |   0.73 |     < .001 | -7.77 | < .001
#> 每个模型都与 lm1 进行比较。

test_bf(lm1, lm2, lm3, lm4)
#> 模型比较的贝叶斯因子
#> 
#>       模型                                                    BF
#> [lm2] Species + Petal.Length                             3.45e+26
#> [lm3] Species * Sepal.Width                              4.69e+07
#> [lm4] Species * Sepal.Width + Petal.Length + Petal.Width 7.58e+29
#> 
#> * 对照模型：[lm1] Species
#> *   贝叶斯因子类型：基于 BIC 的近似值

绘图函数

绘图函数可通过see 包获得。

行为准则

请注意，performance 项目遵循贡献者行为准则发布。通过参与本项目，即表示您同意遵守其条款。

贡献说明

我们欢迎 bug 报告、建议、问题，以及（最重要的是）用于修复问题和添加功能的贡献。

请遵循此处提及的贡献指南：

https://easystats.github.io/performance/CONTRIBUTING.html

参考文献

performance 快速上手指南

performance 是 R 语言 easystats 生态系统的核心包之一，旨在提供统一、一致的方法来评估统计模型的质量。它支持线性模型、广义线性模型、混合效应模型及贝叶斯模型等多种类型，可计算 R²、ICC、RMSE 等拟合指标，并检测过离散、零膨胀、奇异性等常见问题。

环境准备

• 操作系统：Windows、macOS 或 Linux
• R 版本：建议 R ≥ 4.0.0
• 前置依赖：无特殊系统级依赖，但需确保已安装基础 R 环境。该包依赖多个 R 包（如 lme4, glmmTMB, rstanarm 等），安装时会自动处理。

💡 提示：国内用户若遇到 CRAN 下载缓慢，可配置清华或中科大镜像源：

options(repos = c(CRAN = "https://mirrors.tuna.tsinghua.edu.cn/CRAN"))

安装步骤

方式一：从 CRAN 安装（稳定版）

install.packages("performance")

方式二：从 R-universe 安装（开发最新版）

install.packages("performance", repos = "https://easystats.r-universe.dev")

加载包

推荐加载整个 easystats 生态系统以使用全部功能：

library(easystats)
# 或仅加载 performance
library(performance)

🔄 保持更新：定期运行 easystats::install_latest() 获取最新版本。

基本使用

1. 计算模型拟合指标（R²）

model <- lm(mpg ~ wt + cyl, data = mtcars)
r2(model)
# 输出示例：
# # R2 for Linear Regression
#        R2: 0.830
#   adj. R2: 0.819

2. 检查模型假设（综合诊断）

model <- lm(dist ~ speed, data = cars)
check_model(model)
# 自动生成包括残差正态性、异方差性、共线性等在内的诊断图

3. 获取模型性能摘要

m1 <- lm(mpg ~ wt + cyl, data = mtcars)
model_performance(m1)
# 输出包含 AIC, BIC, R², RMSE 等关键指标的表格

4. 比较多个模型

m2 <- glm(vs ~ wt + mpg, data = mtcars, family = "binomial")
compare_performance(m1, m2)
# 返回各模型在 AIC、BIC、R² 等指标上的对比结果

通过以上几步，即可快速评估你的回归模型是否“表现良好”。更多高级功能（如 ICC 计算、过离散检验、零膨胀检测等）请参考官方文档。