mintyr 速查表

通用约定适用于所有函数

参数	含义
`data`	输入的表或列表，绝不会被原地修改。
`cols`	要处理的列，可用列名或列号（`c("mpg","wt")`, `1:3`）
`by`	分组列，列名或列号均可
`out_type`	`"dt"` 返回 data.table（默认），`"df"` 返回 data.frame
`path`	输出位置；不存在的文件夹会自动创建
`seed`	使折可复现；不影响全局随机数状态

install.packages("mintyr")       # CRAN
pak::pak("tony2015116/mintyr")   # 开发版
library(mintyr)
library(data.table)

不会悄悄丢数据：如果两个输出会落到同一个文件，mintyr 会报错停止，而不是覆盖。

导入多个文件 → 一张表

import_xlsx(file, combine = TRUE, sheet = NULL, skip = 0, header_rows = 1, header_sep = "_", header_fill = "auto", file_col = "excel_name", sheet_col = "sheet_name", path_col = NULL, workers = 1, verbose = FALSE, on_error = "stop", ...)

把所有工作簿的所有工作表读入一个 data.table，并加上来源列 excel_name / sheet_name。

sheet — 工作表序号或名称
skip = 1, header_rows = 2 — 多行表头，用 header_sep 连接；合并单元格由 header_fill 处理（"auto" / "right" / "none"）
combine = FALSE → 返回命名列表 "<文件>_<工作表>"
workers = 4 — 文件大或多时并行读取
on_error = "warn" — 跳过无法读取的文件，只给一条警告
... → readxl::read_excel()（col_types、na）

import_csv(file, combine = TRUE, file_col = "_file", path_col = NULL, full_path = FALSE, keep_ext = FALSE, ...)

用 fread() 读取多个 CSV / TXT 文件；... 传给 fread()（select、na.strings、nThread）。

files <- list.files("raw", "\\.xlsx$",
                    full.names = TRUE,
                    recursive = TRUE)
dt <- import_xlsx(files, skip = 1,
                  header_rows = 2,
                  path_col = "file_path")
# 从 raw/<场>/<年份>/文件.xlsx 提取为列
dt[, farm := get_path_info(file_path, n = -3)]
dt[, year := get_path_info(file_path, n = -2)]

0.2.1 新变化：某列在一个工作表中为空时，沿用它在其他表中的类型；类型确实不一致时合并为文本，并给出一条警告。列类型根据全部行推断。

重塑与嵌套宽表 → 分块

w2l_nest(data, cols = NULL, by = NULL, out_type = "dt")

宽表 → 长表，再按性状（name）和 by 嵌套成 data 列表列。cols = NULL 加 by：只嵌套、不转长。

nested <- w2l_nest(mtcars,
                   cols = c("mpg", "qsec"),
                   by = "am")

w2l_split(data, cols = NULL, by = NULL, out_type = "dt", sep = "_")

同样的重塑，但返回命名列表（"mpg_0"、"mpg_1"…），可直接交给 split_cv() 和 export_list()。

c2p_nest(data, cols, by = NULL, pairs_n = 2, sep = "-", out_type = "dt")

变量两两组合（三三组合用 pairs_n = 3），统一改名为 value1、value2…，一个函数就能处理所有组合。

pairs <- c2p_nest(mtcars,
                  cols = c("mpg", "hp", "wt"),
                  by = "am")
pairs[, r := sapply(data, function(d)
  cor(d$value1, d$value2))]

r2p_nest(data, names_from, cols, out_type = "dt", id = NULL)

同一性状在 names_from 各水平下并排成列，按 id 对齐（如 G×E 相关）。id + names_from 不唯一时报错。

r2p_nest(growth, names_from = "farm",
         cols = c("adg", "bf"), id = "animal")

交叉验证每个分组内做 k 折

nest_cv(data, v = 10, repeats = 1, strata = NULL, breaks = 4, pool = 0.1, seed = NULL, materialize = TRUE, out_type = "dt")

用于嵌套表（如 w2l_nest() 的结果）：每个分组 × 折一行。

split_cv(data, v = 10, repeats = 1, strata = NULL, breaks = 4, pool = 0.1, seed = NULL, materialize = TRUE, out_type = "dt")

用于表的列表（如 w2l_split() 的结果）；单张表请用 list() 包起来。

参数	作用
`v`, `repeats`	折数、重复次数；重复时增加 `id2` 列
`strata`	分层列，各折比例均衡；数值列按 `breaks` 个分位数分箱；占比低于 `pool` 的层会合并
`materialize = FALSE`	只保留行号，大幅节省内存
`out_type = "df"`	子集为 data.frame（适合 ASReml-R）

返回列：id（Fold1… 或 Repeat1…）、id2、train_idx、validate_idx，以及 train / validate 子集。

cv <- nest_cv(nested, v = 4, seed = 2026)
cv[, r := mapply(function(tr, va) {
  fit <- lm(value ~ wt + hp, data = tr)
  cor(predict(fit, va), va$value)
}, train, validate)]
cv[, .(mean_r = mean(r)), by = .(name, am)]

描述统计可直接用于报告

desc_stats(data, cols = NULL, by = NULL, type = "common", stats = NULL, total = FALSE, total_label = "Total", min_n = 1, probs = c(0, .25, .5, .75, 1), conf_level = 0.95, na_rm = TRUE, digits = NULL, fmt = NULL, labels = NULL, shape = "long", sep = "_", out_type = "dt")

