🧩核心概念：对象、项目与引用

在深入命令之前，理解DNAnexus的核心数据模型至关重要。这不是可选的理论课——如果你不理解这三个概念，每一条dx命令都会让你困惑。

🧩 DNAnexus 三大核心概念

1. 对象（Object）——平台上的所有实体都是对象。每个对象有一个唯一不可变的ID，格式为类型-xxxx：

  • project-xxxx——项目
  • file-xxxx——文件
  • job-xxxx——作业
  • applet-xxxx——应用
  • record-xxxx——记录

2. 项目（Project）——权限边界和数据组织单元。所有操作都在某个项目上下文中进行。项目之间通过ID可以实现跨项目访问。

3. 引用（Reference）——通过对象ID而非路径引用数据，确保不可变性和可重复性。

对象引用语法

DNAnexus有三种引用方式，理解它们的区别是构建自动化脚本的基础：

# 1. 跨项目绝对路径引用 project-BQpp3Y804Y0xbyG4GJPQ01xv:/C. Elegans/ce10.fasta.gz # 2. 基于作业输出的对象引用（链式引用的核心） job-xxxx:sorted_bam # 3. JSON格式的结构化引用（用于API调用） {"$dnanexus_link": "file-xxxx"}

第一种用于直接访问已知路径的文件。第二种是自动化的关键——你可以引用一个尚未完成的作业的输出，系统会自动建立依赖关系。第三种在编写dx-app或直接调用API时使用。

不可变性原则

DNAnexus上的数据对象是不可变的（immutable）——它们只能被创建或删除，不能被覆盖。同一个项目里上传两个同名文件不会覆盖，而是创建两个独立对象各有独立ID。这不是bug，是设计：不可变性保证了分析的可重复性——同一个对象ID永远指向同一组字节。

🔐安装与身份认证

安装dx-toolkit

dx CLI是dx-toolkit的一部分。安装方式取决于你的环境：

# 通过pip安装（推荐Python 3环境） pip install dxpy # 升级 pip install --upgrade dxpy # 验证安装 dx --version # DNAnexus Command-Line Client, API v1.0.0, client v0.394.0

登录与会话管理

# 交互式登录 $ dx login Acquiring credentials from https://auth.dnanexus.com Username: <your username> Password: <your password> # 使用认证令牌登录（适合自动化脚本） $ dx login --token <YOUR_TOKEN> # 设置会话超时（秒），默认7天 $ dx login --timeout 3600 # 查看当前身份 $ dx whoami # 查看当前环境 $ dx env # 登出（会使令牌失效） $ dx logout
🔐 认证最佳实践

令牌管理：在DNAnexus平台UI中生成认证令牌（Settings → API Keys），而非在脚本中硬编码用户名密码。令牌可以设置过期时间和权限范围。

自动化场景：使用DX_SECURITY_CONTEXT环境变量传递令牌，避免在命令行参数中暴露：

export DX_SECURITY_CONTEXT='{"auth_token":"YOUR_TOKEN"}' dx ls

多账号切换：使用--env-help查看可覆盖的环境变量，在不同项目/账号间切换。

📁项目导航与数据探查

选择项目

登录后需要选择一个工作项目——这是所有后续操作的上下文。dx select是切换工作空间的核心命令：

# 交互式选择（列出你有权限的项目） $ dx select # 按名称选择 $ dx select "My Research Project" # 按项目ID选择 $ dx select project-BQpp3Y804Y0xbyG4GJPQ01xv # 选择公共参考基因组项目 $ dx select --public --name "Reference Genome Files*" # 只显示有ADMINISTER权限的项目 $ dx select --level ADMINISTER

目录操作

# 查看当前工作目录 $ dx pwd # output: project-Bxxxx (/) # 列出目录内容 $ dx ls # 长格式列表（显示ID、大小、修改时间） $ dx ls -l # 列出指定目录 $ dx ls /data/fastq # 通配符过滤——必须加引号！ $ dx ls "*.fastq" # 切换目录 $ dx cd /data $ dx cd / # 回到根目录 # 创建目录 $ dx mkdir results # 树状显示项目结构 $ dx tree $ dx tree -l # 长格式
⚠️ 通配符陷阱

使用通配符（*或?）时必须用引号包裹。否则Shell会在传递给dx之前先行展开，导致意外结果或"file not found"错误。

正确：dx ls "*.fastq"

错误：dx ls *.fastq（Shell会先在本地目录展开）

跨项目访问

你不需要切换项目就能查看其他项目的内容——使用项目ID:路径语法即可：

