alterlab-dnanexus

DNAnexus 集成

概述

DNAnexus 是一个用于生物医学数据分析和基因组学的云平台。可构建和部署应用/小应用、管理数据对象、运行工作流，并使用 dxpy Python SDK 开发和执行基因组学流水线。

何时使用此技能

以下情况应使用此技能：

• 创建、构建或修改 DNAnexus 应用/小应用
• 上传、下载、搜索或整理文件和记录
• 运行分析、监控作业、创建工作流
• 编写使用 dxpy 与平台交互的脚本
• 设置 dxapp.json、管理依赖项、使用 Docker
• 处理 FASTQ、BAM、VCF 或其他生物信息学文件
• 管理项目、权限或平台资源

不适用的情况

场景	改用
在 LatchBio 上使用 Latch SDK 工作流（@workflow/@task、LatchFile/LatchDir）	alterlab-latchbio
直接运行 nf-core/sarek 胚系/体细胞变异检测流水线	alterlab-nf-core-sarek
在 DNAnexus 之外运行通用无服务器 GPU/CPU 作业或提交 SLURM/HPC 作业	alterlab-modal / alterlab-remote-compute
在本地 Python 中读取或筛选 BAM/VCF 记录	alterlab-pysam
在 Benchling 中管理注册表、库存或 ELN 记录	alterlab-benchling

核心功能

此技能分为五个主要领域，每个领域都有详细的参考文档：

1. 应用开发

用途：创建可在 DNAnexus 平台上运行的可执行程序（应用/小应用）。

主要操作：

• 使用 dx-app-wizard 生成应用框架
• 编写具有正确入口点的 Python 或 Bash 应用
• 处理输入/输出数据对象
• 使用 dx build 或 dx build --app 部署
• 在平台上测试应用

常见用例：

• 生物信息学流水线（比对、变异检测）
• 数据处理工作流
• 质量控制和筛选
• 格式转换工具

参考：参阅 references/app-development.md，了解：

• 完整的应用结构和模式
• Python 入口点装饰器
• 使用 dxpy 处理输入/输出
• 开发最佳实践
• 常见问题及解决方案

2. 数据操作

用途：管理平台上的文件、记录和其他数据对象。

主要操作：

• 使用 dxpy.upload_local_file() 和 dxpy.download_dxfile() 上传/下载文件
• 创建和管理带有元数据的记录
• 按名称、属性或类型搜索数据对象
• 在项目之间克隆数据
• 管理项目文件夹和权限

常见用例：

• 上传测序数据（FASTQ 文件）
• 整理分析结果
• 搜索特定样本或实验
• 在项目之间备份数据
• 管理参考基因组和注释

参考：参阅 references/data-operations.md，了解：

• 完整的文件和记录操作
• 数据对象生命周期（打开/关闭状态）
• 搜索和发现模式
• 项目管理
• 批量操作

3. 作业执行

用途：运行分析、监控执行情况并编排工作流。

主要操作：

• 使用 applet.run() 或 app.run() 启动作业
• 监控作业状态和日志
• 创建子作业以进行并行处理
• 构建并运行多步骤工作流
• 使用输出引用串联作业

常见用例：

• 对测序数据运行基因组学分析
• 并行处理多个样本
• 多步骤分析流水线
• 监控长时间运行的计算
• 调试失败的作业

参考：参阅 references/job-execution.md，了解：

• 完整的作业生命周期和状态
• 工作流创建和编排
• 并行执行模式
• 作业监控和调试
• 资源管理

4. Python SDK（dxpy）

用途：通过 Python 以编程方式访问 DNAnexus 平台。

主要操作：

• 使用数据对象处理器（DXFile、DXRecord、DXApplet 等）
• 使用高级函数执行常见任务
• 针对高级操作直接调用 API
• 在对象之间创建链接和引用
• 搜索和发现平台资源

常见用例：

• 用于数据管理的自动化脚本
• 自定义分析流水线
• 批处理工作流
• 与外部工具集成
• 数据迁移和整理

参考：请参阅 references/python-sdk.md，了解：

• 完整的 dxpy 类参考
• 高级实用函数
• API 方法文档
• 错误处理模式
• 常见代码模式

5. 配置和依赖项

用途：配置应用元数据并管理依赖项。

主要操作：

• 编写包含输入、输出和运行规范的 dxapp.json
• 安装系统软件包（execDepends）
• 打包自定义工具和资源
• 使用资产共享依赖项
• 集成 Docker 容器
• 配置实例类型和超时

常见用例：

• 定义应用输入／输出规范
• 安装生物信息学工具（samtools、bwa 等）
• 管理 Python 软件包依赖项
• 使用 Docker 镜像设置复杂环境
• 选择计算资源

参考：请参阅 references/configuration.md，了解：

• 完整的 dxapp.json 规范
• 依赖项管理策略
• Docker 集成模式
• 区域和资源配置
• 配置示例

快速入门示例

上传并分析数据

import dxpy

# Upload input file
input_file = dxpy.upload_local_file("sample.fastq", project="project-xxxx")

