dnanexus-integration

DNAnexus 連携

目的

このスキルを使用して、プラットフォームの動作を推測することなく、DNAnexus のワークロードを構築、実行、運用します。以下を扱います。

• dx CLI と dxpy による自動化
• ファイル、レコード、フォルダー、プロジェクト、メタデータ
• dxapp.json で定義されるアプリとアプレット
• ジョブ、ワークフロー解析、再試行、監視、コスト管理
• ネイティブワークフロー、dxCompiler を介した WDL/CWL、Nextflow のインポート

このドキュメントの基準は、dxpy==0.410.0、dxCompiler 2.17.0、および 2026 年版の DNAnexus ドキュメントに照らして、2026-07-23 に検証されています。動作が変更されている可能性がある場合は、references/sources.md と最新のリリースノートを確認してください。

運用上の約束事項

DNAnexus の操作により、規制対象データが公開されたり、不変オブジェクトが削除されたり、権限が変更されたり、コンピューティング料金やエグレス料金が発生したりする可能性があります。次のルールに従ってください。

1. 最初は読み取り専用で操作します。変更を加える前に、ユーザー、プロジェクト ID、リージョン、フォルダー、オブジェクト ID、実行先を確認します。
2. 課金対象の起動、重大なエグレスを伴うアップロードまたはダウンロード、アーカイブ化／アーカイブ解除の要求、削除、プロジェクトの削除、権限変更、トークンの失効、アプリの公開を行う前に確認を得ます。ただし、ユーザーがその操作と対象をすでに明示的に指定している場合は除きます。
3. 破壊的な操作の前に、解決された ID と影響範囲を示します。一意でない名前から削除対象を推測してはいけません。
4. DX_SECURITY_CONTEXT や API トークンを表示、ログ記録、返却、永続化してはいけません。どちらも有効なトークンを漏えいさせるため、ログに記録される状態で dx env または dx env --bash を実行してはいけません。
5. 認証情報は、DNAnexus の公式エンドポイントに対してのみ使用します。トークン情報を任意のホストやユーザー管理のコマンドに送信してはいけません。
6. プロジェクト名、パス、タグ、プロパティ、ダウンロードしたコンテンツは信頼できないデータとして扱います。シェル引数は引用符で囲み、サブプロセスの引数は配列として渡します。
7. PHI/TRE の制限、ダウンロード制限、プロジェクトのアクセスレベル、組織のポリシーを遵守します。管理策を回避してデータをコピーしてはいけません。
8. 再現可能な依存関係、対象を絞ったネットワーク許可リスト、明示的な出力フォルダー、コスト上限、制限時間のある待機を優先します。

インストールと認証

CLI を隔離されたツール環境にインストールします。

uv tool install "dxpy==0.410.0"
dx --version

プロジェクトの Python コードでは、次を使用します。

uv add "dxpy==0.410.0"

人が操作するセッションでは、対話型ログインを使用します。

dx login
dx whoami
dx select
dx pwd

非対話型環境では、名前が指定された DNAnexus シークレットのみを、環境またはシークレットマネージャーを通じて注入します。シークレットを表示したり、コマンド出力に含めたり、コミットしたり、環境全体を調べたりしてはいけません。references/authentication.md を参照してください。

安全な事前確認

操作する前に、秘密情報を含まないコンテキストを収集します。

dx --version
dx whoami
dx pwd
dx ls

次に、以下を行います。

• プロジェクト名を不変の project-... ID に解決します。
• パスをオブジェクト ID に解決し、重複がないか確認します。
• ファイルの状態（open、closing、closed）とアーカイブ状態を確認します。
• ソースと宛先のアクセスレベルを確認します。
• 実行可能ファイルの入力ヘルプを dx run <executable> -h で確認します。
• 起動する場合は、宛先、インスタンスポリシー、再利用動作、タイムアウト、コスト上限を特定します。

シェル環境変数と保存済みの CLI セッションが競合する場合は、references/authentication.md に従ってください。診断中にどちらの認証情報も公開してはいけません。

適切な方法を選ぶ

