📚 课程目录第3章 PTXQC包安装

第3章 PTXQC包安装：从CRAN到GitHub，我踩过的坑都在这了

说实话，安装一个R包听起来没什么大不了的。一行代码的事情嘛。

但PTXQC这个包，有点特殊。它依赖一堆生物信息学和统计学底层的包，比如Rcpp、data.table、ggplot2这些。如果你直接敲install.packages("PTXQC")，大概率会遇到"编译失败"或者"依赖包版本不对"的问题。

我个人习惯是：先搞清楚环境，再动手安装。省得浪费时间排查。

3.1 准备工作：为什么先装Rtools和依赖包

PTXQC的底层依赖包里有不少需要编译C/C++代码的，比如Rcpp。Windows用户如果没有装Rtools，那编译过程会直接报错。

我曾经在一个Windows服务器上部署PTXQC，结果忘了提前装Rtools，编译到一半卡住了。折腾了半小时才发现问题。

所以，先确认你的系统：

Windows：必须安装Rtools（版本要匹配你的R版本）。建议下载Rtools42或Rtools43。
macOS：确保安装了Xcode Command Line Tools。
Linux：一般自带gcc，但可能需要安装libcurl4-openssl-dev等系统包。

怎么检查Rtools装好了？直接在终端跑：

system('gcc --version')

如果返回了版本信息，那基本上没问题。如果报错，那就乖乖去装吧。

小提示： 我建议你安装最新版的R（4.2+），然后对应的Rtools也选最新版的。老版本R有一些坑，比如矩阵运算包会报错，别问我怎么知道的。

3.2 方法一：通过CRAN安装（稳定版，推荐大多数用户）

这是最简单的途径。CRAN上的PTXQC是经过审核的稳定版，质量有保证。

打开R或RStudio，输入：

install.packages("PTXQC")

如果你在国内网络比较慢，可以换个镜像源。我个人习惯用清华的镜像：

install.packages("PTXQC", repos = "https://mirrors.tuna.tsinghua.edu.cn/CRAN/")

安装过程中，R会自动拉取依赖包。你可能会看到类似这样的日志：

also installing the dependencies ‘Rcpp’, ‘data.table’, ‘ggplot2’, ‘xml2’, ‘yaml’, ‘digest’, ‘gridExtra’, ‘scales’, ‘stringr’, ‘lubridate’, ‘dplyr’, ‘tidyr’, ‘tibble’, ‘purrr’, ‘rlang’, ‘vctrs’, ‘lifecycle’, ‘pillar’, ‘cli’, ‘utf8’, ‘fansi’, ‘magrittr’, ‘glue’, ‘pkgconfig’, ‘R6’, ‘RColorBrewer’, ‘viridisLite’

等待几分钟，如果全部绿色通过，那就装好了。你试试：

library(PTXQC)

如果没有报错，恭喜你。

注意： CRAN版本可能落后于GitHub上的开发版。如果你需要最新的质控算法（比如最新的色谱峰检测算法），建议用GitHub安装。别问我怎么知道的，有一次官方修复了一个严重bug，CRAN版本要两个月后才更新。

3.3 方法二：从GitHub安装（开发版，推荐尝鲜用户）

如果你想用最新的功能，或者CRAN上的版本有某个bug影响你工作了，那就从GitHub装。

首先，确保你装了devtools或remotes包。没有的话先装：

install.packages("devtools")

然后：

library(devtools)
install_github("PeeperLab/PTXQC")

这里有个常见坑——GitHub可能会限制匿名访问。如果你遇到这样的错误：

Error: Failed to install 'PTXQC' from GitHub:
  HTTP error 403. API rate limit exceeded for your IP.

那就用remotes包，并配置GitHub token（不过一般家庭网络不会触发限速，公司内网比较常见）。

另一种方式是直接下载源码压缩包，手动安装：

install.packages("path/to/PTXQC-master.zip", repos = NULL, type = "source")

为什么会有这个需求？说实话，有时候GitHub挂了，或者你内网不能连外网，手动下载然后本地安装是最稳的。我去年有一次在客户现场部署，他们服务器不能联网，我就是用U盘拷过去的。

3.4 依赖包的依赖：Rcpp和data.table的编译问题

这两个包是PTXQC核心计算的基石。Rcpp负责调用C++加速质谱数据处理，data.table负责高效地读写大表格（比如几十万行的肽段数据）。

但它们的编译过程对系统环境有要求。

你可能会遇到类似错误：

* installing *source* package 'Rcpp' ...
** package 'Rcpp' successfully unpacked and MD5 sums checked
** using staged installation
** libs
*** arch i386
c:/Rtools/mingw_32/bin/g++  -std=gnu++11 ... blah blah
fatal error: 'sys/stat.h' file not found

这个错误说明系统缺少C++标准头文件。Linux用户需要装build-essential：

sudo apt-get install build-essential

macOS用户执行：

xcode-select --install

Windows用户检查Rtools是否正确设置了环境变量。怎么检查？在R里跑：

Sys.which("g++")

如果返回空字符串，那就没找到编译器。

我的经验： 如果以上方法搞不定，别硬刚。直接装预编译的二进制包。Windows和macOS上的CRAN通常提供二进制版，一句install.packages("Rcpp", type = "binary")就搞定了。

3.5 安装后的验证：确保一切就绪

装好之后，建议做个快速验证。跑一个最小的工作流——生成一个空的质控报告。

library(PTXQC)

# 创建一个测试报告（不需要真实数据）
result <- createQCRreport(createFakePTXQCdata())
print(result)

如果能正常跑出结果，没报错，那说明环境完美。如果卡住了，十有八九是某个依赖包版本有问题。

怎么排查？我有个土办法：查看sessionInfo()，看看所有依赖包的版本，然后对照PTXQC的DESCRIPTION文件里的依赖范围：

sessionInfo()

对比一下，看看有没有版本号落在外面的。

3.6 知识结构图：安装流程一览

下面这张图总结了我认为最稳妥的安装路径。你跟着走，基本不会踩坑。

3.7 避坑指南：我替你试过的错

最后，列几个我真实踩过的坑。你遇到了直接跳过就好。

问题现象	根本原因	我的解决方法
`Error: package 'Rcpp' was installed before R 4.0`	Rcpp版本太旧，不兼容新R	重装Rcpp：`install.packages("Rcpp")`
`cannot find -lgfortran`	缺少Fortran编译器（少见）	Linux下`sudo apt install gfortran`；Windows下换二进制包
`API rate limit exceeded`	GitHub匿名请求过多	用`remotes::install_github(token = "...")`或者换CRAN装
`creation of QC report failed: object '...' not found`	PTXQC包版本与数据格式不匹配	更新到GitHub最新开发版

重要提醒： 如果你在Windows上遇到Makevars相关错误，别去手动改文件。直接install.packages("PTXQC", type = "binary")强制装二进制版。别问为什么，问就是Windows的C++工具链太折腾。

嗯，到这里安装部分基本结束了。接下来你就可以放心用PTXQC生成漂亮的质控报告了。记住：装包只是第一步，真正的工作是在数据上跑出可解释的结果。