# 列出公共参考基因组项目的内容 $ dx ls "project-BQpp3Y804Y0xbyG4GJPQ01xv:/" # 描述另一个项目中的文件 $ dx describe "project-BQpp3Y804Y0xbyG4GJPQ01xv:/H. Sapiens - GRCh38/hs38DH.fasta.gz"

文件操作：cp、mv、rm

# 从公共项目复制文件到当前项目 $ dx cp "project-BQpp3Y804Y0xbyG4GJPQ01xv:/H. Sapiens - GRCh38/hs38DH.dict" / # 移动/重命名文件（文件ID不变，只改元数据） $ dx mv hello.txt goodbye.txt $ dx mv goodbye.txt /data/hello.txt # 删除文件（用ID最安全，因为文件名不唯一） $ dx rm file-GXZB2180fF65j2G1197pP7By # 删除目录 $ dx rmdir /old_results
💡 同区域复制不产生额外存储费

使用dx cp在同一区域的两个项目间复制文件时，平台不会物理复制数据——它只创建一个新的数据库条目指向同一组字节。这意味着不产生额外存储费用。跨区域复制则会物理拷贝数据并产生费用。

使用dx describe <project-id>查看项目的"Region"属性确认区域。

📤数据上传与下载

上传

# 基本上传 $ dx upload sample.fastq # 等待上传完成并返回完整描述（交互式） $ dx upload --wait sample.fastq # 简洁模式——只返回文件ID（适合脚本） $ file_id=$(dx upload sample.fastq --brief) $ echo "Uploaded file ID: $file_id" # 上传到指定路径 $ dx upload sample.fastq --path /data/fastq/ # 递归上传目录 $ dx upload -r ./my_data/ # 上传时设置属性 $ dx upload sample.fastq --property species=human --property batch=run01

下载

# 下载文件（保留云端文件名） $ dx download file-xxxx # 指定本地输出路径 $ dx download file-xxxx -o /local/path/output.bam # 强制覆盖本地已有文件 $ dx download file-xxxx -f --no-progress # 下载作业输出 $ dx download job-xxxx:sorted_bam -o results.bam

快速查看文件内容

# 查看文件头部（默认10行） $ dx head sample.fastq # 查看前12行（FASTQ的前3条read） $ dx head -n 12 sample.fastq # 输出整个文件内容（类似Unix cat） $ dx cat hello.txt
📤 大文件传输：使用Upload Agent

对于大规模文件传输（GB级或批量文件），建议使用Upload Agent（UA）而非dx upload。UA支持：

  • 多线程并行上传
  • 自动压缩
  • 断点续传
  • 批量文件传输

传输效率比基础dx upload提升数倍。详见DNAnexus官方文档的Upload Agent章节。

🔍对象元数据：describe与find

dx describe——查看对象详情

dx describe是理解任何对象属性的关键命令。它返回对象的完整元数据：

# 描述文件对象 $ dx describe file-xxxx ID file-xxxx Class file Project project-Bxxxx Name ce10.fasta.gz State closed Size 29.21 MB Created 2024-01-15 10:32 UTC # JSON格式输出（适合脚本解析） $ dx describe file-xxxx --json # 自定义分隔符输出 $ dx describe file-xxxx --delim "," # 描述项目 $ dx describe project-Bxxxx # 描述作业 $ dx describe job-xxxx

dx find——搜索平台实体

dx find是一个强大的搜索命令，可以搜索多种实体类型：

# 搜索当前项目中的数据对象 $ dx find data # 按名称搜索 $ dx find data --name "sample*" # 按通配符搜索（注意引号） $ dx find data --name "*.bam" # 按属性搜索 $ dx find data --property species=human # 按标签搜索 $ dx find data --tag processed # 搜索作业历史 $ dx find jobs # 按状态搜索作业 $ dx find jobs --state failed # 搜索可用应用 $ dx find apps # 搜索项目 $ dx find projects --name "UKB*"
🔍 元数据应用策略
元数据类型 用途 设置方式
Properties 键值对形式的实验元数据（物种、样本ID、批次） dx set_properties file-xxxx species=human
Tags 快速筛选和分类对象 dx tag file-xxxx processed
State closed=上传完成，open=正在写入 上传完成后自动变为closed

⚙️作业管理：run、watch、wait

DX CLI的核心价值在于程序化地执行分析作业。理解作业的生命周期是管理复杂分析流的基础。

dx run——启动作业

