TCGA数据批量下载实践：GDC-client安装、配置与常见问题全解析

做生信的人跟TCGA打交道几乎是必修课。这个癌症基因组图谱数据库攒了33种癌症、上万个样本的测序和临床数据从表达量、突变、拷贝数到甲基化全部覆盖很多肿瘤方向的研究都靠它起步。但TCGA的数据量早就不是早期那种“网页点几下就能下载”的体量尤其当你需要拿一批样本的RNA-seq或突变数据时几十上百个文件一个个从浏览器下载基本等于把时间浪费在反复重试上。GDC-client就是官方为了解决这个场景推出的命令行数据下载工具支持清单批量下载、断点续传和文件校验是很多老手在TCGA数据库里批量取数时的默认选择。这篇文章按我自己的实操顺序来写先说清楚为什么需要这个工具再讲三个平台的安装细节然后重点拆解从筛选数据到生成manifest、到跑通下载命令的完整路径最后把我踩过的报错、以及数据下载完之后的整理经验一并交代。无论你是刚接触TCGA数据库的新手还是已经在portal上折腾过一阵但还没用顺命令行工具的研究生都可以照着操作一遍。1. 为什么TCGA数据要用GDC-client而不是浏览器直接拉1.1 TCGA数据库和GDC平台的关系说GDC-client之前得先把TCGA和GDC的关系捋清楚。TCGA是The Cancer Genome Atlas的缩写是由美国国家癌症研究所NCI和国家人类基因组研究所NHGRI联合推动的大型公共项目从2006年前后开始运作覆盖了33种癌症类型积累了超过2万个肿瘤样本的基因组、转录组、表观遗传数据以及对应的临床和病理信息。这里有个容易混淆的点TCGA本身是一个研究计划它的数据现在已经统一托管在GDCGenomic Data Commons基因组数据共享平台里。所以你现在打开portal.gdc.cancer.gov看到的其实是GDC Portal它整合了TCGA、TARGET、CCLE等几个大型癌症数据项目。你要下载的TCGA数据实际上都是从GDC这个“仓库”里取的。GDC官方提供了两种下载路径网页端的Cart功能以及命令行的GDC Data Transfer Tool。网页端适合临时取少量文件命令行工具就是GDC-client专门解决大量文件的批量传输。很多刚接触的人容易忽略这一点以为只有网页端入口等到文件多了才发现网页端根本撑不住。1.2 浏览器直接下载的三个硬伤接触过TCGA的人都知道portal上筛选数据很直观按癌症类型、数据类型、平台勾选就行。可问题出在下载环节。浏览器直接下载有三个绕不开的硬伤。第一文件一多浏览器下载任务管理就是灾难。一次下载几十个甚至几百个文件浏览器里密密麻麻全是下载任务哪个下完了、哪个断了很难一眼看出来一旦关错页面或者浏览器崩溃之前的下载队列全没了。第二没有断点续传。这是最伤人的。单个文件下到百分之七八十网络一抖断了浏览器不会帮你从断点接着传只能从头再来一遍。RNA-seq的counts文件虽然不算特别大但成百上千个文件反复断点时间成本翻着倍往上走。第三没有完整性校验。GDC官方传输链路里带了md5校验机制下载完会比对文件是否完整浏览器下载没有这个能力文件丢几个字节你根本不知道等分析跑到一半才发现数据有问题那种返工才叫折磨。1.3 GDC-client的核心能力GDC-client是官方维护的命令行工具解决的就是上面这些场景。它的核心能力包括通过manifest清单文件批量下载一条命令带走几十上百个文件断点续传中断后重新执行命令已经完成的任务会跳过继续传未完成的自动校验下载过程中会比对文件md5值文件损坏会自动重新拉取支持受控数据通过token文件访问需要授权的保护数据。我第一次跑通之后就再也没在浏览器里点过下载按钮。这个工具不光是效率问题更是数据可靠性问题。后面我会把每个环节的具体操作展开讲。2. 安装GDC-clientWindows、macOS、Linux三平台实操记录2.1 从官方页面找到正确的版本我始终建议从GDC官网的Access Data页面进入找GDC Data Transfer Tool的下载入口。页面往下拉能看到最新版本的发布记录一般同时提供Windows、macOS、Linux三种平台的压缩包。这里面有个细节值得注意官方发布文件名里通常会带上版本号、平台和体系结构信息比如Linux版本会标明是64位x86_64。绝大多数人的服务器都是64位Linux下载x86_64版本就行。如果你跑在ARM架构的服务器上就需要确认官方有没有对应的ARM构建目前官方对主流x86_64的支持是最完善的。版本选择有个原则不必追新但也别长期停在特别老的版本。GDC服务端的接口会持续演进老版本client偶尔会遇到接口不兼容的奇怪问题。如果你发现某个老版本下载时老报一些看不懂的HTTP错误去官方页面看看有没有新版本往往比排查半天配置更有效。2.2 解压、环境变量与常见安装坑三个平台的安装本质都是两件事解压文件把可执行文件路径加进环境变量。Windows平台下载下来通常是zip压缩包解压后能看到一个gdc-client.exe。这里有两种用法。一种是不配环境变量每次都切换到解压目录下执行.\gdc-client.exe另一种更省事把解压路径加到系统的Path环境变量里之后无论在哪个目录打开cmd或PowerShell直接敲gdc-client就能运行。具体操作是右键“此电脑” → 属性 → 高级系统设置 → 环境变量在系统变量里找到Path新增一条填上解压目录的完整路径确认后重开终端生效。macOS和Linux的操作类似。我平时主要用Linux服务器比较多做法是把解压目录放到/opt或自己的~/tools下然后在~/.bashrc或~/.zshrc里加一行export PATH/opt/gdc-client/bin:$PATH保存后执行source ~/.bashrcgdc-client命令就能全局使用了。如果你的机器上正好有对外可写的bin目录比如/usr/local/bin把解压出来的gdc-client软链接进去也是常见做法。这里有一个很多人忽略的小坑macOS在新版本上第一次运行gdc-client可能会因为安全策略提示“无法打开因为无法验证开发者”。解决办法是在系统设置的安全与隐私里允许该应用运行或者对可执行文件右键打开一次再允许。这种情况不是工具本身的bug遇到别慌。2.3 验证安装跑通前先确认这一步安装完不要急着下载数据先在终端里确认工具本身没问题gdc-client --version能正常打印出版本号说明安装基本OK。如果提示command not found优先检查环境变量是否配置正确、终端有没有重新加载配置。Windows用户还要注意PowerShell和cmd对当前目录下可执行文件的前缀要求。另外可以顺手看一下帮助文档gdc-client --help gdc-client download --helpdownload子命令的help会列出所有可用参数后面我要讲的参数都在这里面能找到官方解释。养成翻help的习惯比到处问人靠谱得多尤其是当你用的版本和我这篇里的参数有细微出入时以官方help为准最稳妥。3. 下载前必须搞清楚的访问权限与token配置3.1 open access与controlled access的区别很多新手第一次下TCGA数据到token这一步就懵了为什么下载还要登录、还要生成一个“看不懂的文件”这背后其实是TCGA数据的访问分级机制。GDC把数据分成两类open access公开数据和controlled access受控数据。公开数据不需要任何授权比如大多数RNA-seq的表达定量结果、部分临床注释匿名下载就行但体细胞突变中的部分原始文件、涉及个体基因型信息的敏感数据属于受控数据必须先在dbGaP申请对应项目的访问权限权限批下来后才能下载。实操中最常见的情况是你只在portal上筛选了公开数据其实不传token也能下。但加上token也没有坏处GDC-client会用这个身份信息做权限校验。所以我个人的建议是不管是否公开数据都顺手准备好token免得后面换受控数据时再折腾一遍流程。3.2 生成token文件的具体步骤token生成的过程不算复杂但新手容易在细节卡住。完整流程如下。第一步注册GDC账号登录portal.gdc.cancer.gov。注册时按页面要求填写邮箱并完成邮件验证。第二步登录后点击页面右上角的用户名在下拉菜单里找到Developer进入后能看到Auth Token区域。第三步点击Generate Token页面会下载一个txt格式的token文件。文件里是一长串加密字符下载后建议立即改名为token.txt放到你常用的工作目录里避免和别的文件混在一起认不出来。第四步把token文件和manifest放在同一个工作目录后面引用路径会方便很多。token是有有效期的不是永久有效。过期后重新到portal里点一次Generate Token即可。我在实际使用中发现把token生成日期记下来很有用——你很可能隔几个月再下载一批新数据突然报401了才想起来token早就过期了。这里必须提醒一点token文件等同你的下载权限凭证千万别把它提交到git仓库也别随手发给别人。这东西在受控数据场景下能直接读取敏感数据保管级别至少要和自己的密码一致。3.3 manifest批量下载清单是怎么来的manifest是GDC的批量下载清单本质上是一个纯文本TSV表格。第一行是列名后面每一行对应一个待下载文件记录了文件UUID、文件名、md5校验值、大小和状态。GDC-client就是照着这个清单逐条下载的。想拿到manifest还是在portal里操作。先通过左侧筛选条件和搜索框把数据范围定下来比如指定癌症类型TCGA-LUAD文件类型RNA-seq定量结果然后把感兴趣的文件加入Cart购物车Cart右上角的Download Manifest按钮会生成这个清单文件下载到本地就得到manifest.txt。这里有个容易忽略的点manifest里的state列表示文件的可用状态绝大多数情况是released已发布。如果你把文件加入Cart很久以后才下载manifest中间文件状态可能发生变化后续下载时client会针对这些文件报错。所以推荐的做法是确定要下载了再生成manifest不要提前太早。把token、manifest、gdc-client三者准备好下载的前置条件就齐了。4. 真正跑起来GDC-client常用参数与批量下载实战4.1 一次完整的TCGA-LUAD表达数据下载示例以我最近做的一个具体场景为例我要下载TCGA-LUAD肺腺癌的转录组表达定量数据准备做后续的差异基因分析。在portal上筛选时的条件大致是Cases里选Lung AdenocarcinomaFiles里的Data Category选Transcriptome ProfilingData Type选Gene Expression QuantificationExperimental Strategy选RNA-SeqWorkflow Type选STAR-Counts。这里特别说一下workflow type的选择。TCGA早期转录组定量用的是HTSeq-Counts流程后来GDC切换到STAR流程新下载的数据建议优先选STAR-Counts作为统一表达定量来源。如果你要对比不同批次数据尽量只用一种workflow混用不同定量流程会导致表达量不可比这个坑我在实际分析里踩过。筛选完成后把所有文件加入CartDownload Manifest得到manifest.txt。我的工作目录是/data/tcga_luad/里面已经有manifest和token/data/tcga_luad/ ├── manifest.txt └── token.txt然后执行下载命令gdc-client download -m manifest.txt -t token.txt -d /data/tcga_luad/解释一下参数-m后面跟manifest文件-t后面跟token文件-d指定数据输出的目录如果不加-d文件默认下载到当前命令行所在目录。跑起来之后终端会持续打印每个文件的下载进度文件名、大小、完成百分比。整个过程基本不需要人工干预等它跑完就行。我下载过一批约300个RNA-seq counts文件平均每个几十MB在稳定带宽下一次跑完大概十几分钟到半小时具体时间跟网络状态关系很大。4.2 并发数、断点续传和日志监控当文件多、体量大的时候有几个参数值得花时间调。-n / --n-processes指定并发下载进程数。我第一次用的时候直接把并发开到32想着越快越好结果服务器疯狂弹连接错误后来发现是并发过高被对方限流了。经验值是8到16之间比较稳妥带宽普通的话8就够用。如果你只有几个大文件并发开小一点2到4就能跑满带宽如果几百个小文件并发可以适当开大。断点续传是GDC-client最大的加分项。下载到一半比如网络断了或者你得关机下班了直接让它退出下次再执行同一条命令它会自动检查目录里已有的文件已完成的跳过只补剩余的部分。不需要任何特殊设置这是默认行为。续传有一个前提下一次命令的-d参数必须和上次一致而且不要把之前下载完的文件挪走或改名否则一致性判断会失效。大批量下载时建议把日志落到文件里再用后台方式运行gdc-client download -m manifest.txt -t token.txt -d /data/tcga_luad/ -n 8 --log-file download.log 21 加一个放到后台用tail盯着日志tail -f download.log这样即使终端意外断开下载进程在服务器上一般还活着前提是用了nohup或tmux/screen会话日志能帮你确认到底跑到哪里了。下载结束后可以grep一下错误信息快速定位出问题的文件grep -i error download.log4.3 下载完成后目录里是什么样的GDC-client下载完成后的目录结构通常长这样/data/tcga_luad/ ├── 2f8e0d3f-xxxx-xxxx-xxxx-xxxxxxxxxxxx/ │ └── TCGA-XX-XXXX-01A-01R-XXXX-XX-STAR-Counts.txt.gz ├── b7c1a2a4-xxxx-xxxx-xxxx-xxxxxxxxxxxx/ │ └── TCGA-XX-XXXX-01A-01R-XXXX-XX-STAR-Counts.txt.gz每个文件都躺在以文件UUID命名的子目录里。为什么要这样组织因为GDC内部用UUID保证文件的全局唯一性重名文件也能区分开。但这个结构对下游分析不友好所以下载完通常要花一步来做目录整理具体方法我在第6章重点讲。这里顺带提一下TCGA样本barcode的阅读方法文件名里的TCGA-XX-XXXX-01A-01R-XXXX-XX其实是样本的唯一标识-01代表原发肿瘤-11代表实体组织正常样本-02是复发-03是转移。分组分析时判断肿瘤/正常样本主要看的就是这个位置。很多新手在这上面吃亏把肿瘤样本和正常样本归错组分析结论直接报废。5. 实测中的高频报错与排查思路5.1 401 Unauthorized先怀疑token再怀疑权限GDC-client最经典的报错就是401 Unauthorized。接到这个报错90%的可能是token出了问题要么token有效期过了要么你的受控数据访问权限还没批下来要么token文件路径填错了。我踩过的一个真实例子用旧token下载之前拿到的受控数据结果报401我以为网络问题折腾了二十分钟查配置最后才发现token是两个月前生成的早就过期了。重新生成token后一切正常。所以看到401第一件事就是重新登录portal重新Generate Token再用新token重试一次。这一步能解决绝大多数情况。如果换了新token还是401那就要考虑是不是数据权限本身没有被批准。受控数据的权限需要去dbGaP提交申请批准后才生效。在portal的文件详情页可以看你的访问级别符不符合该文件的访问要求。5.2 网络超时、连接中断与重试策略GDC服务器端链路复杂、高峰时段带宽波动明显所以超时和连接中断属于高频问题尤其是数据量大、持续时间长的下载任务。典型表现是报错Connection reset或者某个文件长时间卡在进度条不动。我的处理经验分几步走。先确认是不是偶发问题直接对目标接口做一次连通性测试看地址是否可达、响应是否正常。如果只是偶尔卡一下client自身的重试逻辑一般能兜住不用额外操作。再调整并发参数把-n从16调低到8甚至4减小瞬时连接压力给每条连接更多带宽余量。还有重试参数GDC-client对单个文件本身有重试逻辑也可以用--retry-amount参数调大重试次数比如设成10给网络波动更多缓冲空间。如果是在公司或学校的受管网络环境里还需要考虑网络策略是否限制了目标域名的持续大流量传输。这种属于环境层面的限制找网络管理员确认白名单或调整网络策略往往比在客户端里反复调参数更高效。整个下载过程中最重要的心态是已经跑起来的任务不要轻易杀掉重来。断点续传会帮你跳过已完成的部分贸然杀掉反而可能让已经写入临时文件的那点进度作废。5.3 manifest文件状态异常与磁盘空间不够manifest里的文件不会永远可用。有些数据因为样本撤回或数据审核会被标记为withdrawn状态。如果你拿着旧manifest去下载GDC-client会针对这部分文件报状态错误但其它正常文件不受影响会继续下载。这类问题的根源通常是manifest生成时间和实际下载时间隔得太久。解决办法是回到portal重新生成一份最新manifest如果只是想取某个文件也可以直接在portal里定位后单独下载。我个人的习惯是只要本次下载的数据量不是特别大就重新生成一次manifest确保数据版本一致。另一个看起来直白但很容易栽跟头的报错是No space left on deviceTCGA批量下载的总大小在开始前很难精确估算。你盯着manifest里几百个文件时虽然size列标了每个文件的大小但人不会去心算总和。建议下载前用du和df确认目标磁盘剩余空间再用命令把manifest的size列加一下估算总大小心里有数再动手。我现在的习惯是给每个下载任务单独规划一个磁盘空间充裕的目录下载过程中定期df -h看剩余空间避免数据下到一半卡死。尤其当你把下载目录放在根分区、而根分区本身只有几十GB剩余的时候这个检查能帮你避免很多麻烦。6. 下载完之后数据校验、重命名与下游分析接入6.1 用md5再确认一遍文件完整性GDC-client在下载过程中已经默认做了分段md5校验正常情况下不需要你再额外验证。但如果你要把数据拷贝到别的机器或者下载过程网络状况差到让你怀疑人生手动校验一遍其实很快。manifest文件里每一行都带有对应文件的md5值可以用md5sumLinux/macOS或Get-FileHashPowerShell批量比对。我在Linux下一般写一个简单循环来处理示意如下while read -r id fname md5 size state; do if [ $state released ]; then actual$(md5sum $fname | awk {print $1}) [ $actual $md5 ] echo OK $fname || echo MISMATCH $fname fi done manifest.txt注意这只是一个示意脚本实际manifest的表头和字段顺序要先看一眼再套用。比对逻辑很简单本地算出的md5和manifest记录的md5一致说明文件完整不一致说明文件损坏或下载过程有问题单独重新下载这个文件就好。6.2 把UUID目录整理成可读样本名下载完成后的UUID目录结构虽然保证文件不重名但人类看不友好。真正做分析时你需要用文件名里的样本barcode去对应样本信息而不是用UUID。所以建议下载完成后做一步“重命名整理”把真实文件名提取出来统一放到一个新的扁平目录里。这一步用一段简单的Python脚本就能完成import os import shutil manifest manifest.txt src_dir /data/tcga_luad dst_dir /data/tcga_luad/renamed os.makedirs(dst_dir, exist_okTrue) with open(manifest) as f: lines f.readlines() for line in lines[1:]: uuid line.strip().split(\t)[0] fname line.strip().split(\t)[1] src os.path.join(src_dir, uuid, fname) if os.path.exists(src): shutil.copy(src, os.path.join(dst_dir, fname)) print(copied, fname)建议用复制而不是移动等确信新目录里的文件都正常了再删原目录这样中间出问题还能回溯。把文件集中到一个目录后后续读入R或Python做表达矩阵构建都会方便很多。6.3 从下载数据到差异分析的衔接数据整理好之后常见的研究线路大概有三条。第一条针对RNA-seq表达定量文件不管是STAR-Counts还是HTSeq-Counts下游通常是DESeq2或edgeR做差异基因分析。Counts文件对应基因水平的原始read count做差异分析时直接在R里读入、构建样本分组矩阵即可。如果你下载的是TPM或FPKM版本虽然也可以做差异筛选但通常不建议直接替代counts输入给DESeq2因为这类工具内置的离散分布模型默认输入是整数count。第二条针对体细胞突变数据常见的下游工具是maftools可以直接读入突变注释格式做瀑布图、突变类型统计、驱动基因富集等可视化。第三条做临床关联分析。下载数据时我强烈建议顺手把同批样本的临床信息Clinical Supplement一起下载。因为后面做分组对比时几乎必然要用到生存状态、分期、亚型等临床字段。手上没有这份信息就只能回portal重新筛选一遍来回折腾非常浪费时间。从工具链路来看TCGAbiolinks这个R包也能完成数据下载和sample对齐方便的地方在于自动把表达量与临床注释合并成一个对象。但如果你已经用GDC-client把数据拉下来了继续用TCGAbiolinks只做下游分析也是完全可以的两条路并不冲突。根据个人使用经验我再说最后一点下载TCGA数据时养成记录的习惯很值当。每次下载的manifest、token生成日期、portal筛选条件、数据版本都随手存在下载目录的说明文件里。过几个月你再回来看这批数据就知道当时选的是什么条件、文件对应哪个数据库版本不用重新推演一遍。GDC-client说到底只是个传输工具真正决定数据后续价值的是你下载前想清楚要什么、下载后把数据管理成什么样。把这个流程跑顺后面分析才会省心。