拓冰网站定制 
TCGA 数据下载是个老生常谈的话题但每次组里来新人我还是要让他们把 GDC-client 的文档从头到尾读一遍。原因很简单网页端下载器看着方便一旦涉及成百上千个文件或者需要断点续传、校验完整性网页那个“下载篮”方案基本就是给自己找麻烦。GDC-client 是 NCI 官方针对 TCGAThe Cancer Genome Atlas数据分发系统 GDCGenomic Data Commons推出的命令行下载工具本质上是把 HTTP 协议封装成了更可控的多线程任务流专门解决大文件批量下载、中断后续传、以及文件完整性校验这些问题。适合谁用凡是需要下载 RNA-seq 表达矩阵、甲基化芯片原始数据、拷贝数变异 segment 文件或者 WES/WGS 的 BAM 文件的人都应该把 GDC-client 纳入标准工作流。本文会从工具原理、环境配置、配置文件解析、命令使用到实战案例把整个流程完整走一遍。1. 内容整体设计与思路拆解1.1 为什么批量下载必须放弃网页端很多人第一次下 TCGA 数据第一反应是打开 GDC Portal 网页把感兴趣的病例加入购物车然后点 Download。这个流程对下载几个文件来说完全没问题但放到科研场景里根本不现实。举个例子你想下载某个癌种全部样本的 RNA-seq 基因表达 STAR-Counts 结果样本量动辄几百甚至上千每个样本对应一个表达文件。通过网页下载你得到的是一个一个手工保存的文件名字还是乱七八糟的 UUID整理起来累死人。更关键的是网页下载没有断点续传机制。网络稍微波动一下下载到一半的文件直接作废又得重头再来。我见过一个师弟下几百个文件因为宿舍网络不稳定点了整整一下午最后成功落地的不足六成剩下全是损坏的压缩包。这种体验相信不少人都经历过。GDC-client 解决的就是这三个问题批量调度、断点续传、数据校验。它通过读取一个 manifest 文件来获取需要下载的文件 ID、文件名和校验信息然后多线程并发下载。整个下载过程每一个文件都落盘到以文件 UUID 命名的子目录里最后生成对应的.json元数据文件方便后续追溯和管理。也就是说只要配置得当几百个文件可以无人值守地批量拉取中间的失败会自动重试实在不行还能手动补跑。1.2 GDC-client 的工作流程和核心文件GDC-client 的工作流程可以概括为三步获取 manifest、配置下载参数、执行下载任务。manifest 文件是 GDC Portal 中根据你的筛选条件自动生成的清单本质上是一个 TSVTab 分隔文件包含四列id文件的 UUID全局唯一标识符filename原始文件名md5该文件的 MD5 校验值size文件大小单位是字节为什么要有这个清单因为 GDC 服务器上所有文件的访问路径都是基于 UUID 生成的文件名只是给人看的元数据。你单独知道文件名是没法直接定位到文件的必须通过 manifest 里的 UUID 去请求 API。GDC-client 做的事就是逐行解析这个文件然后向 GDC API 发起请求并下载文件本体。下载完成后每个文件目录下除了数据文件本身还会有一个.json格式的元数据文件记录文件的 MD5、大小、下载时间等信息。这个设计很贴心你在后续整理数据时不用重新回 GDC Portal 查这些信息直接读本地 JSON 就行。另外要理解一个关键概念GDC 的下载接口分两种一种是普通文件下载一种是受控数据下载。普通数据如 HTSeq-Counts 表达矩阵、masked 的甲基化信号不需要认证直接下载受控数据如部分 WES 的 BAM 文件、未 mask 的 VCF 文件需要 GDC 账号申请 dbGaP 权限并且在下载时携带 token 文件。GDC-client 的-t参数就是干这个用的。1.3 工具选型对比为什么是 GDC-client 而不是 gdc_get 或 API 脚本为什么不用 Python 的 requests 库直接调 GDC API毕竟 API 文档也是公开的自己写脚本看起来更“灵活”。我来说说自己的体会。API 方案需要你自己处理重试机制、线程池、断点续传和校验逻辑这些功能看起来不难但真正做起来很容易出 bug。GDC-client 已经把这些基础能力固化进 C 实现里而且是官方团队长期维护的稳定性有保障。至于另一个常用方案gdc_get那是社区第三方开发的下载工具虽然在某些场景下速度表现不错但涉及 token 鉴权和断点续传时偶尔会出现兼容性问题。官方 GDC-client 在这些细节上做得更稳妥尤其是处理受控数据时token 的认证流程是官方验证过的不容易遇到“明明有权限但下载 403”这种尴尬。我个人的建议是如果你只是偶尔下载十几个文件网页端或者轻量脚本都行但凡是下载量超过 50 个文件、或者文件本身是大体积的 BAM/FASTQ直接上 GDC-client 不带犹豫的。2. GDC-client 下载安装与环境配置详解2.1 各平台下载方式与版本选择GDC-client 官方发布的安装包支持 Windows、macOS 和 Linux 三大平台。建议直接到 GDC 官网的 Software 页面下载最新版本。截止我写这篇文章时官方最新稳定版本为 v3.0 系列但版本更新迭代较快大家以官网为准。有几个选版本时的注意事项如果你用的是 CentOS 7 这类比较老的 Linux 发行版注意 glibc 版本兼容问题。新版本 GDC-client 可能在旧 glibc 环境下报错这时候可以选择历史版本或者升级系统库。macOS 用户注意区分 Apple SiliconM1/M2/M3和 Intel 芯片官方提供的是通用版但如果你的机器比较老可能会出现权限问题。Windows 用户下载的压缩包里是.exe可执行文件不需要安装解压即用。这里放一个各平台下载和安装的最小操作说明Linux# 下载 tarball 包以官方最新版本链接为准 wget https://gdc.cancer.gov/files/public/file/gdc-client_v3.0.1_Ubuntu_x64.zip # 解压 unzip gdc-client_v3.0.1_Ubuntu_x64.zip # 把二进制文件移动到 PATH 环境变量包含的目录 mv gdc-client /usr/local/bin/ gdc-client --versionmacOS# 下载对应版本的 dmg 或 zip 包 # 如果下载后提示无法打开需要去 系统设置 - 隐私与安全性 中允许该应用运行Windows解压 zip 包后得到gdc-client.exe建议把整个文件夹加入系统 PATH 环境变量。具体操作是右键“此电脑” - 属性 - 高级系统设置 - 环境变量 - 在 Path 中新增解压目录路径。不加入 PATH 也可以只是每次调用都需要带上完整路径比较麻烦。安装后第一件事就是验证版本确认二进制文件能正常运行gdc-client --version正常输出类似gdc-client v3.0.1这样的信息就说明安装成功了。2.2 路径规划与目录结构设计GDC-client 下载文件默认以文件 UUID 作为一级目录名文件原始名作为二级文件名。在开始下载之前我强烈建议你先规划好目录结构这是很多人忽略但实际非常重要的环节。举个反面例子。我见过有人直接在~/Downloads下面跑 GDC-client结果整个目录全是 UUID 文件夹后续样本整理和分析时根本对不上哪个文件属于哪个样本。正确做法是为每一个下载任务单独建立一个项目目录目录名最好包含数据集信息和版本号比如data/ └── TCGA-LUAD/ ├── manifest_20240101.txt └── gdc_download/ ├── 00022d47-1a3d-4b11-8a52-9fbf7f1c0f1b/ │ ├── 1a9c9e0d-8b0f-4db5-a75f-... .txt │ └── 00022d47-... .json └── 00a6e71d-0ae9-4f5e-9a3f-... / ├── 3c1a2e3b-... .txt └── 00a6e71d-... .json这样设计的好处是后续不管你用 R 还是 Python 处理数据都能根据父目录名快速定位到样本对应的文件。此外建议在下载完成后保留 manifest 文件副本作为这次数据批次的身份标识。GDC 数据库版本升级后同样的筛选条件重新生成的 manifest 可能略有差异保留旧版 manifest 可以方便审计和复现。2.3 网络环境要求与断点续传的理解GDC 的下载服务器部署在 AWS 上域名为api.gdc.cancer.gov和gdc-api.nci.nih.gov。国内用户下载时经常遇到速度慢或者连接中断的问题这个不是 GDC 服务器的问题而是跨境网络链路质量不稳定导致的。如果你也是这种情况可以尝试两个办法使用代理。在 GDC-client 命令中通过环境变量HTTPS_PROXY指定代理地址适合有实验室代理或者云服务器代理的情况。错峰下载。美东时间白天对应北京时间凌晨这个时段跨境链路相对空一些下载速度通常会有明显改善。但不管网络多差GDC-client 的断点续传机制都能让你省心不少。它的实现原理是下载每个文件时先创建一个对应的临时文件后缀为.part下载过程中持续写入同时记录当前已下载的字节数。如果下载中断下次运行相同命令时工具会检测到.part文件的存在并从断点继续下载。完整下载完成后.part文件会被重命名为目标文件。所以中间网络断了或者命令被 CtrlC 中断都不需要惊慌重新跑一次命令即可续传。这里有一个经验之谈某些文件在下载过程中如果长时间没有新的数据写入可能会被服务器判定为超时而断开连接GDC-client 默认会在一定时间后自动重试。你可以通过调整下载参数来优化重试行为这个我在后面结合具体命令讲。3. GDC 数据检索与 manifest 文件生成3.1 在 GDC Portal 上筛选数据并生成清单manifest 文件的生成是使用 GDC-client 之前最重要的一步也是最容易出错的一步。因为你选的数据范围直接决定了下载内容的对与错。访问 GDC Portalportal.gdc.cancer.gov点击页面顶部“Repository”进入数据仓库页面。在这里你可以通过左侧的筛选器来限定数据范围包括Primary Site原发部位如 Lung、Breast、ColorectalProject具体项目编号如 TCGA-LUAD、TCGA-BRCAData Category数据类别如 Transcriptome Profiling、Copy Number VariationData Type数据类型如 Gene Expression Quantification、Masked Copy Number SegmentExperimental Strategy实验策略如 RNA-Seq、WXS、WGSWorkflow Type分析流程如 STAR-Counts、STAR - Gene Quantification这个选项在转录组数据中很常用把筛选条件设置好之后页面会列出符合条件的文件清单同时显示总数和总体积。在这一步我强烈建议你先看一眼“总体积”因为它直接决定了你的下载时间。比如筛选出两三百个 BAM 文件体量很可能达到数百 GB你得确认自己的磁盘空间是否足够。确认文件清单没问题后点击“Manifest”按钮浏览器会自动下载一个.txt文件。这个文件就是 GDC-client 下载时需要读取的清单文件。默认文件名通常是gdc_manifest_日期.txt格式如下id filename md5 size 00022d47-1a3d-4b11-8a52-9fbf7f1c0f1b 01a2d3e4-..._counts.txt abcdef1234567890abcdef1234567890 1234563.2 理解 manifest 的关键字段manifest 文件看似简单但四个字段都很有讲究id是文件 UUID这是 GDC 内部文件的主键也是 GDC-client 访问服务器的钥匙。filename只是给你看的样本文件名它往往是UUID_基因注释来源的形式。这里有个小注意点GDC 不同时间段处理的样本文件名后缀格式可能不太一样。比如有些是.htseq.counts.gz有些是.tsv.gz这跟 GDC 的处理流程版本有关不影响你下载但后续读入数据时要注意匹配。md5是文件内容的 MD5 哈希值用于校验下载文件的完整性。GDC-client 在下载完成后会自动计算本地文件的 MD5 并与 manifest 中的值比较不一致的话会判定下载失败并重新下载。size是字节大小。有时候筛选条件相同、时间点不同的两次下载size 值也会有细微差异这与 GDC 数据的版本更新有关。所以在博文、论文中分析 TCGA 数据时最好明确记录数据下载日期和 GDC 数据版本否则后续别人复现你的分析时可能对不上结果。3.3 使用 API 自动生成 manifest进阶用法除了在网页端手工生成 manifestGDC 还提供了一套 REST API让你可以用脚本方式自动化获取清单。这对于需要同时处理多个癌种或者多组数据的用户特别有用。比如你想查询 TCGA-LUAD 项目中所有 RNA-Seq 的 STAR-Counts 基因表达文件可以用如下 API 查询curl -X POST https://api.gdc.cancer.gov/files \ -H Content-Type: application/json \ -d { filters: { op: and, content: [ { op: in, content: { field: cases.project.project_id, value: [TCGA-LUAD] } }, { op: in, content: { field: files.experimental_strategy, value: [RNA-Seq] } }, { op: in, content: { field: files.analysis.workflow_type, value: [STAR - Counts] } } ] }, fields: file_id,file_name,md5sum,file_size,cases.submitter_id, format: TSV, size: 10000 } \ -o manifest_TCGA-LUAD.txt这种方式适合后续要写 pipeline 的用户一次性集成到流程里避免每次都在网页上手工点筛选器。不过提醒一下fields参数中字段名要注意大小写和分隔符比如 GDC 用md5sum而不是md5返回的 TSV 表头和 manifest 略有差异需要简单处理一下再给 GDC-client 使用。4. GDC-client 核心命令详解与实操记录4.1 download 命令的参数说明与实战GDC-client 最核心的命令就是download它的基本用法如下gdc-client download -m manifest_file.txt -d 下载目录-m参数指定 manifest 文件路径-d参数指定下载目录。如果省略-d默认下载到当前目录。这个命令会读取 manifest 中所有条目然后并发下载。常用参数一览参数含义注意事项-m指定 manifest 文件必选参数-d指定下载目录建议设置为项目目录下的gdc_download子目录-t指定 token 文件下载受控数据时必须携带-n并发下载任务数默认 1建议根据网络情况调整-r重试次数默认 0建议设置为 3-5-s分片下载开关默认不开启开启后可提高大文件下载速度--no-related-files不下载关联文件默认会下载所有关联文件实际运行中一个典型的多文件下载命令是gdc-client download -m gdc_manifest_20240101.txt -d ./gdc_download -n 8 -r 5这里的关键参数是-n和-r。-n控制并发数量太小速度慢太大容易触发 GDC 服务器的限流或导致连接中断。我实测下来国内网络环境-n 4左右比较稳妥如果是在海外节点或者代理环境-n 8甚至-n 12都能稳定跑。-r控制在单个文件下载失败后的重试次数建议至少设置 3 次网络不稳定时可以加大到 8 次。4.2 使用 token 下载受控数据TCGA 数据库中部分数据属于受控访问级别比如某些未汇总的 VCF 文件、BAM 原始文件需要先申请 dbGaP 授权然后在 GDC 官网生成 token 文件。下载这类数据时必须带上 tokengdc-client download -m manifest_controlled.txt -d ./gdc_download -t gdc-user-token.2024-01-01.txttoken 文件本质是一串加密令牌GDC-client 会把它的内容放在 HTTP 请求的 Header 中完成身份认证。这里有几个关键经验分享token 文件是有有效期的一般是三个月。过期后下载会报 401 错误这时候需要去 GDC Portal 重新生成。token 文件关联的是你的 GDC 账号不要随意分享给他人也绝对不要上传到 GitHub 等公开仓库。每次下载受控数据前建议先确认 token 文件格式是否正确。直接cat一下 token 文件如果看到的是{token: ...}的 JSON 格式就没问题。一个常见错误是 Windows 用户直接在 PowerShell 里执行命令时token 文件路径带了空格或者反斜杠导致解析失败。建议把 token 文件放在项目根目录用相对路径来引用。4.3 upload 命令和其他辅助命令GDC-client 的另一个常用命令是upload用于向 GDC 上传数据。这个命令主要面向数据提交方比如你要向 TCGA 以外的项目提交测序数据就可能用到。基本格式是gdc-client upload --path /path/to/upload_folder --token gdc-user-token.txt上传数据时也会自动做 MD5 校验保证数据完整性。不过对绝大多数科研人员来说upload 命令很少用到了解有这回事就行。除了上传下载GDC-client 还有一条很有帮助的信息查询命令gdc-client --help这条命令会列出所有可用命令和参数说明。当你忘记参数时可以直接在终端查不用翻文档。4.4 下载过程日志解读与状态分析GDC-client 在下载时会实时输出日志很多人看到一堆日志就发慌其实日志信息非常有价值。我来教你怎么读懂它。典型日志输出大致是这样的Output directory: gdc_download 12:00:01 INFO Downloading: 00022d47-1a3d-4b11-8a52-9fbf7f1c0f1b (1/10) 12:00:03 INFO Download complete: 00022d47-1a3d-4b11-8a52-9fbf7f1c0f1b 12:00:03 INFO Downloaded 10 files successfully; 0 errors如果某个文件下载失败日志会显示类似信息12:05:17 ERROR Failed to download: 00a6e71d-...: Cannot connect to host 12:05:17 INFO Retrying in 5 seconds... (attempt 1/5)这里要注意的信息是“attempt X/Y”Y 就是-r参数指定的重试次数。如果 Y 次都失败了就说明这个文件的连接问题比较顽固光靠 GDC-client 自己重试解决不了需要检查网络或者代理。还有一个常见的日志情况是12:10:22 WARNING An error occurred while trying to download a file: 418这个 418 状态码有点特殊一般是 GDC 服务器认为请求异常比如并发太高触发了限流保护。遇到这种情况降低-n并发数后重新运行即可。4.5 常见问题与排查技巧实录问题一证书验证失败在部分 Linux 环境下运行 GDC-client 可能提示 SSL 证书验证失败。这是因为系统缺少对应的 CA 证书根目录。解决办法很简单yum install ca-certificates -y # CentOS/RHEL apt install ca-certificates -y # Ubuntu/Debian问题二gdc-client: command not found这是 PATH 环境变量没有包含 GDC-client 二进制文件所在目录导致的。重新检查一下文件是否真的下载成功以及 PATH 配置是否正确。临时用一下可以写绝对路径比如/usr/local/bin/gdc-client。问题三Windows 系统杀毒软件拦截Windows Defender 或者其他杀毒软件有时会把 GDC-client 的下载行为误判为异常活动导致下载进程被强制终止。如果出现莫名其妙的中断问题可以先把杀毒软件实时防护临时关闭或者把 GDC-client 所在目录加入白名单。问题四下载目录磁盘空间不足manifest 文件里每个条目有一个 size 字段你可以把所有条目的 size 加起来估算总下载体积。下 BAM 文件的时候几百 GB 的数据量很常见磁盘空间不够会导致失败。建议下载前先在项目目录里跑一下df -h看剩余空间。问题五manifest 文件行尾符问题Windows 用户可能碰到过一个隐藏坑用记事本编辑过 manifest 文件后文件行尾变成 CRLF导致 Linux 上的 GDC-client 解析失败。处理方法很简单用 dos2unix 转换一下dos2unix gdc_manifest_20240101.txt4.6 Windows 下 CMD 而非 PowerShell 的坑这是一个专门想拿出来说的经验。在 Windows 环境下运行 GDC-client官方支持的是 CMD命令提示符而不是 PowerShell。在 PowerShell 中直接运行gdc-client时可能会因为执行策略或控制台代码页的问题导致输出的日志中文乱码或者参数传递异常。我之前排查过一例同样的命令 paste 到 PowerShell 里文件就是下载不下来切到 CMD 一切正常。如果你习惯用 PowerShell也不是完全不能用。可以显式调用 cmd 来执行命令cmd.exe /c gdc-client download -m manifest.txt -d gdc_download不管用哪种终端我都不建议在路径里带空格或中文免得字符编码问题干扰日志解析。5. 从下载到整合数据落地后的整理与验证5.1 下载完成后的目录检查与 MD5 校验很多人在 GDC-client 完成下载后直接从 UUID 目录里把文件复制出来就开工了我建议先做一次整体检查。方法很简单用自带命令行工具对所有子目录的.json元数据文件的md5字段和实际文件比对一下就行。如果你不想写脚本也有个简单的手工方式。GDC-client 在日志里会显示“Downloaded X files successfully 0 errors”如果 errors 不为 0就说明有文件没下成功。这时候可以直接重新运行一次相同的下载命令它会自动跳过已下载且校验通过的文件只补下缺失或损坏的文件。重新补下命令的便捷性是 GDC-client 节省时间的一大原因。因为它会读取已有文件目录里的.json元数据判断哪些文件已经存在且 MD5 校验通过从而跳过这些条目只处理剩余部分。对于网络不稳定的环境来说这个特性特别实用。5.2 文件映射从 UUID 找到样本名GDC 下载下来的文件夹是 UUID虽然对机器友好但人的可读性很差。为了后续分析方便你通常需要把 UUID 映射回 TCGA 样本的 barcode。怎么做最常用的方案是通过 GDC API 查询每个文件 UUID 关联的病例信息curl -X POST https://api.gdc.cancer.gov/files \ -H Content-Type: application/json \ -d { filters: { op: in, content: { field: files.file_id, value: [00022d47-1a3d-4b11-8a52-9fbf7f1c0f1b] } }, fields: file_id,file_name,cases.submitter_id,cases.samples.sample_type,cases.samples.submitter_id, format: TSV }返回结果会包含 sample submitter_id 和 sample type。把这些信息保存成一个映射表后续分析时会非常有用。我习惯在下载完数据后就直接生成一个file_to_sample.tsv映射文件这样每次处理数据都省去查 API 的时间。5.3 用 R 或 Python 读取下载文件的简单示意数据整合到这一步就可以进入正式分析了。比如说你想把某个癌种所有样本的基因表达文件合并成一个表达矩阵。RNA-seq 的 STAR-Counts 结果是一个 TSV 文件一般行是基因 IDEnsembl ID列是对应样本的表达量。Python 遍历目录里的所有文件并合并的代码可以参考import pandas as pd import glob files glob.glob(gdc_download/*/*.tsv) expression [] for f in files: df pd.read_csv(f, sep\t, index_col0, headerNone, names[gene_id, count]) sample_id f.split(/)[1] # 用 UUID 目录作临时 ID df.columns [sample_id] expression.append(df.iloc[:, 0]) expr_matrix pd.concat(expression, axis1) expr_matrix.columns [f.split(/)[1] for f in files] expr_matrix.to_csv(expr_matrix_counts.tsv, sep\t)需要注意的是 STAR-Counts 标准输出里包含一些特殊行比如___no_feature、___ambiguous等统计行以__开头合并前建议先过滤掉。另外GDC 提供的注释文件包含 gene_id 和 gene_name 的映射关系做差异分析时往往需要做一次 ID 转化这也是一个常规操作了。5.4 线下存档与版本管理建议最后说一个实操中很多人忽略的问题TCGA 数据库本身会随着时间推移而不断更新数据版本。半年前下载的数据和现在下载的数据在同样的筛选条件下文件版本可能不同这会影响你的分析结果的可复现性。因此建议每个下载任务完成后把以下文件一并归档保存manifest文件标识这次数据的文件清单GDC Portal 筛选条件截图或者 JSON 配置文件下载日期记录数据版本号Portal 页面底部通常会显示如 GDC Data Release 40.0这样存档一年后再被别人问起“你这数据什么时候下的哪个版本”的时候你能快速给出准确回答。科研数据的管理严谨是第一位。6. 大文件下载的分片策略与逻辑6.1 分片下载的工作原理GDC-client 从 v1.4 开始支持分片下载range request。传统下载是把一个文件作为一个整体从头拉到尾分片下载则是把一个文件切成多个固定大小的片段并发地去拉取不同片段最后在本地合并。这个机制对大文件特别有效尤其是 BAM 文件动辄几 GB 甚至几十 GB 的场景。单个连接传输受限于带宽和延迟分片后理论上可以并行利用更多带宽显著提升下载速度。开启分片下载的方法是在命令中加-s或者--slicinggdc-client download -m manifest.txt -d gdc_download -s默认分片大小一般不用调整用默认值即可。但如果你在日志里看到某些分片反复失败可能和网络路径稳定性有关可以考虑关闭分片、回到普通模式下载。6.2 大文件下载时内存和磁盘的占用分片下载会临时产生多个.part文件碎片这些碎片存在同一个目标文件夹里。如果你的磁盘空间只剩几十 GB千万别启动分片下载大 BAM 文件因为分片数据合并前会占用额外的临时空间极容易把磁盘撑爆。还有一点需要留意分片下载对系统内存占用比普通模式略高。如果服务器内存比较小小于 4GB不建议同时把并发数和分片都开满。实测下来在 4GB 内存的云服务器上-n 4加上-s基本就是内存占用的安全上限了。6.3 何时不需要分片下载小文件几十到几百 MB时分片带来的性能提升几乎可以忽略不计反而可能因为分片多、校验开销大导致整体速度变慢。所以如果你下载的是表达矩阵、甲基化信号文件这类小体量数据直接不带-s参数即可。7. 自动化批量下载集成进分析流程的思路7.1 Shell 脚本自动批量下载多个项目生物信息分析流程中一次性下载多个项目是常有的事。比如你同时要 TCGA-LUAD、TCGA-LUSC、TCGA-BRCA 三个项目的数据只要把三个 manifest 文件分别准备好写一个简单的循环脚本就能自动处理#!/bin/bash for project in LUAD LUSC BRCA; do gdc-client download \ -m manifest_${project}.txt \ -d data/${project} \ -n 4 -r 5 \ --log-file log_${project}.txt done注意--log-file参数可以把日志写入文件而不是只输出到终端。这样你可以挂一个nohup或者后台任务跑完后再统一查看日志不用一直盯着终端窗口。7.2 定时任务与增量更新TCGA 数据库不是静止的每隔一段时间会发布新的数据版本。如果项目在做长期追踪分析可以利用 crontab 写一个定时任务每月拉取最新数据。但这里要强调一个原则不要直接在原来的下载目录上更新而是建议新数据放到新目录通过比较 manifest 文件的内容来判断哪些文件新增了、哪些文件版本变化了。这样做的好处是旧版本的文件不会被覆盖分析结果可以保持可追溯性。7.3 并发数与网络带宽的平衡最后把并发参数再说透一点。-n不是越大越好。GDC 服务器对每个 IP 的并发连接数有限制当你把-n拉到 20 以上大量连接同时建立很容易触发服务器的限流机制表现为任务反复卡住、速度反而下降。一个比较稳的参数选择思路是普通项目文件每个小于 100MB-n 8大文件BAM、FASTQ-n 4加上-s网络信号不稳定丢包率较高-n 2或-n 3优先保证完整率我自己的经验是稳定比速度更重要。下载中断后虽然可以续传但每次重试都要重新建立连接、重新验证元数据花在“返回去处理失败任务”上的时间往往比一开始稳着下载多得多。8. 数据校验与整理后的最后一步归档备份8.1 检查下载日志确保零错误下载完成后第一件事不是处理数据而是确认日志中没有错误。推荐做法是执行完下载命令后手动 grep 一下日志里的错误信息grep -iE error|fail log_download.txt如果没有任何输出说明所有文件都下载成功了。如果还有少量 error直接重新运行下载命令让它自动补下那些失败的文件。8.2 快照文件清单与最终数据管理所有文件下载并验证完成后生成一份完整的文件清单find gdc_download -type f -name *.json download_metadata.txt这份清单配合 manifest 文件保存在一起作为数据包的“身份档案”。以后不管谁拿这批数据去分析只要对照清单就能确认数据来源和完整性。8.3 长期归档时的压缩策略如果你需要把这批数据放到实验室共享存储或者对象存储中建议不要直接压缩整个目录因为 UUID 目录嵌套层次深、文件数量多tar 起来效率不高而且后续要单独取某个文件时还得先解压。更好的办法是维持目录结构不变把整个父目录放入对象存储桶再用单独的文本清单来管理元信息。这样既保留了 GDC-client 原本的目录组织方式又方便后续对单文件做快速访问。我这里再说一个小心得给数据备份时可以把每个 UUID 目录里的.json文件里记录的 MD5 值和对象存储返回的 ETag 做一次比对如果对得上说明备份过程数据没有损坏这个环节能帮你避免很多“备份完才发现数据坏了”的糟心事。9. 从下载到产出一个完整的 TCGA 转录组数据实操复盘前面把 GDC-client 的原理、安装、参数和常见问题都说了一遍这一节我拉一个真实场景带大家把整个流程串一遍也方便你们对照自己的操作。9.1 场景设定与数据范围假设我们要下载 TCGA-LUAD肺腺癌的 RNA-seq 基因表达数据具体条件是数据类别Transcriptome Profiling数据类型Gene Expression Quantification实验策略RNA-Seq分析流程STAR - Counts文件格式TSV在这个条件下GDC Portal 会筛出满足条件的全部文件。9.2 操作步骤实录第一步在 GDC Portal 筛选并下载 manifest进入 Repository 页面左侧筛选器按上述条件逐个勾选右侧列表会自动刷新。点击 Manifest 按钮下载得到gdc_manifest_20240101.txt。第二步预估数据量用文本编辑器或者终端查看 manifest统计文件个数和总大小awk -F\t NR1 {sum$4} END {print NR-1 files, sum/1024/1024/1024 GB} gdc_manifest_20240101.txt这一步的目的是在下载之前就确认磁盘空间是否足够。第三步执行下载在项目目录中运行gdc-client download \ -m gdc_manifest_20240101.txt \ -d ./gdc_download \ -n 8 \ -r 5 \ --log-file log_download_20240101.log下载过程中观察日志输出了解实时进度。第四步校验并整理下载完成后检查日志错误grep -iE error|fail log_download_20240101.log确认没有报错后进入gdc_download目录检查目录结构和数量是否与 manifest 一致。第五步生成文件映射表调用 GDC API将 UUID 映射到样本 barcode并保存为映射表。后续 R/Python 分析直接读取映射表即可完成样本 ID 转换。这一套流程走下来一个转录组表达数据的下载任务就算完整结束了。整个过程大约十分钟的操作时间剩下就是等待下载完成。9.3 进阶批量合并表达矩阵的脚本数据下载并且映射表生成好后合并表达矩阵就非常简单了。这里给一个稍微完整一点的 Python 脚本按映射表重命名样本列import pandas as pd import glob # 读取 UUID 到样本名的映射表 mapping pd.read_csv(file_to_sample.tsv, sep\t, index_col0) expr_list [] for f in glob.glob(gdc_download/*/*.tsv): uuid f.split(/)[1] if uuid not in mapping.index: continue df pd.read_csv(f, sep\t, index_col0, comment#) df df[~df.index.str.startswith(_)] # 过滤掉统计行 sample_name mapping.loc[uuid, sample_submitter_id] df.columns [sample_name] expr_list.append(df) matrix pd.concat(expr_list, axis1) matrix.to_csv(TCGA_LUAD_star_counts_matrix.tsv, sep\t)合并后的表达矩阵就能直接用于差异表达分析、生存分析特征筛选等下游工作了。以后每年 GDC 数据版本更新只需重新走一遍下载流程替换映射文件就能快速产出最新版本的表达矩阵很方便。10. 写在最后几个实战中的细节体会操作过很多次 GDC 数据下载之后我想单独强调几个容易踩坑但很少被文档提到的细节。下载窗口期的问题。GDC 的数据并不是绝对静态的官方会不定期发布数据版本更新。同一份 manifest过几个月重新下载可能会发现文件版本和之前有细微差异。所以你的分析结果如果想保持稳定可复现最好把“数据下载日期数据版本号”写进论文的方法部分。关于并发数真的不要贪。我见过有人为了追求速度把-n调到 50结果大量文件反复失败最后花在排查上的时间比省下来的时间还多。做科研下载数据稳定压倒一切。token 文件的管理要养成习惯。很多人下载受控数据时临时生成 token用完就随手删了等下次需要时又找不到。建议统一放在一个~/.gdc_token/目录下按日期命名比如gdc-user-token.2024-01-01.txt同时把这个目录做好权限控制。还有一个容易被忽略的小问题GDC-client 下载的目录是 UUID但部分下游分析工具比如某些 R 包需要你按 TCGA barcode 来组织文件。这个转换可以在数据下载后立刻做也可以在分析代码里动态做但千万不要把 UUID 目录里的文件复制出来重命名后再删除原目录因为一旦后续需要核对 MD5失去原目录结构会让你非常被动。如果你刚接触 TCGA 数据下载我建议先在本地挑一个小规模的 manifest比如 10 个文件以内测试一遍流程确认网络、工具、参数都没问题后再跑全量数据。毕竟几百个文件下载到一半出问题排查的代价还是要比一开始多花十分钟测试高得多。 GDC-client高效下载TCGA数据：从批量下载到断点续传全攻略
TCGA 数据下载是个老生常谈的话题但每次组里来新人我还是要让他们把 GDC-client 的文档从头到尾读一遍。原因很简单网页端下载器看着方便一旦涉及成百上千个文件或者需要断点续传、校验完整性网页那个“下载篮”方案基本就是给自己找麻烦。GDC-client 是 NCI 官方针对 TCGAThe Cancer Genome Atlas数据分发系统 GDCGenomic Data Commons推出的命令行下载工具本质上是把 HTTP 协议封装成了更可控的多线程任务流专门解决大文件批量下载、中断后续传、以及文件完整性校验这些问题。适合谁用凡是需要下载 RNA-seq 表达矩阵、甲基化芯片原始数据、拷贝数变异 segment 文件或者 WES/WGS 的 BAM 文件的人都应该把 GDC-client 纳入标准工作流。本文会从工具原理、环境配置、配置文件解析、命令使用到实战案例把整个流程完整走一遍。1. 内容整体设计与思路拆解1.1 为什么批量下载必须放弃网页端很多人第一次下 TCGA 数据第一反应是打开 GDC Portal 网页把感兴趣的病例加入购物车然后点 Download。这个流程对下载几个文件来说完全没问题但放到科研场景里根本不现实。举个例子你想下载某个癌种全部样本的 RNA-seq 基因表达 STAR-Counts 结果样本量动辄几百甚至上千每个样本对应一个表达文件。通过网页下载你得到的是一个一个手工保存的文件名字还是乱七八糟的 UUID整理起来累死人。更关键的是网页下载没有断点续传机制。网络稍微波动一下下载到一半的文件直接作废又得重头再来。我见过一个师弟下几百个文件因为宿舍网络不稳定点了整整一下午最后成功落地的不足六成剩下全是损坏的压缩包。这种体验相信不少人都经历过。GDC-client 解决的就是这三个问题批量调度、断点续传、数据校验。它通过读取一个 manifest 文件来获取需要下载的文件 ID、文件名和校验信息然后多线程并发下载。整个下载过程每一个文件都落盘到以文件 UUID 命名的子目录里最后生成对应的.json元数据文件方便后续追溯和管理。也就是说只要配置得当几百个文件可以无人值守地批量拉取中间的失败会自动重试实在不行还能手动补跑。1.2 GDC-client 的工作流程和核心文件GDC-client 的工作流程可以概括为三步获取 manifest、配置下载参数、执行下载任务。manifest 文件是 GDC Portal 中根据你的筛选条件自动生成的清单本质上是一个 TSVTab 分隔文件包含四列id文件的 UUID全局唯一标识符filename原始文件名md5该文件的 MD5 校验值size文件大小单位是字节为什么要有这个清单因为 GDC 服务器上所有文件的访问路径都是基于 UUID 生成的文件名只是给人看的元数据。你单独知道文件名是没法直接定位到文件的必须通过 manifest 里的 UUID 去请求 API。GDC-client 做的事就是逐行解析这个文件然后向 GDC API 发起请求并下载文件本体。下载完成后每个文件目录下除了数据文件本身还会有一个.json格式的元数据文件记录文件的 MD5、大小、下载时间等信息。这个设计很贴心你在后续整理数据时不用重新回 GDC Portal 查这些信息直接读本地 JSON 就行。另外要理解一个关键概念GDC 的下载接口分两种一种是普通文件下载一种是受控数据下载。普通数据如 HTSeq-Counts 表达矩阵、masked 的甲基化信号不需要认证直接下载受控数据如部分 WES 的 BAM 文件、未 mask 的 VCF 文件需要 GDC 账号申请 dbGaP 权限并且在下载时携带 token 文件。GDC-client 的-t参数就是干这个用的。1.3 工具选型对比为什么是 GDC-client 而不是 gdc_get 或 API 脚本为什么不用 Python 的 requests 库直接调 GDC API毕竟 API 文档也是公开的自己写脚本看起来更“灵活”。我来说说自己的体会。API 方案需要你自己处理重试机制、线程池、断点续传和校验逻辑这些功能看起来不难但真正做起来很容易出 bug。GDC-client 已经把这些基础能力固化进 C 实现里而且是官方团队长期维护的稳定性有保障。至于另一个常用方案gdc_get那是社区第三方开发的下载工具虽然在某些场景下速度表现不错但涉及 token 鉴权和断点续传时偶尔会出现兼容性问题。官方 GDC-client 在这些细节上做得更稳妥尤其是处理受控数据时token 的认证流程是官方验证过的不容易遇到“明明有权限但下载 403”这种尴尬。我个人的建议是如果你只是偶尔下载十几个文件网页端或者轻量脚本都行但凡是下载量超过 50 个文件、或者文件本身是大体积的 BAM/FASTQ直接上 GDC-client 不带犹豫的。2. GDC-client 下载安装与环境配置详解2.1 各平台下载方式与版本选择GDC-client 官方发布的安装包支持 Windows、macOS 和 Linux 三大平台。建议直接到 GDC 官网的 Software 页面下载最新版本。截止我写这篇文章时官方最新稳定版本为 v3.0 系列但版本更新迭代较快大家以官网为准。有几个选版本时的注意事项如果你用的是 CentOS 7 这类比较老的 Linux 发行版注意 glibc 版本兼容问题。新版本 GDC-client 可能在旧 glibc 环境下报错这时候可以选择历史版本或者升级系统库。macOS 用户注意区分 Apple SiliconM1/M2/M3和 Intel 芯片官方提供的是通用版但如果你的机器比较老可能会出现权限问题。Windows 用户下载的压缩包里是.exe可执行文件不需要安装解压即用。这里放一个各平台下载和安装的最小操作说明Linux# 下载 tarball 包以官方最新版本链接为准 wget https://gdc.cancer.gov/files/public/file/gdc-client_v3.0.1_Ubuntu_x64.zip # 解压 unzip gdc-client_v3.0.1_Ubuntu_x64.zip # 把二进制文件移动到 PATH 环境变量包含的目录 mv gdc-client /usr/local/bin/ gdc-client --versionmacOS# 下载对应版本的 dmg 或 zip 包 # 如果下载后提示无法打开需要去 系统设置 - 隐私与安全性 中允许该应用运行Windows解压 zip 包后得到gdc-client.exe建议把整个文件夹加入系统 PATH 环境变量。具体操作是右键“此电脑” - 属性 - 高级系统设置 - 环境变量 - 在 Path 中新增解压目录路径。不加入 PATH 也可以只是每次调用都需要带上完整路径比较麻烦。安装后第一件事就是验证版本确认二进制文件能正常运行gdc-client --version正常输出类似gdc-client v3.0.1这样的信息就说明安装成功了。2.2 路径规划与目录结构设计GDC-client 下载文件默认以文件 UUID 作为一级目录名文件原始名作为二级文件名。在开始下载之前我强烈建议你先规划好目录结构这是很多人忽略但实际非常重要的环节。举个反面例子。我见过有人直接在~/Downloads下面跑 GDC-client结果整个目录全是 UUID 文件夹后续样本整理和分析时根本对不上哪个文件属于哪个样本。正确做法是为每一个下载任务单独建立一个项目目录目录名最好包含数据集信息和版本号比如data/ └── TCGA-LUAD/ ├── manifest_20240101.txt └── gdc_download/ ├── 00022d47-1a3d-4b11-8a52-9fbf7f1c0f1b/ │ ├── 1a9c9e0d-8b0f-4db5-a75f-... .txt │ └── 00022d47-... .json └── 00a6e71d-0ae9-4f5e-9a3f-... / ├── 3c1a2e3b-... .txt └── 00a6e71d-... .json这样设计的好处是后续不管你用 R 还是 Python 处理数据都能根据父目录名快速定位到样本对应的文件。此外建议在下载完成后保留 manifest 文件副本作为这次数据批次的身份标识。GDC 数据库版本升级后同样的筛选条件重新生成的 manifest 可能略有差异保留旧版 manifest 可以方便审计和复现。2.3 网络环境要求与断点续传的理解GDC 的下载服务器部署在 AWS 上域名为api.gdc.cancer.gov和gdc-api.nci.nih.gov。国内用户下载时经常遇到速度慢或者连接中断的问题这个不是 GDC 服务器的问题而是跨境网络链路质量不稳定导致的。如果你也是这种情况可以尝试两个办法使用代理。在 GDC-client 命令中通过环境变量HTTPS_PROXY指定代理地址适合有实验室代理或者云服务器代理的情况。错峰下载。美东时间白天对应北京时间凌晨这个时段跨境链路相对空一些下载速度通常会有明显改善。但不管网络多差GDC-client 的断点续传机制都能让你省心不少。它的实现原理是下载每个文件时先创建一个对应的临时文件后缀为.part下载过程中持续写入同时记录当前已下载的字节数。如果下载中断下次运行相同命令时工具会检测到.part文件的存在并从断点继续下载。完整下载完成后.part文件会被重命名为目标文件。所以中间网络断了或者命令被 CtrlC 中断都不需要惊慌重新跑一次命令即可续传。这里有一个经验之谈某些文件在下载过程中如果长时间没有新的数据写入可能会被服务器判定为超时而断开连接GDC-client 默认会在一定时间后自动重试。你可以通过调整下载参数来优化重试行为这个我在后面结合具体命令讲。3. GDC 数据检索与 manifest 文件生成3.1 在 GDC Portal 上筛选数据并生成清单manifest 文件的生成是使用 GDC-client 之前最重要的一步也是最容易出错的一步。因为你选的数据范围直接决定了下载内容的对与错。访问 GDC Portalportal.gdc.cancer.gov点击页面顶部“Repository”进入数据仓库页面。在这里你可以通过左侧的筛选器来限定数据范围包括Primary Site原发部位如 Lung、Breast、ColorectalProject具体项目编号如 TCGA-LUAD、TCGA-BRCAData Category数据类别如 Transcriptome Profiling、Copy Number VariationData Type数据类型如 Gene Expression Quantification、Masked Copy Number SegmentExperimental Strategy实验策略如 RNA-Seq、WXS、WGSWorkflow Type分析流程如 STAR-Counts、STAR - Gene Quantification这个选项在转录组数据中很常用把筛选条件设置好之后页面会列出符合条件的文件清单同时显示总数和总体积。在这一步我强烈建议你先看一眼“总体积”因为它直接决定了你的下载时间。比如筛选出两三百个 BAM 文件体量很可能达到数百 GB你得确认自己的磁盘空间是否足够。确认文件清单没问题后点击“Manifest”按钮浏览器会自动下载一个.txt文件。这个文件就是 GDC-client 下载时需要读取的清单文件。默认文件名通常是gdc_manifest_日期.txt格式如下id filename md5 size 00022d47-1a3d-4b11-8a52-9fbf7f1c0f1b 01a2d3e4-..._counts.txt abcdef1234567890abcdef1234567890 1234563.2 理解 manifest 的关键字段manifest 文件看似简单但四个字段都很有讲究id是文件 UUID这是 GDC 内部文件的主键也是 GDC-client 访问服务器的钥匙。filename只是给你看的样本文件名它往往是UUID_基因注释来源的形式。这里有个小注意点GDC 不同时间段处理的样本文件名后缀格式可能不太一样。比如有些是.htseq.counts.gz有些是.tsv.gz这跟 GDC 的处理流程版本有关不影响你下载但后续读入数据时要注意匹配。md5是文件内容的 MD5 哈希值用于校验下载文件的完整性。GDC-client 在下载完成后会自动计算本地文件的 MD5 并与 manifest 中的值比较不一致的话会判定下载失败并重新下载。size是字节大小。有时候筛选条件相同、时间点不同的两次下载size 值也会有细微差异这与 GDC 数据的版本更新有关。所以在博文、论文中分析 TCGA 数据时最好明确记录数据下载日期和 GDC 数据版本否则后续别人复现你的分析时可能对不上结果。3.3 使用 API 自动生成 manifest进阶用法除了在网页端手工生成 manifestGDC 还提供了一套 REST API让你可以用脚本方式自动化获取清单。这对于需要同时处理多个癌种或者多组数据的用户特别有用。比如你想查询 TCGA-LUAD 项目中所有 RNA-Seq 的 STAR-Counts 基因表达文件可以用如下 API 查询curl -X POST https://api.gdc.cancer.gov/files \ -H Content-Type: application/json \ -d { filters: { op: and, content: [ { op: in, content: { field: cases.project.project_id, value: [TCGA-LUAD] } }, { op: in, content: { field: files.experimental_strategy, value: [RNA-Seq] } }, { op: in, content: { field: files.analysis.workflow_type, value: [STAR - Counts] } } ] }, fields: file_id,file_name,md5sum,file_size,cases.submitter_id, format: TSV, size: 10000 } \ -o manifest_TCGA-LUAD.txt这种方式适合后续要写 pipeline 的用户一次性集成到流程里避免每次都在网页上手工点筛选器。不过提醒一下fields参数中字段名要注意大小写和分隔符比如 GDC 用md5sum而不是md5返回的 TSV 表头和 manifest 略有差异需要简单处理一下再给 GDC-client 使用。4. GDC-client 核心命令详解与实操记录4.1 download 命令的参数说明与实战GDC-client 最核心的命令就是download它的基本用法如下gdc-client download -m manifest_file.txt -d 下载目录-m参数指定 manifest 文件路径-d参数指定下载目录。如果省略-d默认下载到当前目录。这个命令会读取 manifest 中所有条目然后并发下载。常用参数一览参数含义注意事项-m指定 manifest 文件必选参数-d指定下载目录建议设置为项目目录下的gdc_download子目录-t指定 token 文件下载受控数据时必须携带-n并发下载任务数默认 1建议根据网络情况调整-r重试次数默认 0建议设置为 3-5-s分片下载开关默认不开启开启后可提高大文件下载速度--no-related-files不下载关联文件默认会下载所有关联文件实际运行中一个典型的多文件下载命令是gdc-client download -m gdc_manifest_20240101.txt -d ./gdc_download -n 8 -r 5这里的关键参数是-n和-r。-n控制并发数量太小速度慢太大容易触发 GDC 服务器的限流或导致连接中断。我实测下来国内网络环境-n 4左右比较稳妥如果是在海外节点或者代理环境-n 8甚至-n 12都能稳定跑。-r控制在单个文件下载失败后的重试次数建议至少设置 3 次网络不稳定时可以加大到 8 次。4.2 使用 token 下载受控数据TCGA 数据库中部分数据属于受控访问级别比如某些未汇总的 VCF 文件、BAM 原始文件需要先申请 dbGaP 授权然后在 GDC 官网生成 token 文件。下载这类数据时必须带上 tokengdc-client download -m manifest_controlled.txt -d ./gdc_download -t gdc-user-token.2024-01-01.txttoken 文件本质是一串加密令牌GDC-client 会把它的内容放在 HTTP 请求的 Header 中完成身份认证。这里有几个关键经验分享token 文件是有有效期的一般是三个月。过期后下载会报 401 错误这时候需要去 GDC Portal 重新生成。token 文件关联的是你的 GDC 账号不要随意分享给他人也绝对不要上传到 GitHub 等公开仓库。每次下载受控数据前建议先确认 token 文件格式是否正确。直接cat一下 token 文件如果看到的是{token: ...}的 JSON 格式就没问题。一个常见错误是 Windows 用户直接在 PowerShell 里执行命令时token 文件路径带了空格或者反斜杠导致解析失败。建议把 token 文件放在项目根目录用相对路径来引用。4.3 upload 命令和其他辅助命令GDC-client 的另一个常用命令是upload用于向 GDC 上传数据。这个命令主要面向数据提交方比如你要向 TCGA 以外的项目提交测序数据就可能用到。基本格式是gdc-client upload --path /path/to/upload_folder --token gdc-user-token.txt上传数据时也会自动做 MD5 校验保证数据完整性。不过对绝大多数科研人员来说upload 命令很少用到了解有这回事就行。除了上传下载GDC-client 还有一条很有帮助的信息查询命令gdc-client --help这条命令会列出所有可用命令和参数说明。当你忘记参数时可以直接在终端查不用翻文档。4.4 下载过程日志解读与状态分析GDC-client 在下载时会实时输出日志很多人看到一堆日志就发慌其实日志信息非常有价值。我来教你怎么读懂它。典型日志输出大致是这样的Output directory: gdc_download 12:00:01 INFO Downloading: 00022d47-1a3d-4b11-8a52-9fbf7f1c0f1b (1/10) 12:00:03 INFO Download complete: 00022d47-1a3d-4b11-8a52-9fbf7f1c0f1b 12:00:03 INFO Downloaded 10 files successfully; 0 errors如果某个文件下载失败日志会显示类似信息12:05:17 ERROR Failed to download: 00a6e71d-...: Cannot connect to host 12:05:17 INFO Retrying in 5 seconds... (attempt 1/5)这里要注意的信息是“attempt X/Y”Y 就是-r参数指定的重试次数。如果 Y 次都失败了就说明这个文件的连接问题比较顽固光靠 GDC-client 自己重试解决不了需要检查网络或者代理。还有一个常见的日志情况是12:10:22 WARNING An error occurred while trying to download a file: 418这个 418 状态码有点特殊一般是 GDC 服务器认为请求异常比如并发太高触发了限流保护。遇到这种情况降低-n并发数后重新运行即可。4.5 常见问题与排查技巧实录问题一证书验证失败在部分 Linux 环境下运行 GDC-client 可能提示 SSL 证书验证失败。这是因为系统缺少对应的 CA 证书根目录。解决办法很简单yum install ca-certificates -y # CentOS/RHEL apt install ca-certificates -y # Ubuntu/Debian问题二gdc-client: command not found这是 PATH 环境变量没有包含 GDC-client 二进制文件所在目录导致的。重新检查一下文件是否真的下载成功以及 PATH 配置是否正确。临时用一下可以写绝对路径比如/usr/local/bin/gdc-client。问题三Windows 系统杀毒软件拦截Windows Defender 或者其他杀毒软件有时会把 GDC-client 的下载行为误判为异常活动导致下载进程被强制终止。如果出现莫名其妙的中断问题可以先把杀毒软件实时防护临时关闭或者把 GDC-client 所在目录加入白名单。问题四下载目录磁盘空间不足manifest 文件里每个条目有一个 size 字段你可以把所有条目的 size 加起来估算总下载体积。下 BAM 文件的时候几百 GB 的数据量很常见磁盘空间不够会导致失败。建议下载前先在项目目录里跑一下df -h看剩余空间。问题五manifest 文件行尾符问题Windows 用户可能碰到过一个隐藏坑用记事本编辑过 manifest 文件后文件行尾变成 CRLF导致 Linux 上的 GDC-client 解析失败。处理方法很简单用 dos2unix 转换一下dos2unix gdc_manifest_20240101.txt4.6 Windows 下 CMD 而非 PowerShell 的坑这是一个专门想拿出来说的经验。在 Windows 环境下运行 GDC-client官方支持的是 CMD命令提示符而不是 PowerShell。在 PowerShell 中直接运行gdc-client时可能会因为执行策略或控制台代码页的问题导致输出的日志中文乱码或者参数传递异常。我之前排查过一例同样的命令 paste 到 PowerShell 里文件就是下载不下来切到 CMD 一切正常。如果你习惯用 PowerShell也不是完全不能用。可以显式调用 cmd 来执行命令cmd.exe /c gdc-client download -m manifest.txt -d gdc_download不管用哪种终端我都不建议在路径里带空格或中文免得字符编码问题干扰日志解析。5. 从下载到整合数据落地后的整理与验证5.1 下载完成后的目录检查与 MD5 校验很多人在 GDC-client 完成下载后直接从 UUID 目录里把文件复制出来就开工了我建议先做一次整体检查。方法很简单用自带命令行工具对所有子目录的.json元数据文件的md5字段和实际文件比对一下就行。如果你不想写脚本也有个简单的手工方式。GDC-client 在日志里会显示“Downloaded X files successfully 0 errors”如果 errors 不为 0就说明有文件没下成功。这时候可以直接重新运行一次相同的下载命令它会自动跳过已下载且校验通过的文件只补下缺失或损坏的文件。重新补下命令的便捷性是 GDC-client 节省时间的一大原因。因为它会读取已有文件目录里的.json元数据判断哪些文件已经存在且 MD5 校验通过从而跳过这些条目只处理剩余部分。对于网络不稳定的环境来说这个特性特别实用。5.2 文件映射从 UUID 找到样本名GDC 下载下来的文件夹是 UUID虽然对机器友好但人的可读性很差。为了后续分析方便你通常需要把 UUID 映射回 TCGA 样本的 barcode。怎么做最常用的方案是通过 GDC API 查询每个文件 UUID 关联的病例信息curl -X POST https://api.gdc.cancer.gov/files \ -H Content-Type: application/json \ -d { filters: { op: in, content: { field: files.file_id, value: [00022d47-1a3d-4b11-8a52-9fbf7f1c0f1b] } }, fields: file_id,file_name,cases.submitter_id,cases.samples.sample_type,cases.samples.submitter_id, format: TSV }返回结果会包含 sample submitter_id 和 sample type。把这些信息保存成一个映射表后续分析时会非常有用。我习惯在下载完数据后就直接生成一个file_to_sample.tsv映射文件这样每次处理数据都省去查 API 的时间。5.3 用 R 或 Python 读取下载文件的简单示意数据整合到这一步就可以进入正式分析了。比如说你想把某个癌种所有样本的基因表达文件合并成一个表达矩阵。RNA-seq 的 STAR-Counts 结果是一个 TSV 文件一般行是基因 IDEnsembl ID列是对应样本的表达量。Python 遍历目录里的所有文件并合并的代码可以参考import pandas as pd import glob files glob.glob(gdc_download/*/*.tsv) expression [] for f in files: df pd.read_csv(f, sep\t, index_col0, headerNone, names[gene_id, count]) sample_id f.split(/)[1] # 用 UUID 目录作临时 ID df.columns [sample_id] expression.append(df.iloc[:, 0]) expr_matrix pd.concat(expression, axis1) expr_matrix.columns [f.split(/)[1] for f in files] expr_matrix.to_csv(expr_matrix_counts.tsv, sep\t)需要注意的是 STAR-Counts 标准输出里包含一些特殊行比如___no_feature、___ambiguous等统计行以__开头合并前建议先过滤掉。另外GDC 提供的注释文件包含 gene_id 和 gene_name 的映射关系做差异分析时往往需要做一次 ID 转化这也是一个常规操作了。5.4 线下存档与版本管理建议最后说一个实操中很多人忽略的问题TCGA 数据库本身会随着时间推移而不断更新数据版本。半年前下载的数据和现在下载的数据在同样的筛选条件下文件版本可能不同这会影响你的分析结果的可复现性。因此建议每个下载任务完成后把以下文件一并归档保存manifest文件标识这次数据的文件清单GDC Portal 筛选条件截图或者 JSON 配置文件下载日期记录数据版本号Portal 页面底部通常会显示如 GDC Data Release 40.0这样存档一年后再被别人问起“你这数据什么时候下的哪个版本”的时候你能快速给出准确回答。科研数据的管理严谨是第一位。6. 大文件下载的分片策略与逻辑6.1 分片下载的工作原理GDC-client 从 v1.4 开始支持分片下载range request。传统下载是把一个文件作为一个整体从头拉到尾分片下载则是把一个文件切成多个固定大小的片段并发地去拉取不同片段最后在本地合并。这个机制对大文件特别有效尤其是 BAM 文件动辄几 GB 甚至几十 GB 的场景。单个连接传输受限于带宽和延迟分片后理论上可以并行利用更多带宽显著提升下载速度。开启分片下载的方法是在命令中加-s或者--slicinggdc-client download -m manifest.txt -d gdc_download -s默认分片大小一般不用调整用默认值即可。但如果你在日志里看到某些分片反复失败可能和网络路径稳定性有关可以考虑关闭分片、回到普通模式下载。6.2 大文件下载时内存和磁盘的占用分片下载会临时产生多个.part文件碎片这些碎片存在同一个目标文件夹里。如果你的磁盘空间只剩几十 GB千万别启动分片下载大 BAM 文件因为分片数据合并前会占用额外的临时空间极容易把磁盘撑爆。还有一点需要留意分片下载对系统内存占用比普通模式略高。如果服务器内存比较小小于 4GB不建议同时把并发数和分片都开满。实测下来在 4GB 内存的云服务器上-n 4加上-s基本就是内存占用的安全上限了。6.3 何时不需要分片下载小文件几十到几百 MB时分片带来的性能提升几乎可以忽略不计反而可能因为分片多、校验开销大导致整体速度变慢。所以如果你下载的是表达矩阵、甲基化信号文件这类小体量数据直接不带-s参数即可。7. 自动化批量下载集成进分析流程的思路7.1 Shell 脚本自动批量下载多个项目生物信息分析流程中一次性下载多个项目是常有的事。比如你同时要 TCGA-LUAD、TCGA-LUSC、TCGA-BRCA 三个项目的数据只要把三个 manifest 文件分别准备好写一个简单的循环脚本就能自动处理#!/bin/bash for project in LUAD LUSC BRCA; do gdc-client download \ -m manifest_${project}.txt \ -d data/${project} \ -n 4 -r 5 \ --log-file log_${project}.txt done注意--log-file参数可以把日志写入文件而不是只输出到终端。这样你可以挂一个nohup或者后台任务跑完后再统一查看日志不用一直盯着终端窗口。7.2 定时任务与增量更新TCGA 数据库不是静止的每隔一段时间会发布新的数据版本。如果项目在做长期追踪分析可以利用 crontab 写一个定时任务每月拉取最新数据。但这里要强调一个原则不要直接在原来的下载目录上更新而是建议新数据放到新目录通过比较 manifest 文件的内容来判断哪些文件新增了、哪些文件版本变化了。这样做的好处是旧版本的文件不会被覆盖分析结果可以保持可追溯性。7.3 并发数与网络带宽的平衡最后把并发参数再说透一点。-n不是越大越好。GDC 服务器对每个 IP 的并发连接数有限制当你把-n拉到 20 以上大量连接同时建立很容易触发服务器的限流机制表现为任务反复卡住、速度反而下降。一个比较稳的参数选择思路是普通项目文件每个小于 100MB-n 8大文件BAM、FASTQ-n 4加上-s网络信号不稳定丢包率较高-n 2或-n 3优先保证完整率我自己的经验是稳定比速度更重要。下载中断后虽然可以续传但每次重试都要重新建立连接、重新验证元数据花在“返回去处理失败任务”上的时间往往比一开始稳着下载多得多。8. 数据校验与整理后的最后一步归档备份8.1 检查下载日志确保零错误下载完成后第一件事不是处理数据而是确认日志中没有错误。推荐做法是执行完下载命令后手动 grep 一下日志里的错误信息grep -iE error|fail log_download.txt如果没有任何输出说明所有文件都下载成功了。如果还有少量 error直接重新运行下载命令让它自动补下那些失败的文件。8.2 快照文件清单与最终数据管理所有文件下载并验证完成后生成一份完整的文件清单find gdc_download -type f -name *.json download_metadata.txt这份清单配合 manifest 文件保存在一起作为数据包的“身份档案”。以后不管谁拿这批数据去分析只要对照清单就能确认数据来源和完整性。8.3 长期归档时的压缩策略如果你需要把这批数据放到实验室共享存储或者对象存储中建议不要直接压缩整个目录因为 UUID 目录嵌套层次深、文件数量多tar 起来效率不高而且后续要单独取某个文件时还得先解压。更好的办法是维持目录结构不变把整个父目录放入对象存储桶再用单独的文本清单来管理元信息。这样既保留了 GDC-client 原本的目录组织方式又方便后续对单文件做快速访问。我这里再说一个小心得给数据备份时可以把每个 UUID 目录里的.json文件里记录的 MD5 值和对象存储返回的 ETag 做一次比对如果对得上说明备份过程数据没有损坏这个环节能帮你避免很多“备份完才发现数据坏了”的糟心事。9. 从下载到产出一个完整的 TCGA 转录组数据实操复盘前面把 GDC-client 的原理、安装、参数和常见问题都说了一遍这一节我拉一个真实场景带大家把整个流程串一遍也方便你们对照自己的操作。9.1 场景设定与数据范围假设我们要下载 TCGA-LUAD肺腺癌的 RNA-seq 基因表达数据具体条件是数据类别Transcriptome Profiling数据类型Gene Expression Quantification实验策略RNA-Seq分析流程STAR - Counts文件格式TSV在这个条件下GDC Portal 会筛出满足条件的全部文件。9.2 操作步骤实录第一步在 GDC Portal 筛选并下载 manifest进入 Repository 页面左侧筛选器按上述条件逐个勾选右侧列表会自动刷新。点击 Manifest 按钮下载得到gdc_manifest_20240101.txt。第二步预估数据量用文本编辑器或者终端查看 manifest统计文件个数和总大小awk -F\t NR1 {sum$4} END {print NR-1 files, sum/1024/1024/1024 GB} gdc_manifest_20240101.txt这一步的目的是在下载之前就确认磁盘空间是否足够。第三步执行下载在项目目录中运行gdc-client download \ -m gdc_manifest_20240101.txt \ -d ./gdc_download \ -n 8 \ -r 5 \ --log-file log_download_20240101.log下载过程中观察日志输出了解实时进度。第四步校验并整理下载完成后检查日志错误grep -iE error|fail log_download_20240101.log确认没有报错后进入gdc_download目录检查目录结构和数量是否与 manifest 一致。第五步生成文件映射表调用 GDC API将 UUID 映射到样本 barcode并保存为映射表。后续 R/Python 分析直接读取映射表即可完成样本 ID 转换。这一套流程走下来一个转录组表达数据的下载任务就算完整结束了。整个过程大约十分钟的操作时间剩下就是等待下载完成。9.3 进阶批量合并表达矩阵的脚本数据下载并且映射表生成好后合并表达矩阵就非常简单了。这里给一个稍微完整一点的 Python 脚本按映射表重命名样本列import pandas as pd import glob # 读取 UUID 到样本名的映射表 mapping pd.read_csv(file_to_sample.tsv, sep\t, index_col0) expr_list [] for f in glob.glob(gdc_download/*/*.tsv): uuid f.split(/)[1] if uuid not in mapping.index: continue df pd.read_csv(f, sep\t, index_col0, comment#) df df[~df.index.str.startswith(_)] # 过滤掉统计行 sample_name mapping.loc[uuid, sample_submitter_id] df.columns [sample_name] expr_list.append(df) matrix pd.concat(expr_list, axis1) matrix.to_csv(TCGA_LUAD_star_counts_matrix.tsv, sep\t)合并后的表达矩阵就能直接用于差异表达分析、生存分析特征筛选等下游工作了。以后每年 GDC 数据版本更新只需重新走一遍下载流程替换映射文件就能快速产出最新版本的表达矩阵很方便。10. 写在最后几个实战中的细节体会操作过很多次 GDC 数据下载之后我想单独强调几个容易踩坑但很少被文档提到的细节。下载窗口期的问题。GDC 的数据并不是绝对静态的官方会不定期发布数据版本更新。同一份 manifest过几个月重新下载可能会发现文件版本和之前有细微差异。所以你的分析结果如果想保持稳定可复现最好把“数据下载日期数据版本号”写进论文的方法部分。关于并发数真的不要贪。我见过有人为了追求速度把-n调到 50结果大量文件反复失败最后花在排查上的时间比省下来的时间还多。做科研下载数据稳定压倒一切。token 文件的管理要养成习惯。很多人下载受控数据时临时生成 token用完就随手删了等下次需要时又找不到。建议统一放在一个~/.gdc_token/目录下按日期命名比如gdc-user-token.2024-01-01.txt同时把这个目录做好权限控制。还有一个容易被忽略的小问题GDC-client 下载的目录是 UUID但部分下游分析工具比如某些 R 包需要你按 TCGA barcode 来组织文件。这个转换可以在数据下载后立刻做也可以在分析代码里动态做但千万不要把 UUID 目录里的文件复制出来重命名后再删除原目录因为一旦后续需要核对 MD5失去原目录结构会让你非常被动。如果你刚接触 TCGA 数据下载我建议先在本地挑一个小规模的 manifest比如 10 个文件以内测试一遍流程确认网络、工具、参数都没问题后再跑全量数据。毕竟几百个文件下载到一半出问题排查的代价还是要比一开始多花十分钟测试高得多。