# Run analysis
job = dxpy.DXApplet("applet-xxxx").run({
    "reads": dxpy.dxlink(input_file.get_id())
})

# Wait for completion
job.wait_on_done()

# Download results
output_id = job.describe()["output"]["aligned_reads"]["$dnanexus_link"]
dxpy.download_dxfile(output_id, "aligned.bam")

搜索并下载文件

import dxpy

# Find BAM files from a specific experiment.
# name defaults to exact match; pass name_mode="glob" to use wildcards.
files = dxpy.find_data_objects(
    classname="file",
    name="*.bam",
    name_mode="glob",
    properties={"experiment": "exp001"},
    project="project-xxxx"
)

# Download each file
for file_result in files:
    file_obj = dxpy.DXFile(file_result["id"])
    filename = file_obj.describe()["name"]
    dxpy.download_dxfile(file_result["id"], filename)

创建简单应用

# src/my-app.py
import dxpy
import subprocess

@dxpy.entry_point('main')
def main(input_file, quality_threshold=30):
    # Download input
    dxpy.download_dxfile(input_file["$dnanexus_link"], "input.fastq")

    # Process
    subprocess.check_call([
        "quality_filter",
        "--input", "input.fastq",
        "--output", "filtered.fastq",
        "--threshold", str(quality_threshold)
    ])

    # Upload output
    output_file = dxpy.upload_local_file("filtered.fastq")

    return {
        "filtered_reads": dxpy.dxlink(output_file)
    }

dxpy.run()

工作流决策树

使用 DNAnexus 时，请遵循以下决策树：

1. 需要创建新的可执行文件吗？

   • 是 → 使用 应用开发（references/app-development.md）
   • 否 → 继续第 2 步

2. 需要管理文件或数据吗？

   • 是 → 使用 数据操作（references/data-operations.md）
   • 否 → 继续第 3 步

3. 需要运行分析或工作流吗？

   • 是 → 使用 作业执行（references/job-execution.md）
   • 否 → 继续第 4 步

4. 正在编写 Python 脚本进行自动化吗？

   • 是 → 使用 Python SDK（references/python-sdk.md）
   • 否 → 继续第 5 步

5. 正在配置应用设置或依赖项吗？

   • 是 → 使用 配置（references/configuration.md）

通常需要结合多种功能（例如，应用开发 + 配置，或数据操作 + 作业执行）。

安装和身份验证

安装 dxpy

uv pip install dxpy

登录 DNAnexus

dx login

这会对你的会话进行身份验证，并设置对项目和数据的访问权限。

验证安装

dx --version
dx whoami

常见模式

快速入门部分展示了批处理（查找文件并启动并行作业）；有关 scatter-gather 和子作业，请参阅 references/job-execution.md。

模式 1：多步流水线

将多个分析串联起来（get_output_ref 会将一个作业的输出作为下一个作业的输入）：

# Step 1: Quality control
qc_job = qc_applet.run({"reads": input_file})

# Step 2: Alignment (uses QC output)
align_job = align_applet.run({
    "reads": qc_job.get_output_ref("filtered_reads")
})

# Step 3: Variant calling (uses alignment output)
variant_job = variant_applet.run({
    "bam": align_job.get_output_ref("aligned_bam")
})

模式 2：数据整理

系统地整理分析结果：

# Create organized folder structure
dxpy.api.project_new_folder(
    "project-xxxx",
    {"folder": "/experiments/exp001/results", "parents": True}
)

# Upload with metadata
result_file = dxpy.upload_local_file(
    "results.txt",
    project="project-xxxx",
    folder="/experiments/exp001/results",
    properties={
        "experiment": "exp001",
        "sample": "sample1",
        "analysis_date": "2025-10-20"
    },
    tags=["validated", "published"]
)

最佳实践

• 切勿将 API 令牌硬编码；请通过 dx login 或 DX_SECURITY_CONTEXT 进行身份验证。
• 默认情况下，find_* 的 name 筛选条件会进行精确匹配；使用通配符时请传入 name_mode="glob"。
• 使用 get_output_ref() 直接将作业输出传递给下游输入（它本身已经是 dxlink）。
• 审慎选择实例类型，并设置 timeoutPolicy 以限制失控的成本。

每个参考文件末尾都列有针对相应主题的最佳实践，以提供更深入的指导。

资源

此技能包含详细的参考文档：

references/

• app-development.md - 构建和部署应用/小程序的完整指南
• data-operations.md - 文件管理、记录、搜索和项目操作
• job-execution.md - 运行作业、工作流、监控和并行处理
• python-sdk.md - 包含所有类和函数的 dxpy 库全面参考
• configuration.md - dxapp.json 规范和依赖管理

在需要了解特定操作的详细信息或处理复杂任务时，请加载这些参考资料。

获取帮助

• 官方文档：https://documentation.dnanexus.com/
• API 参考：http://autodoc.dnanexus.com/
• GitHub 仓库：https://github.com/dnanexus/dx-toolkit
• 支持邮箱：[email protected]

属于 AlterLab Academic Skills 套件。