idc-index 命令行下载工具实战从 manifest 到 s5cmd 断点续传无代码下载 NCI IDC 癌症影像数据【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills本文基于 imaging-data-commons 技能的 CLI 指南 展开系统讲解idc-index包提供的三个命令行工具——idc download、idc download-from-manifest、idc download-from-selection——的安装前提、参数语义、manifest 文件格式与断点续传机制。读完后你将能在不写一行 Python 代码的情况下按集合、按 UID、按 manifest 或按组合过滤条件把 NCI Imaging Data CommonsIDC的 DICOM 数据完整、可恢复地下载到本地并懂得用 dry-run 在真正占用磁盘前估算下载规模。一、前提idc-index 的安装与版本校验idc-index是 IDC 官方 Python 包安装后终端中会多出一个idc命令本文的三个子命令均由它提供。该技能规定的标准安装校验方式是运行随技能分发的 check_version.pypython scripts/check_version.py脚本会报告当前解释器下已安装的idc-index版本并在版本不满足要求时打印针对当前解释器的安装命令。当前技能锁定的最低版本是0.12.5对应的 IDC 数据版本为v24见 SKILL.md 的 frontmattermetadata.idc-index: 0.12.5、metadata.idc-data-version: v24。从 check_version.py 的源码结构看这个校验脚本有几个值得注意的设计它从不自己安装或升级任何包。当idc_index模块缺失或版本低于MIN_VERSION时脚本打印安装命令并以非零状态码退出把环境选择权留给调用者安装命令总是显式指向运行脚本的解释器sys.executable且系统存在uv时优先给出uv pip install --python 解释器 ...否则退回到解释器 -m pip install ...避免装进 PATH 上另一个无关的 Python 环境两种命令形式都会尊重 PEP 668 的 externally-managed 守卫——在受管系统 Python 上安装会被拒绝脚本明确提示应使用虚拟环境或--user网络可达时脚本还会顺带检查 PyPI 上的idc-index与技能仓库是否有新版本仅做提示、不自动更新。这个只报不装的原则与 SKILL.md 的整体路由策略一致如果任务只需要只读元数据计数、属性值、授权查询技能建议直接用 REST API 而不安装idc-index因为安装要付出约 77 MB 打包索引数据以及 pandas、pyarrow、duckdb 等依赖的代价。只有需要真正移动图像字节下载文件时才值得安装——而安装之后命令行就是免代码下载的最直接入口。二、idc download输入类型自动识别的通用下载命令idc download是三个命令中最通用的一个。它智能解释传入的参数自动判断输入到底是manifest 文件路径还是一组标识符列表——标识符可以是collection_id集合、PatientID患者、StudyInstanceUID研究、SeriesInstanceUID系列或crdc_series_uuidCRDC 系列 UUID。用法示例# 下载整个集合 idc download rider_pilot --download-dir ./data # 按 UID 下载特定系列 idc download 1.3.6.1.4.1.9328.50.1.69736 --download-dir ./data # 下载多个条目逗号分隔 idc download tcga_luad,tcga_lusc --download-dir ./data # 从 manifest 文件下载按文件扩展名自动识别 idc download manifest.txt --download-dir ./data选项选项说明--download-dir目标目录默认当前目录--dir-template目录层级模板默认%collection_id/%PatientID/%StudyInstanceUID/%Modality_%SeriesInstanceUID--log-level日志级别debug, info, warning, error, critical目录模板变量--dir-template决定下载文件在磁盘上的组织方式模板中可用的变量有五个%collection_id—— 集合标识符%PatientID—— 患者标识符%StudyInstanceUID—— 研究 UID%SeriesInstanceUID—— 系列 UID%Modality—— 影像模态CT、MR、PT 等# 扁平结构所有文件放在同一目录 idc download rider_pilot --download-dir ./data --dir-template # 简化层级省略 StudyInstanceUID 层 idc download rider_pilot --download-dir ./data --dir-template %collection_id/%PatientID/%Modality同一套模板在 Python API 中同样适用参数名是dirTemplate而非--dir-template标志默认值相同%collection_id/%PatientID/%StudyInstanceUID/%Modality_%SeriesInstanceUID。例如# 简化层级省略 StudyInstanceUID 层 client.download_from_selection( downloadDir./data, collection_idtcga_luad, dirTemplate%collection_id/%PatientID/%Modality ) # 结果./data/tcga_luad/TCGA-05-4244/CT/ # dirTemplate 禁用层级所有文件直接写入 downloadDir值得强调的是可复现性SKILL.md 的最佳实践明确要求用dirTemplate组织下载如%collection_id/%PatientID/%Modality并保存你所构建数据集背后的 Series UID 列表或 manifest。目录层级本身就是数据集血缘的一部分。三、idc download-from-manifest带校验、进度与断点续传的 manifest 下载idc download-from-manifest专攻 manifest 文件下载内置 manifest 校验、进度追踪与断点续传能力适合大规模队列cohort下载场景。用法示例# 基础 manifest 下载 idc download-from-manifest --manifest-file cohort.txt --download-dir ./data # 带进度条与校验 idc download-from-manifest --manifest-file cohort.txt --download-dir ./data --show-progress-bar # 使用 s5cmd sync 恢复中断的下载 idc download-from-manifest --manifest-file cohort.txt --download-dir ./data --use-s5cmd-sync选项选项说明--manifest-file必填。包含 S3 URL 的 manifest 文件路径--download-dir必填。目标目录--validate-manifest下载前校验 manifest默认启用--show-progress-bar显示下载进度--use-s5cmd-sync启用可恢复下载——跳过已下载的文件--quiet抑制子进程输出--dir-template目录层级模板--log-level日志详细程度manifest 文件格式manifest 文件每行一个 S3 URLs3://idc-open-data/cb09464a-c5cc-4428-9339-d7fa87cfe837/* s3://idc-open-data/88f3990d-bdef-49cd-9b2b-4787767240f2/*这里有两个底层细节读 REST API 指南 后可以确认manifest 中的路径是 CRDC UUID 而非 DICOM UID。IDC 的所有 DICOM 文件存放在 AWS S3 与 GCS 镜像的公开桶中按crdc_series_uuid/crdc_instance_uuid.dcm组织见 云存储指南。用 CRDC UUID 做路径是为了支持版本管理同一 DICOM 系列内容变更后会被分配新的 CRDC UUID旧 UUID 路径保持可访问。因此下载同一个SeriesInstanceUID在不同 IDC 版本可能对应不同的 manifest 行——把 manifest 存下来就是保存了数据的确切版本快照该命令只识别s3://行。从源码与文档描述看download-from-manifest并不是简单地把 URL 交给传输客户端它会从 manifest 中抽取每个crdc_series_uuid与本地索引再退回prior_versions_index做连接以计算大小并构建输出目录层级。因此 manifest 中的 URL 必须指向 S3 兼容端点gs://行不会被识别——GCS 与 S3 的路径结构相同但命令本身以s3://为准。如何获取 manifest 文件指南给出了两条获取路径IDC Portal在浏览器端构建队列后导出 manifest注意 SKILL.md 强调 Portal 是纯交互式的不应出现在任何脚本化流程中用 Python 查询生成从 SQL 结果中取出series_aws_url列写盘from idc_index import IDCClient client IDCClient() results client.sql_query( SELECT series_aws_url FROM index WHERE collection_id rider_pilot AND Modality CT ) with open(ct_manifest.txt, w) as f: for url in results[series_aws_url]: f.write(url \n)index表中series_aws_url列的值形如s3://idc-open-data/crdc_series_uuid/*指向整个系列文件夹——这正是上面 manifest 示例中/*通配符的由来。另外 REST API 指南 也提供了零安装的替代方案POST /v3/cohort/manifest.txt返回text/plain每行一个s3://…/*URL可以直接重定向保存后用idc download-from-manifest消费整条查询 → manifest → CLI 下载链路不依赖本地索引。四、idc download-from-selection按过滤条件组合下载idc download-from-selection让你直接用过滤条件驱动下载多个过滤条件按顺序叠加应用AND 语义。用法示例# 按集合下载 idc download-from-selection --collection-id rider_pilot --download-dir ./data # 按特定系列下载 idc download-from-selection --series-instance-uid 1.3.6.1.4.1.9328.50.1.69736 --download-dir ./data # 多个过滤条件组合 idc download-from-selection --collection-id nlst --patient-id 100004 --download-dir ./data # 试运行——先看看会下载什么而不实际下载 idc download-from-selection --collection-id tcga_luad --dry-run --download-dir ./data选项选项说明--download-dir必填。目标目录--collection-id按集合标识符过滤--patient-id按患者标识符过滤--study-instance-uid按研究 UID 过滤--series-instance-uid按系列 UID 过滤--crdc-series-uuid按 CRDC UUID 过滤--dry-run只计算队列规模不下载--show-progress-bar显示下载进度--use-s5cmd-sync启用可恢复下载--dir-template目录层级模板注意过滤条件的粒度与 IDC 数据模型一一对应collection_id是 IDC 在标准 DICOM 层级Patient → Study → Series → Instance之上新增的分组维度按疾病/模态/研究主题归组患者如tcga_luad、nlstPatientID、StudyInstanceUID、SeriesInstanceUID则是标准 DICOM 标识符见 SKILL.md 的IDC Data Model一节。五个过滤参数覆盖了从粗到细的全部层级。用--dry-run估算下载规模在提交一个可能达到 TB 级的下载之前先用--dry-run摸底idc download-from-selection --collection-id nlst --dry-run --download-dir ./data试运行会输出匹配过滤条件的系列数量预计总下载大小不下载任何文件这与 SKILL.md 中先小后大explore small, then commit的最佳实践呼应——部分集合collection的体量是 TB 级的盲下既浪费磁盘也可能触发下载失败。五、四个常见工作流原文档整理了四套组合打法覆盖了从测试到大规模生产的典型场景。工作流 1下载小集合做测试# rider_pilot 约 1GB适合测试 idc download rider_pilot --download-dir ./test_data工作流 2大数据集——进度条 断点续传# 大下载使用 s5cmd sync——中断后可恢复 idc download-from-selection \ --collection-id nlst \ --download-dir ./nlst_data \ --show-progress-bar \ --use-s5cmd-sync--use-s5cmd-sync是这条工作流的关键下载走 s5cmd 的 sync 模式跳过已存在的文件因此中断后重跑同一命令即可从断点继续而不是从头再来。idc-index内部本就使用 s5cmd 从这些 S3 桶做传输见 云存储指南该标志等于把底层的续传能力直接暴露给命令行。工作流 3先估算后下载# 先查规模 idc download-from-selection --collection-id tcga_luad --dry-run --download-dir ./data # 规模可接受再真正下载 idc download-from-selection --collection-id tcga_luad --download-dir ./data工作流 4Python 查询 CLI 下载按模态筛选这是跨语言协作的典型模式——精细过滤模态 解剖部位用 Python 的 SQL 表达力强下载则交给 CLI 的并发与续传能力# 第一步Python 中查询目标系列 UID from idc_index import IDCClient client IDCClient() results client.sql_query( SELECT SeriesInstanceUID FROM index WHERE collection_id nlst AND Modality CT AND BodyPartExamined CHEST LIMIT 50 ) # 存成 manifest results[SeriesInstanceUID].to_csv(my_series.csv, indexFalse, headerFalse)# 第二步CLI 下载逗号分隔的标识符列表会被自动识别 idc download my_series.csv --download-dir ./lung_ct注意第二步利用的正是idc download的输入自动识别能力CSV 中没有 S3 前缀的内容会被当作标识符列表处理。这里也再次印证前文的原则——Modality、BodyPartExamined这类过滤值应先枚举真实取值再写进条件猜测字符串是空结果集的最常见原因。六、内置安全机制CLI 内置了四道安全防线均无需额外配置磁盘空间检查开始下载前验证剩余空间是否足够manifest 校验默认在下载前校验 manifest 文件格式进度追踪可选进度条便于监控大文件下载断点续传--use-s5cmd-sync让中断的下载可以跳过已下载文件继续。七、故障排查下载中断用--use-s5cmd-sync重跑即可恢复idc download-from-manifest --manifest-file cohort.txt --download-dir ./data --use-s5cmd-sync连接超时网络不稳时建议拆小批量下载用 Python 把队列拆分成多个 manifest 文件再顺序下载。这与 SKILL.md 排障章节按 10–20 个系列一批的建议一致。另外两条来自仓库文档的补充提示如果下载回来的文件名crdc_instance_uuid.dcm对不上你预期的系列多半是该系列在更新的 IDC 版本中被修订、CRDC UUID 变了——用prior_versions_index比对历史路径见 云存储指南 的版本化一节下载的文件若打不开先检查Modality与SOPClassUIDSEG、RTSTRUCT、SR 与病理切片都不是普通 CT/MR 视图器能处理的对象类型。八、延伸参考本文对应的完整文档与同技能的其他参考指南均位于仓库内可直接查阅cli_guide.md —— 本文所基于的 CLI 指南原文SKILL.md —— 技能总入口访问路径路由、IDC 数据模型、核心 API 模式、最佳实践与排障cloud_storage_guide.md —— 桶组织、CRDC UUID 版本化、s5cmd/gsutil 直连rest_api_guide.md —— 零安装获取 cohort manifest 的 REST 路径/v3/cohort/manifest.txtsql_patterns.md —— 过滤值发现、大小估算等 SQL 模式check_version.py —— 版本校验脚本源码适用前提小结文中命令均要求idc-index技能锁定 0.12.5数据版本 v24已安装下载目标为 IDC 公开桶S3/GCS无需任何认证manifest 路径必须为s3://形式download-from-selection的过滤字段对应本地索引若本地索引落后于线上数据版本个别系列会被静默跳过——此时先运行check_version.py按提示升级。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考