collapse <img src='https://yellow-cdn.veclightyear.com/0a4dffa0/5518cedf-e705-4739-a264-de2035a97778.png' width="150px" align="right" />

collapse 是一个基于C/C++的R语言数据转换和统计计算包。其目标是：

在R中简化复杂的数据转换、探索和计算任务。
帮助使R代码快速、灵活、简洁和对程序员友好。

它还实现了一种类无关的R编程方法，支持base R、tibble、grouped_df（tidyverse）、data.table、sf、units、pseries、pdata.frame（plm）和xts/zoo。

主要特性：

高级统计编程：一套完整的快速统计函数，支持对向量、矩阵和数据框进行分组和加权计算。快速且可编程的分组、排序、匹配、唯一值/行、因子生成和交互。
快速数据操作：用于数据操作、数据对象转换和内存高效R编程的快速灵活函数。
高级聚合：快速简便的多数据类型、多函数、加权和并行化数据聚合。
高级转换：快速行/列运算，（分组）替换和统计清除（按引用），（分组、加权）缩放/标准化，（高维）between（平均）和（准）within（去均值）转换。
高级时间计算：快速灵活的索引时间序列和面板数据类，（序列）滞后/超前，以及（滞后/超前、迭代、准、对数）差分和（复合）增长率计算，适用于（不规则）时间序列和面板。面板数据的多变量自相关、偏相关和交叉相关函数。面板数据到（ts-）数组的转换。
列表处理：递归列表搜索、拆分、提取/子集、应用，以及广义行绑定/解列到数据框。
高级数据探索：快速（分组、加权、面板分解）汇总统计和描述工具。

collapse 用C和C++编写，仅依赖于Rcpp。其算法比base R快数倍，可扩展至10亿级观测，对复杂任务（如分位数、加权统计、模式/计数/去重、连接）非常高效。优化的R代码确保最小开销和快速语法评估。

安装

# 在CRAN上安装当前版本
install.packages("collapse")

从R-universe安装稳定的开发版本（Windows/Mac二进制文件）

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

从GitHub安装稳定的开发版本（需要编译）

remotes::install_github("SebKrantz/collapse")

从CRAN存档安装以前的版本（需要编译）

install.packages("https://cran.r-project.org/src/contrib/Archive/collapse/collapse_1.9.6.tar.gz", repos = NULL, type = "source")

较早的稳定版本：1.8.9, 1.7.6, 1.6.5, 1.5.3, 1.4.2, 1.3.2, 1.2.1


## 文档