# 交互式运行（提示输入参数） $ dx run bwa_mem # 直接指定所有参数 $ dx run bwa_mem \ -ireads="sample.fastq" \ -igenomeindex_targz="project-BQpp:/H. Sapiens - GRCh38/bwa.tar.gz" \ --yes # 简洁模式——只返回作业ID（适合脚本） $ job_id=$(dx run bwa_mem -ireads=sample.fastq -y --brief) # 查看应用帮助（了解输入参数名） $ dx run freebayes -h # 安装应用（类似书签功能） $ dx install bwa_mem
⚙️ dx run 参数规范

输入参数前缀取决于参数类型：

  • -i——普通输入（文件、字符串、数字）
  • -is——字符串类型输入
  • -ia——数组类型输入
  • -ib——布尔类型输入

使用dx run <app> -h查看某个应用的完整参数列表。方括号[]表示可选参数。

关键标志：

  • -y / --yes——跳过确认提示，适合脚本
  • --brief——只返回作业ID
  • --watch——启动后立即监控日志
  • --allow-ssh——允许SSH进入作业节点

作业生命周期管理

📋 作业管理命令速查
命令 功能 典型场景
dx run 启动作业/应用 执行BWA比对、变异检测
dx watch 实时跟踪日志 监控长作业进度，查看STDERR
dx describe job-xxxx 查看作业详情 检查状态、输入输出、耗时
dx find jobs 检索作业历史 审计分析流程，查找失败作业
dx terminate 终止运行中作业 取消错误配置的作业以节省成本
dx wait 等待作业完成 串联依赖作业，实现自动化

作业状态流转

# 作业状态流转： # pending → running → done (成功) # pending → running → failed (失败) # pending → running → terminated (手动终止) # pending → waiting_on_input → ... (链式引用依赖) # 实时监控作业日志 $ dx watch job-xxxx # 等待作业完成（阻塞式） $ dx wait job-xxxx # 终止运行中的作业 $ dx terminate job-xxxx # 查看项目所有作业 $ dx find jobs --project project-Bxxxx # 只看失败的作业 $ dx find jobs --state failed

🔗链式引用：构建自动化流水线

DNAnexus最强大的特性是作业链式引用（Job-based Object Reference）。通过job-ID:output_field语法，可以将上游作业的输出直接作为下游作业的输入——无需等待中间文件落地。系统自动处理依赖关系，确保下游作业在上游完成后才启动。

流水线执行逻辑

🔗 自动化流水线

上传FASTQ → BWA比对 → FreeBayes变异检测 → 下载VCF结果

完整自动化脚本示例

以下是一个完整的端到端自动化流水线脚本——从上传FASTQ到下载VCF，全程无需人工干预：

#!/usr/bin/env bash set -euo pipefail # ============================================ # DNAnexus 自动化分析流水线 # FASTQ → BWA比对 → FreeBayes变异检测 → VCF下载 # ============================================ # 1. 上传FASTQ文件，获取文件ID echo "Uploading FASTQ..." READS_ID=$(dx upload sample.fastq --brief) echo " File ID: $READS_ID" # 2. 启动BWA比对作业 echo "Launching BWA-MEM job..." BWA_JOB=$(dx run bwa_mem \ -ireads="$READS_ID" \ -igenomeindex_targz="project-BQpp:/H. Sapiens - GRCh38/bwa.tar.gz" \ -y --brief) echo " Job ID: $BWA_JOB" # 3. 用链式引用启动FreeBayes——无需等待BWA完成 # 系统会自动建立依赖，FreeBayes在BWA完成后才启动 echo "Launching FreeBayes job (chained)..." FREEBAYES_JOB=$(dx run freebayes \ -isorted_bams="$BWA_JOB:sorted_bam" \ -igenome_fastagz="project-BQpp:/H. Sapiens - GRCh38/hs38DH.fasta.gz" \ -y --brief) echo " Job ID: $FREEBAYES_JOB" # 4. 等待最终作业完成 echo "Waiting for FreeBayes to complete..." dx wait "$FREEBAYES_JOB" # 5. 下载结果 echo "Downloading results..." dx download "$FREEBAYES_JOB:variants_vcfgz" -o results.vcf.gz -f echo "Pipeline complete! Results: results.vcf.gz"
💡 链式引用的核心优势

1. 自动依赖管理：系统自动建立作业依赖图。FreeBayes作业在BWA完成前处于"waiting for input"状态——不消耗计算资源。

2. 无中间文件落地：BWA的输出BAM文件不需要下载到本地再上传给FreeBayes。数据在云端直接传递，节省时间和带宽。

