dnanexus-integration

DNAnexus 連携

概要

DNAnexus は、生物医学データ解析およびゲノミクスのためのクラウドプラットフォームです。アプリ/アプレットを構築・デプロイし、データオブジェクトを管理し、ワークフローを実行できます。また、ゲノミクスパイプラインの開発と実行には dxpy Python SDK を使用します。

このスキルを使用するタイミング

このスキルは、次の場合に使用してください。

• DNAnexus のアプリ/アプレットを作成、ビルド、または変更する場合
• ファイルやレコードをアップロード、ダウンロード、検索、整理する場合
• 解析を実行し、ジョブを監視し、ワークフローを作成する場合
• dxpy を使用してプラットフォームと連携するスクリプトを書く場合
• dxapp.json を設定し、依存関係を管理し、Docker を使用する場合
• FASTQ、BAM、VCF、その他のバイオインフォマティクスファイルを処理する場合
• プロジェクト、権限、またはプラットフォームリソースを管理する場合

主な機能

このスキルは 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. 設定と依存関係

目的: アプリのメタデータを設定し、依存関係を管理します。

主な操作:

• inputs、outputs、run 仕様を含む 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
files = dxpy.find_data_objects(
    classname="file",
    name="*.bam",
    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

よくあるパターン

パターン 1: バッチ処理

同じ分析で複数のファイルを処理します:

# Find all FASTQ files
files = dxpy.find_data_objects(
    classname="file",
    name="*.fastq",
    project="project-xxxx"
)

# Launch parallel jobs
jobs = []
for file_result in files:
    job = dxpy.DXApplet("applet-xxxx").run({
        "input": dxpy.dxlink(file_result["id"])
    })
    jobs.append(job)

# Wait for all completions
for job in jobs:
    job.wait_on_done()

パターン 2: マルチステップのパイプライン

複数の分析を連結します:

# 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")
})

パターン 3: データの整理

分析結果を体系的に整理します:

# 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"]
)

ベストプラクティス

1. エラー処理: API 呼び出しは必ず try-except ブロックで囲んでください
2. リソース管理: ワークロードに適したインスタンスタイプを選択してください
3. データの整理: 一貫したフォルダー構造とメタデータを使用してください
4. コスト最適化: 古いデータはアーカイブし、適切なストレージクラスを使用してください
5. ドキュメント: dxapp.json に明確な説明を含めてください
6. テスト: 本番利用の前に、さまざまな入力タイプでアプリをテストしてください
7. バージョン管理: アプリにはセマンティックバージョニングを使用してください
8. セキュリティ: 認証情報をソースコードにハードコードしないでください
9. ログ記録: デバッグのために有益なログメッセージを含めてください
10. クリーンアップ: 一時ファイルと失敗したジョブを削除してください

リソース

このスキルには詳細なリファレンスドキュメントが含まれています:

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]