按分组 × 变量计算统计量，百万行数据也很快。

`type`	统计量
`"common"`	n min max median iqr mean sd se ci
`"full"`	+ q1 q3 mad cv skew kurt
`"mean_sd"` / `"mean_se"` / `"mean_ci"`	n、mean，以及 sd / se / ci_low、ci_high
`"median_iqr"` / `"median_mad"`	n、median，以及 iqr / mad
`"robust"` / `"five_number"`	n median iqr / n min q1 median q3 max
`"quantile"`	n 和 `probs` 指定的分位数 → `q5`, `q2.5`, …

stats = c("n", "mean", "cv") — 任选并按顺序输出（还可选 n_miss、ci_low…）
total = TRUE — 增加合计行，由全部记录计算；计数可相加
min_n = 3 — 样本不足的组保留 n，其他统计量为 NA
digits = c(2, adg = 0) — 按变量分别设置小数位
labels = c(adg = "ADG (g)") · shape = "wide" 输出报告用宽表

fmt 模板：{mean}、{sd:1}（1 位小数）、{cv:1%}（百分比）、{q2.5}（百分位数）。

desc_stats(mtcars, cols = c("mpg", "wt"),
           by = "cyl", fmt = "{mean} ± {sd}",
           total = TRUE, shape = "wide")
# 计数表，带行合计和列合计
desc_stats(iris, by = "Species", stats = "n",
           total = TRUE, shape = "wide")

top_perc(data, perc, cols, by = NULL, keep_data = FALSE, stats = c("n", "min", "max", "mean", "median", "sd", "se", "cv"))

每个变量和分组中前（perc = 0.1）或后（-0.1）X% 记录的统计量，可同时给多个 perc。keep_data = TRUE 时同时返回这些记录（$stat、$data）。

top_perc(iris, perc = c(0.1, -0.1),
         cols = "Petal.Width", by = "Species")

format_digits(data, cols = NULL, digits = 2, percentage = FALSE, nan_as_na = FALSE)

把数值列格式化为固定小数位的文本，用于制表；percentage = TRUE 得到 "12.50%"。

导出分块 → 文件

export_xlsx(data, path, file_col = "excel_name", sheet_col = "sheet_name", sheet_name = "Sheet1", drop_cols = TRUE, overwrite = TRUE, verbose = FALSE)

带 excel_name / sheet_name 的表 → 写回原来的文件和工作表（与 import_xlsx() 无损往返）
列表 + path = "out.xlsx" → 一个工作簿，元素名作工作表名
列表 + path = "dir" → 每个元素一个工作簿
overwrite = FALSE 在写入之前检查所有目标文件

dt <- import_xlsx(files)
dt <- dt[!is.na(weight)]
# 文件名、工作表名与原来相同
export_xlsx(dt, path = "cleaned")

export_nest(data, by = NULL, cols = NULL, path = tempdir(), file_type = "txt", na = "NA", quote = FALSE, ...)

每个嵌套表写到 path/<by1>/<by2>/<列名>.txt；模型对象列会跳过。by 不唯一时报错。

export_list(data, path = tempdir(), file_type = "txt", na = "NA", quote = FALSE, ...)

列表的每个元素写成一个文件；名称中的 / 会变成子文件夹。

# HIBLUP：保留表头，缺失值为 NA
export_nest(nested, path = "hiblup_runs")
# DMU：数值型缺失码，不要表头
export_nest(nested, path = "dmu_runs",
            na = "-9999",
            col.names = FALSE)  # 传给 fwrite()

三个函数都会（不可见地）返回写出的文件路径。

工具函数路径与示例文件

get_path_info(path, n = NULL, rm_extension = TRUE, rm_path = TRUE)

调用	结果
`p <- "D:/data/farmA/2025/pigs.xlsx"`
`get_path_info(p)`	`"pigs"`
`get_path_info(p, rm_extension = FALSE)`	`"pigs.xlsx"`
`get_path_info(p, n = 1)`	`"data"` （盘符不算一段）
`get_path_info(p, n = -3)`	`"farmA"`
`get_path_info(p, n = c(-3, -2))`	`"farmA/2025"`

/ 和 \ 混用也可以；超出路径层数时返回 NA。

mintyr_examples(pattern = NULL) · mintyr_example(path = NULL)

列出 / 定位包自带的示例文件。

mintyr_examples("xlsx")
import_xlsx(mintyr_example("xlsx_test1.xlsx"))

从 0.1.x 升级旧参数名已移除

函数	旧	新
交叉验证、导出	`nest_dt`, `split_dt`	`data`
`w2l_*()`	`cols2l`	`cols`
`c2p_nest()`	`cols2bind`	`cols`
`r2p_nest()`	`rows2bind`, `by`	`names_from`, `cols`
`export_nest()`	`nest_cols`, `group_cols`	`cols`, `by`
`*_cv()`	`splits`（rsample）	`train_idx` / `validate_idx`
`top_perc()`	Mean、SD…	`mean`、`sd`…（小写）

使用旧参数名会报 unused argument 错误。完整列表见 NEWS。

通用约定 适用于所有函数

导入 多个文件 → 一张表

重塑与嵌套 宽表 → 分块

交叉验证 每个分组内做 k 折

描述统计 可直接用于报告

导出 分块 → 文件

工具函数 路径与示例文件

从 0.1.x 升级 旧参数名已移除