3. 可重复性：由于对象不可变，同样的输入+同样的应用=同样的输出。DNAnexus甚至支持smart reuse——如果你再次运行相同的作业，系统会直接返回之前的结果而不重新计算。

4. 错误隔离：如果BWA失败，FreeBayes作业会自动标记为terminated，不会浪费计算资源。

进阶：多分支流水线

# 一个BWA作业的输出可以同时喂给多个下游作业 BWA_JOB=$(dx run bwa_mem -ireads=$READS_ID -y --brief) # 分支1：变异检测 FREEBAYES_JOB=$(dx run freebayes -isorted_bams="$BWA_JOB:sorted_bam" -y --brief) # 分支2：深度统计 SAMTOOLS_JOB=$(dx run samtools_depth -ibam="$BWA_JOB:sorted_bam" -y --brief) # 两个分支并行执行，互不阻塞 dx wait $FREEBAYES_JOB dx wait $SAMTOOLS_JOB

📊完整命令速查表

📋 DX CLI 命令分类速查
分类 命令 功能
认证 dx login 登录平台
dx logout 登出（令牌失效）
dx whoami 查看当前用户
dx env 查看当前环境配置
项目 dx select 选择/切换项目
dx new project 创建新项目
dx invite 邀请用户加入项目
dx uninvite 撤销用户访问权限
dx pwd 查看当前工作目录
数据 dx ls 列出目录内容
dx cd 切换目录
dx mkdir 创建目录
dx cp 跨项目复制
dx mv 移动/重命名
dx rm / dx rmdir 删除文件/目录
dx tree 树状显示结构
传输 dx upload 上传文件
dx download 下载文件
dx head 查看文件头部
dx cat 输出文件内容
元数据 dx describe 查看对象详情
dx find data/jobs/apps 搜索实体
dx tag / dx set_properties 设置标签/属性
作业 dx run 启动作业
dx watch 实时监控日志
dx wait 等待作业完成
dx terminate 终止作业
dx install 安装/收藏应用

💡最佳实践与常见陷阱

✅ DX CLI 使用最佳实践

1. 永远用ID引用对象

文件名在项目中不唯一——两个同名文件可以共存。使用file-xxxx而非文件名来引用对象，确保操作的是正确的对象。

2. 脚本中始终使用--brief和-y

--brief只返回对象ID，方便管道传递。-y跳过确认提示，避免脚本卡在交互等待。

3. 通配符必须加引号

dx ls "*.fastq"而非dx ls *.fastq。否则Shell会先在本地展开。

4. 利用链式引用而非顺序等待

不要dx wait $BWA_JOB后再启动下游——直接用$BWA_JOB:output作为下游输入，让系统自动管理依赖。

5. 用Properties和Tags组织数据

上传时设置--property和--tag，后续可以用dx find data --property/--tag快速筛选，比目录结构更灵活。

6. 大文件用Upload Agent

dx upload适合小文件。GB级文件使用Upload Agent（UA），支持多线程和断点续传。

7. 及时终止错误作业

发现配置错误的作业立即dx terminate——运行中的作业按时间计费，浪费计算资源就是浪费经费。

8. 使用set -euo pipefail保护脚本

在自动化脚本中使用bash严格模式，任何命令失败都会立即停止脚本，避免错误传播。

❌ 常见陷阱
陷阱 后果 解决方案
通配符不加引号 Shell本地展开，dx收到错误参数 始终用引号："*.fastq"
用文件名删除文件 同名文件多个时，提示选择 用file-ID删除
在脚本中不加-y 脚本卡在确认提示 始终加-y --brief
同项目内dx cp 报错——同项目内不能复制 用dx mv移动，或重新上传
上传到/data以为是目录 如果/data不存在，创建文件而非目录 先dx mkdir data，上传时用--path /data/（注意尾斜杠）
忘记dx select切换项目 操作在了错误的项目上 脚本开头始终dx select PROJECT_ID

📄参考资源

📄 参考资源

官方文档：

工具版本：

  • dx-toolkit v0.394.0, API v1.0.0
  • Python 3 required
  • 安装：pip install dxpy

快速帮助：

  • dx help——按分类列出所有命令
  • dx help <category>——查看某类命令
  • dx help <command>或dx <command> -h——查看具体命令用法
一句话总结：DX CLI的设计哲学是"一切皆对象、引用而非复制、声明式依赖管理"。通过对象ID的不可变引用确保分析可重复性，通过作业链式引用构建声明式流水线，通过细粒度权限控制实现安全协作。掌握这些底层逻辑后，从数据上传到全流程自动化分析，一条命令行就够了。