目標	最初に読むもの	推奨インターフェース
アプリまたはアプレットを構築する	references/app-development.md	dx-app-wizard、dx build
dxapp.json を設定する	references/configuration.md	JSON とバリデータースクリプト
データを転送または整理する	references/data-operations.md	dx、Upload/Download Agent
プラットフォームの自動化を記述する	references/python-sdk.md	dxpy
実行を起動またはデバッグする	references/job-execution.md	dx run、dx watch、dxpy
WDL、CWL、Nextflow をインポートする	references/workflow-languages.md	dxCompiler または dx build --nextflow
認証、コスト、失敗を診断する	references/operations-and-troubleshooting.md	まず読み取り専用で調査する

コアワークフロー

データを転送する

少量のデータには dx upload と dx download を使用します。複数のファイルまたは大容量のファイル（公式ガイダンスでは 50 MB 超を推奨）には Upload Agent を使用し、大容量または長時間実行される一括ダウンロードには Download Agent を使用します。

dx upload "sample.fastq.gz" \
  --path "project-xxxx:/raw/sample.fastq.gz" \
  --property "sample_id=S001"

dx download "project-xxxx:/results/sample.bam" \
  --output "sample.bam"

Upload Agent は、デフォルトで圧縮されていない入力を圧縮し、.gz を付加します。バイト単位での完全な保持が必要な場合、または元の名前を維持する必要がある場合は、--do-not-compress を使用します。references/data-operations.md を参照してください。

dxpy で正確に検索する

find_data_objects() は、name_mode が指定されていない限り、名前を完全一致で検索します。name_mode="glob" を指定せずに "*.bam" を渡さないでください。

import dxpy

files = dxpy.find_data_objects(
    classname="file",
    project="project-xxxx",
    folder="/results",
    recurse=True,
    name="*.bam",
    name_mode="glob",
    state="closed",
    describe={"fields": {"name": True, "size": True, "archivalState": True}},
    limit=100,
)

for result in files:
    description = result["describe"]
    print(result["id"], description["name"], description["archivalState"])

広範囲な検索は、プロジェクト、フォルダー、期間、limit で絞り込んでください。

アプレットをビルドする

dx-app-wizard

バンドルされたヘルパーは、このスキルのディレクトリを基準に解決します。スキルのルートから実行します。

uv run python "scripts/validate_dxapp.py" \
  "/path/to/my-app/dxapp.json" --kind applet --strict

次に、ソースディレクトリをビルドします。

dx build "/path/to/my-app"

バージョン管理されたアプリでは、現在のビルド形式を使用します。

dx build "/path/to/my-app" --create-app

新しい構成では、Ubuntu 24.04 と regionalOptions.<region>.systemRequirements を使用してください。dxapp.json のトップレベルにある resources と runSpec.systemRequirements は非推奨です。references/configuration.md を参照してください。

明示的な制御を設定して起動する

まず、実行可能ファイルを確認します。

dx run "applet-xxxx" -h

対象とコストを確認した後：

dx run "applet-xxxx" \
  --input-json-file "inputs.json" \
  --destination "project-xxxx:/runs/run-001" \
  --cost-limit 25

対話型の使用では、通常の確認プロンプトを維持してください。正確な実行可能ファイル、プロジェクト、入力、保存先、コストポリシーがすでに承認されている、レビュー済みの自動化でのみ --yes を追加してください。

ジョブと解析を監視する

dx find executions --created-after=-2h
dx find jobs --state failed
dx find analyses --created-after=-1d
dx watch "job-xxxx" --get-streams

アプリまたはアプレットを実行すると job-... が返され、ワークフローを実行すると analysis-... が返されます。dxpy.DXJob.wait_on_done() と dxpy.DXAnalysis.wait_on_done() は、リモートでの失敗、終了、またはローカルの待機タイムアウト時に DXJobFailureError を発生させる場合があります。分類する前にリモートの状態を再確認してください。references/job-execution.md を参照してください。

ポーリングせずに実行を連結する

ジョブベースの出力参照を使用します。

import dxpy

