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

主な機能

このスキルは、詳細なリファレンスドキュメントを含む次の 5 つの主要分野で構成されています。

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 スイートの一部です。