*collapse*安装时附带内置的结构化[文档](https://sebkrantz.github.io/collapse/reference/collapse-documentation.html)，通过一组独立的帮助页面实现。调用`help('collapse-documentation')`会显示顶级文档页面，提供整个包的概览和所有其他文档页面的链接。

此外还有几个[小品文](https://sebkrantz.github.io/collapse/articles/index.html)，其中包括一篇关于[文档和资源](https://sebkrantz.github.io/collapse/articles/collapse_documentation.html)的小品文。

### 速查表

<a href="https://raw.githubusercontent.com/SebKrantz/collapse/master/misc/collapse%20cheat%20sheet/collapse_cheat_sheet.pdf"><img src="https://yellow-cdn.veclightyear.com/0a4dffa0/6feae601-f36e-4de5-876e-04b2ed3ad15d.png" width="330"/></a>
<a href="https://raw.githubusercontent.com/SebKrantz/collapse/master/misc/collapse%20cheat%20sheet/collapse_cheat_sheet.pdf"><img src="https://yellow-cdn.veclightyear.com/0a4dffa0/eac6883d-a0be-45d3-a481-ff97dd440283.png" width="330"/></a>

### arXiv上的文章

2024年3月，关于*collapse*的一篇[**文章**](https://arxiv.org/abs/2403.05038)已提交给[统计软件杂志](https://www.jstatsoft.org/)。

### 在[useR 2022](https://user2022.r-project.org)上的演讲

[**视频录像**](https://www.youtube.com/watch?v=OwWT1-dSEts) | 
[**幻灯片**](https://raw.githubusercontent.com/SebKrantz/collapse/master/misc/useR2022%20presentation/collapse_useR2022_final.pdf)

## 使用示例
这里提供了一组简单的示例，介绍了*collapse*的一些重要特性。对于熟悉R的读者来说应该很容易理解。
<details>
  <summary><b><a style="cursor: pointer;">点击此处展开 </a></b> </summary>
  
``` r
library(collapse)
data("iris")            # R基础包中的iris数据集
v <- iris$Sepal.Length  # 向量
d <- num_vars(iris)     # 保存数值变量（也可以是矩阵，统计函数是S3泛型）
g <- iris$Species       # 分组变量（也可以是变量列表）

## 高级统计编程 -----------------------------------------------------------------------------

# 简单的（按列）统计...
fmedian(v)                       # 向量
fsd(qM(d))                       # 矩阵（qM是一个更快的as.matrix）
fmode(d)                         # 数据框
fmean(qM(d), drop = FALSE)       # 仍然是矩阵
fmax(d, drop = FALSE)            # 仍然是数据框

# 快速分组和/或加权统计
w <- abs(rnorm(fnrow(iris)))
fmedian(d, w = w)                 # 简单加权统计
fnth(d, 0.75, g)                  # 分组统计（分组第三四分位数）
fmedian(d, g, w)                  # 分组加权统计
fsd(v, g, w)                      # 对向量同理
fmode(qM(d), g, w, ties = "max")  # 或矩阵（分组加权最大众数）...

# 一组快速的数据操作函数允许以高速进行复杂的管道编程
library(magrittr)                            # 管道操作符
iris %>% fgroup_by(Species) %>% fndistinct   # 分组不同值计数
iris %>% fgroup_by(Species) %>% fmedian(w)   # 加权分组中位数 
iris %>% add_vars(w) %>%                     # 将权重向量添加到数据集
  fsubset(Sepal.Length < fmean(Sepal.Length), Species, Sepal.Width:w) %>% # 快速选择和子集
  fgroup_by(Species) %>%                     # 分组（高效创建分组tibble）
  fvar(w) %>%                                # 频率加权分组方差，默认（keep.w = TRUE）  
  roworder(sum.w)                            # 也在名为'sum.w'的列中保存组权重

# 也可以使用dplyr（但dplyr操作动词要慢得多）
library(dplyr)
iris %>% add_vars(w) %>% 
  filter(Sepal.Length < fmean(Sepal.Length)) %>% 
  select(Species, Sepal.Width:w) %>% 
  group_by(Species) %>% 
  fvar(w) %>% arrange(sum.w)
  
## 快速数据操作 ---------------------------------------------------------------------------------------

head(GGDC10S)
# 更广的透视：仅SUM（总计）
SUM <- GGDC10S |> pivot(c("Country", "Year"), "SUM", "Variable", how = "wider")
head(SUM)

# 与wlddev数据连接
wlddev |>
    join(SUM, on = c("iso3c" = "Country", "year" = "Year"), how = "inner")

# 重塑透视并为生成的列提供新标签
pivot(GGDC10S, values = 6:16, names = list("Variable", "Sectorcode"),
      labels = list(to = "Sector",
                    new = c(Sectorcode = "GGDC10S部门代码",
                            Sector = "详细部门描述",
                            VA = "增加值",
                            EMP = "就业")), 
      how = "recast", na.rm = TRUE)

## 高级聚合 -----------------------------------------------------------------------------------------

collap(iris, Sepal.Length + Sepal.Width ~ Species, fmean)  # 使用平均值进行简单聚合..
collap(iris, ~ Species, list(fmean, fmedian, fmode))       # 对每列应用多个函数
add_vars(iris) <- w                                        # 添加权重，以长格式返回..
collap(iris, ~ Species, list(fmean, fmedian, fmode), w = ~ w, return = "long")

# 生成一些额外的逻辑数据
settransform(iris, AWMSL = Sepal.Length > fmedian(Sepal.Length, w = w), 
                   AWMSW = Sepal.Width > fmedian(Sepal.Width, w = w))

# 多类型数据聚合：catFUN应用于所有分类列（这里是AMWSW）
collap(iris, ~ Species + AWMSL, list(fmean, fmedian, fmode), 
       catFUN = fmode, w = ~ w, return = "long")

# 自定义聚合提供最大的灵活性：直接将函数映射到列
collap(iris, ~ Species + AWMSL, 
       custom = list(fmean = 2:3, fsd = 3:4, fmode = "AWMSL"), w = ~ w, 
       wFUN = list(fsum, fmin, fmax), # 这里还使用3个不同的函数聚合权重向量
       keep.col.order = FALSE)        # 不保持列顺序 -> 分组和权重变量优先

# 也可以使用分组tibble：对数值列用加权中位数，对分类列用加权众数
iris %>% fgroup_by(Species, AWMSL) %>% collapg(fmedian, fmode, w = w)

## 高级转换 -------------------------------------------------------------------------------------

# 所有快速统计函数都有TRA参数，支持10种不同的替换和扫描操作
fmode(d, TRA = "replace")     # 用众数替换值
fsd(v, TRA = "/")             # 除以总体标准差（缩放）
fsum(d, TRA = "%")            # 计算百分比
fsd(d, g, TRA = "/")          # 分组缩放
fmin(d, g, TRA = "-")         # 将每个种类中的最小值设为0
ffirst(d, g, TRA = "%%")      # 取每个种类第一个值的模
fmedian(d, g, w, "-")         # 按加权中位数进行分组居中
fnth(d, 0.95, g, w, "%")      # 将数据表示为加权种类95百分位数的百分比
fmode(d, g, w, "replace",     # 用种类加权最小众数替换数据
      ties = "min")

# 也可以直接调用TRA()来替换或扫描匹配的计算统计
TRA(v, sd(v), "/")                       # 等同于fsd(v, TRA = "/")
TRA(d, fmedian(d, g, w), "-", g)         # 等同于fmedian(d, g, w, "-")
TRA(d, BY(d, g, quantile, 0.95), "%", g) # 等同于fnth(d, 0.95, g, TRA = "%")（除了分位数算法）

# 对于常见用途，有一些更快速和更高级的函数
fbetween(d, g)                           # 分组平均 [与fmean(d, g, TRA = "replace")相同但更快]
fwithin(d, g)                            # 分组居中 [与fmean(d, g, TRA = "-")相同但更快]
fwithin(d, g, w)                         # 分组加权居中 [与fmean(d, g, w, "-")相同]
fwithin(d, g, w, theta = 0.76)           # 准居中，即d - theta*fbetween(d, g, w)
fwithin(d, g, w, mean = "overall.mean")  # 保留数据的整体加权平均值

fscale(d)                                # 缩放和居中（默认均值 = 0，标准差 = 1）
fscale(d, mean = 5, sd = 3)              # 自定义缩放和居中
fscale(d, mean = FALSE, sd = 3)          # 保留均值的缩放
fscale(d, g, w)                          # 分组加权缩放和居中
fscale(d, g, w, mean = "overall.mean",   # 将组均值设为整体加权均值，
       sd = "within.sd")                 # 将组标准差设为fsd(fwithin(d, g, w), w = w)

get_vars(iris, 1:2)                      # 使用get_vars快速选择数据框列，gv是简写
fhdbetween(gv(iris, 1:2), gv(iris, 3:5)) # 使用因子和连续协变量的线性预测
fhdwithin(gv(iris, 1:2), gv(iris, 3:5))  # 剔除因子和连续协变量的线性影响
# 这再次为数据操作开辟了新的可能性...

iris %>%  
  ftransform(ASWMSL = Sepal.Length > fmedian(Sepal.Length, Species, w, "replace")) %>%
  fgroup_by(ASWMSL) %>% collapg(w = w, keep.col.order = FALSE)

iris %>% fgroup_by(Species) %>% num_vars %>% fwithin(w)  # 加权去均值化


## 时间序列和面板序列 ---------------------------------------------------------------------------------

flag(AirPassengers, -1:3)                      # 一系列的滞后和前置
EuStockMarkets %>%                             # 一系列的一阶和二阶季节性差分
  fdiff(0:1 * frequency(.), 1:2)  
fdiff(EuStockMarkets, rho = 0.95)              # 准差分 [x - rho*flag(x)]
fdiff(EuStockMarkets, log = TRUE)              # 对数差分 [log(x/flag(x))]
EuStockMarkets %>% fgrowth(c(1, frequency(.))) # 普通和季节性增长率
EuStockMarkets %>% fgrowth(logdiff = TRUE)     # 对数差分增长率 [log(x/flag(x))*100]

# 创建面板数据
pdata <- EuStockMarkets %>% list(`A` = ., `B` = .) %>% 
         unlist2d(idcols = "Id", row.names = "Time")  

L(pdata, -1:3, ~Id, ~Time)                   # 完全识别的面板滞后序列(L是flag的操作符) 
pdata %>% fgroup_by(Id) %>% flag(-1:3, Time) # 同样的效果..

# collapse也支持索引化的序列和数据框(以及plm面板数据类)
pdata <- findex_by(pdata, Id, Time)         
L(pdata, -1:3)          # 与上面相同, ...
psacf(pdata)            # 多变量面板自相关函数
psmat(pdata) %>% plot   # 从面板数据生成3D时间序列数组并绘图

HDW(pdata)              # 这会去除个体和时间固定效应.. (HDW是fhdwithin的操作符)
W(pdata, effect = "Id") # 只去除个体效应.. (W是fwithin的操作符)

## 列表处理 ----------------------------------------------------------------------------------------------

# 一些嵌套的异质数据对象列表..
l <- list(a = qM(mtcars[1:8]),                                   # 矩阵
          b = list(c = mtcars[4:11],                             # 数据框
                   d = list(e = mtcars[2:10], 
                            f = fsd(mtcars))))                   # 向量

ldepth(l)                       # 列表有4层嵌套(考虑到mtcars是一个数据框)
is_unlistable(l)                # 可以被展开
has_elem(l, "f")                # 包含一个名为"f"的元素
has_elem(l, is.matrix)          # 包含一个矩阵

get_elem(l, "f")                # 递归提取元素..
get_elem(l, c("c","f"))         
get_elem(l, c("c","f"), keep.tree = TRUE)
unlist2d(l, row.names = TRUE)   # 智能递归行绑定到数据框   
rapply2d(l, fmean) %>% unlist2d # 对所有元素取平均值并重复

# 应用：从(可能嵌套的)模型对象列表中提取和整理结果
list(mod1 = lm(mpg ~ carb, mtcars), 
     mod2 = lm(mpg ~ carb + hp, mtcars)) %>%
  lapply(summary) %>% 
  get_elem("coef", regex = TRUE) %>%   # 正则表达式搜索和提取
  unlist2d(idcols = "Model", row.names = "Predictor")

## 汇总统计 -------------------------------------------------------------------------------------------

irisNA <- na_insert(iris, prop = 0.15)  # 随机设置15%缺失
fnobs(irisNA)                           # 观测计数
pwnobs(irisNA)                          # 成对观测计数
fnobs(irisNA, g)                        # 分组观测计数
fndistinct(irisNA)                      # 同样适用于唯一值... (默认na.rm = TRUE跳过NA)
fndistinct(irisNA, g)  

descr(iris)                                   # 数据的详细统计描述

varying(iris, ~ Species)                      # 显示哪些变量在Species内部变化
varying(pdata)                                # 哪些是随时间变化的？ 
qsu(iris, w = ~ w)                            # 快速(单遍)汇总(带权重)
qsu(iris, ~ Species, w = ~ w, higher = TRUE)  # 分组汇总 + 高阶矩
qsu(pdata, higher = TRUE)                     # 面板数据汇总(个体间和个体内)
pwcor(num_vars(irisNA), N = TRUE, P = TRUE)   # 成对相关系数及p值和观测数
pwcor(W(pdata, keep.ids = FALSE), P = TRUE)   # 组内相关系数

</details> <p> </p>

经过评估和更广泛的示例集可在[包页面](https://github.com/SebKrantz/collapse/blob/master/https://sebkrantz.github.io/collapse/reference/collapse-package.html上找到(也可以在R中通过调用example('collapse-package')访问),以及在[小品文](https://github.com/SebKrantz/collapse/blob/master/https://sebkrantz.github.io/collapse/articles/index.html和[文档](https://github.com/SebKrantz/collapse/blob/master/https://sebkrantz.github.io/collapse/reference/index.html中进一步说明。