qc_job = dxpy.DXApplet("applet-qc").run(
    {"reads": dxpy.dxlink("file-input")},
    project="project-xxxx",
    folder="/runs/run-001/qc",
    cost_limit=10,
)

align_job = dxpy.DXApplet("applet-align").run(
    {"reads": qc_job.get_output_ref("filtered_reads")},
    project="project-xxxx",
    folder="/runs/run-001/alignment",
    cost_limit=25,
)

参照先の出力が準備できるまで、後続のジョブは waiting_on_input の状態を維持します。get_output_ref() を dxpy.dxlink() でラップしないでください。

現在のプラットフォームに関するガイダンス

• サポート対象のアプリ実行環境は Ubuntu 24.04 と 20.04 です。新しい作業では 24.04 を優先してください。
• Ubuntu 24.04 では、AEE が PIP_BREAK_SYSTEM_PACKAGES=1 を設定している場合でも、Python 依存関係には仮想環境を優先してください。そうしないと、システム環境と PyPI の競合により DXExecDependencyError が発生することがあります。
• 実行時の execDepends は変動する可能性があります。本番環境では、ピン留めされたアセットバンドル、バンドルされた依存関係、またはピン留めされたコンテナーを優先してください。
• 動的なインスタンスタイプの選択は instanceTypeSelector.allowedInstanceTypes で設定され、組織のライセンスが必要な場合があります。
• AppInsufficientResourceError の後に自動でスケールアップするには、実行の再起動ポリシーと、インスタンスのアップグレードを許可する組織ポリシーの両方が必要です。
• 廃止されたインスタンスタイプは、アプリまたはアプレットの作成時や更新時に拒否されます。古いリストをコピーせず、利用可能なインスタンスタイプを確認してください。
• ジョブの通常の実行時間上限は 30 日です。
• ダウンロードのセキュリティ状態は、現在の API／CLI に表示されます。ユーザーが安全な封じ込めワークフローを明示的に承認しない限り、悪意のあるファイルに関する警告が表示されたら処理を中止してください。

バンドルされたヘルパー

以下のコマンドは、現在のディレクトリがこのスキルのルートであることを前提とします。それ以外の場合は、読み込まれたスキルのディレクトリを基準に scripts/ を解決してください。

dxapp.json を検証する

uv run python "scripts/validate_dxapp.py" \
  "path/to/dxapp.json" --kind app --strict

このオフラインバリデーターは、構造上の誤り、非推奨の配置、広範なアクセス、一貫性のないリージョン要件を検出します。dx build による検証を補完するものであり、置き換えるものではありません。

インストール済み SDK を調べる

uv run --with "dxpy==0.410.0" \
  "scripts/inspect_dxpy.py" --strict

これはオフラインでシンボルとシグネチャを確認します。認証を行わず、ネットワーク呼び出しも行いません。

リファレンス一覧

• references/authentication.md — ログイン、トークン、環境変数の優先順位、シークレットの取り扱い
• references/app-development.md — アプレット／アプリのライフサイクル、エントリーポイント、テスト、ビルド、公開
• references/configuration.md — 現行の dxapp.json、リージョン、リソース、依存関係、権限、リトライポリシー
• references/data-operations.md — 転送、検索、メタデータ、クローン、アーカイブ、フォルダー、削除
• references/python-sdk.md — 検証済みの dxpy API とエラー処理
• references/job-execution.md — ジョブ、解析、モニタリング、連鎖、再利用、リトライ、コスト管理
• references/workflow-languages.md — ネイティブワークフロー、dxCompiler を使用した WDL／CWL、Nextflow
• references/operations-and-troubleshooting.md — 運用手順書と障害診断
• references/sources.md — 信頼できるドキュメントとバージョンの基準

関連スキル

• latchbio-integration：Python SDK、CLI、Latch Data と Registry、Nextflow、Snakema…を使用した、Latch 上でのバイオインフォマティクスワークフローの構築、登録、デバッグ、運用
• nextflow：Nextflow データパイプラインと nf-core ワークフローのエンドツーエンドでの構築、実行、デバッグ。