bioinformatics-on-healthomics

Name: bioinformatics-on-healthomics
Author: awslabs

github.com/awslabsデータ・データベース6865 回インストール4 週間前に更新

bioinformatics-on-healthomics について

bioinformatics-on-healthomics は、AWS HealthOmics でのバイオインフォマティクスワークフローの作成、デプロイ、実行を案内するスキルです。パイプライン選択から基盤設定、ワークフロー生成までを扱い、MCP ツールでコンテナ確認や検証、実行管理を行います。

主な機能

01解析目標の確認とパイプライン提案
02WDL または Nextflow の選択
03コンテナ、S3、IAM の設定
04ワークフロー定義の生成と検証
05ワークフロー登録と実行状況の監視

活用シーン

01FASTQ の品質管理やアライメントパイプラインの構築
02変異検出または RNA-Seq ワークフローの作成
03公開コンテナイメージのプライベート ECR へのキャッシュ
04実行失敗の診断とキャッシュ結果の再利用

MCP 対応

HealthOmics MCP ツールを使い、コンテナの利用可否確認、ワークフローの検証・登録、実行管理を行います。テストデータの検索には RODA MCP も利用できます。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/awslabs/hcls-agent-skills --skill bioinformatics-on-healthomics

インストール後、Claude Code で/bioinformatics-on-healthomicsを入力して読み込まれたか確認します。

同梱ファイルscripts/setup-healthomics-role.shscripts/setup-s3-bucket.sh

詳細

AWS HealthOmics でのバイオインフォマティクス解析

AWS HealthOmics でバイオインフォマティクスのワークフローを作成、デプロイ、実行するためのエンドツーエンドのスキルです。高度な技術知識がないユーザーを想定しており、エージェントが明確な説明とともに、あらゆる判断をサポートします。

応答の構成

HealthOmics のバイオインフォマティクスワークフローをユーザーに案内する際は、次の順序に従ってください。

解析の目的を明確にする — 解析の種類、生物種、データ形式を確認します
ツールを推奨する — 理由を添えてパイプラインを提案し、確認を求めます
ワークフロー言語を選択する — 複雑さに応じて WDL または Nextflow を選択します
インフラストラクチャをセットアップする — コンテナ（ECR プルスルー）、S3、IAM、実行キャッシュを設定します
ワークフローコードを生成する — 登録前にリントします
登録して実行する — デプロイし、実行を開始して進捗を監視します
失敗に対処する — MCP ツールで診断し、キャッシュを利用して反復します
結果を提示する — 出力先を案内し、最適化を提案します

基本モデル

AWS HealthOmics は、ゲノミクスワークフローを実行するフルマネージドサービスです。以下を用意します。

ワークフロー定義（Nextflow または WDL）
ECR 内のコンテナイメージ（プルスルーキャッシュ経由でパブリックレジストリから取得）
S3 内の入力データ
IAM サービスロール

HealthOmics がコンピューティングリソースのプロビジョニング、スケジューリング、出力の収集を処理します。

主な制約

すべてのコンテナをプライベート ECR に置く必要があります（パブリックイメージにはプルスルーキャッシュを使用します）
すべての入出力データを S3 に置き、ワークフローと同じリージョンにする必要があります
omics.amazonaws.com に対する信頼ポリシーを持つサービスロールが必要です
対応リージョン：us-east-1、us-east-2、us-west-2、eu-west-1、eu-west-2、 eu-central-1、ap-southeast-1、ap-northeast-1、ap-northeast-2、il-central-1

前提条件

開始前に、次の項目を確認してください。

AWS 認証情報が HealthOmics 対応リージョン向けに設定されていること
AWS CLI v2 がインストールされていること
HealthOmics MCP サーバーが利用可能で、有効になっていること（aws-healthomics パワーを使用します）
テストデータの検索に使用する RODA MCP が利用可能であること（任意ですが推奨）

フェーズ 1：ユーザーの解析内容を把握する

何を達成したいのかをユーザーに尋ねます。一般的な解析の種類は次のとおりです。

解析の種類	一般的なツール	入力	出力
品質管理	FastQC、MultiQC、fastp	FASTQ	QC レポート、トリミング済み FASTQ
アライメント	BWA-MEM2、STAR、minimap2、bowtie2	FASTQ + リファレンス	BAM/CRAM
バリアントコーリング	GATK HaplotypeCaller、DeepVariant、Strelka2、FreeBayes	BAM + リファレンス	VCF/gVCF
構造バリアント	Manta、DELLY、LUMPY、Sniffles	BAM + リファレンス	VCF
RNA-Seq	STAR + featureCounts、Salmon、kallisto	FASTQ + リファレンス/インデックス	カウント行列
メチル化	Bismark、bwa-meth	FASTQ + リファレンス	メチル化コール
バリアントアノテーション	VEP、SnpEff、ANNOVAR	VCF + データベース	アノテーション済み VCF
ジョイントジェノタイピング	GATK GenomicsDBImport + GenotypeGVCFs	gVCF	ジョイント VCF
体細胞バリアントコーリング	Mutect2、VarScan2、Strelka2-somatic	腫瘍/正常 BAM	体細胞 VCF

推奨エンジン

ユーザーが述べた目的に基づいて、ツールのパイプラインを推奨します。組み合わせの例：

全ゲノムシーケンシング（生殖細胞系列）：

fastp（QC + トリミング）→ BWA-MEM2（アライメント）→ GATK MarkDuplicates → GATK HaplotypeCaller → VCF フィルタリング

RNA-Seq の差次的発現解析：

fastp（QC）→ STAR（アライメント）→ featureCounts（定量）

ターゲットパネル / エクソーム：

fastp → BWA-MEM2 → GATK MarkDuplicates → GATK HaplotypeCaller（区間指定あり）→ VQSR またはハードフィルタリング

各ツールを推奨する理由を必ず説明し、先に進む前に確認を求めてください。

フェーズ 2：ワークフロー言語の選択

希望する言語をユーザーに尋ねます。

WDL（ほとんどのユーザーに推奨）— 構文が明確で、入出力が明示的であり、直線的なパイプラインに適しています
Nextflow — 多くの分岐点を持つ、複雑でデータ駆動型のパイプラインに適しています

ユーザーに希望がない場合、シンプルなパイプラインでは WDL 1.1、複雑なマルチサンプルのスキャッター・ギャザーパターンでは Nextflow DSL2 をデフォルトとして使用します。

フェーズ 3：コンテナイメージの取得

パイプライン内の各ツールについて、次の優先順位でコンテナイメージを探します。

quay.io/biocontainers/ — バイオインフォマティクス向けの厳選されたコンテナ。優先して使用します
public.ecr.aws/ — AWS がホストするパブリックイメージ
Docker Hub（registry-1.docker.io）— 幅広く利用できますが、レート制限があります

検索方法

各ツールについて、最新の安定版イメージを検索します。

quay.io：quay.io/biocontainers/<tool>:<version>--<hash>
ECR Public：public.ecr.aws/biocontainers/<tool>:<version>
Docker Hub：broadinstitute/gatk:<version>、staphb/<tool>:<version>

ECR プルスルーキャッシュの設定

HealthOmics では、コンテナをプライベート ECR に配置する必要があります。プルスルーキャッシュを使うと、パブリックイメージを自動的にミラーリングできます。

HealthOmics MCP の CreatePullThroughCacheForHealthOmics ツールを使用します。

upstream_registry に docker-hub、quay、または ecr-public を指定します
必要に応じて ecr_repository_prefix を設定します
quay と ecr-public：認証情報は不要です
docker-hub：credential_arn が必須です（下記を参照）
このツールはキャッシュルールを自動的に作成し、HealthOmics 用のレジストリ権限を更新して、適切な権限を持つリポジトリ作成テンプレートを作成します

Docker Hub 認証（docker-hub のプルスルーキャッシュに必須）

Docker Hub では、匿名でのプルにレート制限が適用されます。プルスルーキャッシュで Docker Hub を使用するには、認証情報を Secrets Manager に保存し、ARN を credential_arn として渡します。

KMS キーを作成します：aws kms create-key → ARN を保存します
認証情報を保存します：aws secretsmanager create-secret --kms-key-id <KEY> --secret-string '{"username":"...","password":"..."}' → シークレット ARN を保存します
credential_arn を CreatePullThroughCacheForHealthOmics に渡します

ユーザーが Docker Hub アカウントを持っていない場合は、認証が不要な quay.io/biocontainers を優先してください。

設定を検証するには、すべてのプルスルーキャッシュルール、レジストリ権限、リポジトリテンプレートを確認する ValidateHealthOmicsECRConfig を使用します。

既存のルールと、HealthOmics で利用可能かどうかを一覧表示するには、ListPullThroughCacheRules を使用します。

コンテナの利用可否を確認する

HealthOmics MCP の CheckContainerAvailability ツールで initiate_pull_through: true を指定し、各コンテナにアクセスできることを確認します。このツールはイメージの存在を検証し、HealthOmics のアクセス権限を確認して、初回のプルスルーを開始できます。

特定のイメージをアップストリームレジストリから HealthOmics の権限付きプライベート ECR にコピーするには、ソースイメージ参照を指定して CloneContainerToECR を使用します（Docker Hub の省略形式、quay.io、public.ecr.aws の形式に対応しています）。

コンテナレジストリマップ

パブリックレジストリ URI を参照するワークフローでは、コンテナレジストリマップを作成すると、HealthOmics がプル先をプライベート ECR にリダイレクトします。

HealthOmics MCP の CreateContainerRegistryMap ツールを使用します。

HealthOmics で利用可能なキャッシュを自動検出するには、include_pull_through_caches: true を設定します
必要に応じて、上書き用の additional_registry_mappings または image_mappings を指定します
出力は container_registry_map パラメーターを使って CreateAHOWorkflow に直接渡すか、S3 に保存して container_registry_map_uri から参照できます

フェーズ 4：ワークフローの生成

選択したツールと言語に基づいて、ワークフロー定義を生成します。healthomics power のステアリングドキュメントにあるベストプラクティスを使用してください

WDL の構造

workflow/
  main.wdl          # Top-level workflow
  tasks/
    fastqc.wdl      # Individual task definitions
    bwa_mem2.wdl
    gatk_hc.wdl
  structs/
    sample.wdl      # Struct definitions
  parameters.json   # Example parameters
  README.md         # Documentation

Nextflow の構造

workflow/
  main.nf           # Entry point
  nextflow.config   # Configuration
  modules/
    fastqc.nf       # Process definitions
    bwa_mem2.nf
    gatk_hc.nf
  conf/
    healthomics.config  # HealthOmics-specific config
  nextflow_schema.json  # Input schema (nf-schema)
  parameters.json       # Example parameters
  README.md             # Documentation

HealthOmics との互換性に関する主なルール

すべてのタスク／プロセスで CPU、メモリ、コンテナを宣言する必要があります
タスクごとに、CPU を 2 つ以上、メモリを 4 GB 以上使用します
すべての最終出力をワークフローレベルで宣言する必要があります
Nextflow：publishDir のベースには /mnt/workflow/pubdir を使用する必要があります
WDL：~{var} による補間と <<< >>> のコマンド区切りを使用します
すべてのコマンドブロックで set -eu を使用します

デプロイ前のリント

WDL/CWL ワークフローでは、デプロイ前の検証に HealthOmics MCP の LintAHOWorkflowDefinition または LintAHOWorkflowBundle ツールを使用します。

フェーズ 5：インフラストラクチャのセットアップ（初回のみ）

初回使用時に、必要な AWS インフラストラクチャをセットアップします。各コンポーネントについてユーザーに確認するか、作成を提案してください。

5A：S3 バケット

ワークフローの入力、出力、オプションの呼び出しキャッシュ用に S3 バケットを作成します：

aws s3 mb s3://<BUCKET_NAME> --region <REGION>

バケットは次の用途に使用します：

入力ファイル（FASTQ、BAM、VCF、参照ファイル）
ワークフローの出力（HealthOmics によって書き込まれる結果）
呼び出しキャッシュ（オプション。中断された実行の再開用）

5B：IAM サービスロール

HealthOmics 用のサービスロールを作成します：

# Create the role with HealthOmics trust policy
aws iam create-role \
    --role-name <ROLE_NAME> \
    --assume-role-policy-document '{
      "Version": "2012-10-17",
      "Statement": [{
        "Effect": "Allow",
        "Principal": {"Service": "omics.amazonaws.com"},
        "Action": "sts:AssumeRole"
      }]
    }'

ロールには次の権限が必要です：

omics.amazonaws.com に対する信頼ポリシー
S3：バケットに対する s3:GetObject、s3:PutObject、s3:ListBucket、s3:GetBucketLocation
ECR：ecr:BatchGetImage、ecr:GetDownloadUrlForLayer、ecr:BatchCheckLayerAvailability
ログ：/aws/omics/* に対する logs:CreateLogGroup、logs:CreateLogStream、logs:PutLogEvents

5C：実行キャッシュのセットアップ

呼び出しキャッシュを使用するか、ユーザーに確認します。呼び出しキャッシュを使用すると、入力が変更されていないタスクの再実行を HealthOmics が省略できることを説明してください。これは、一部のステップ（アライメントなど）は成功しても、後続のステップ（バリアントコーリングなど）の調整が必要となる反復的なワークフロー開発で特に役立ちます。

希望するキャッシュ動作をユーザーに確認してください：

CACHE_ON_FAILURE（開発に推奨）— 実行が失敗した場合、成功したタスクの結果をキャッシュします。次回の実行では、入力が同一のタスクがスキップされます。反復的な開発に最適です。失敗したステップを修正して再実行すると、変更されたタスクまたは失敗したタスクだけが再び実行されます。すでに成功した上流のステップには、キャッシュされた結果が使用されます。
CACHE_ALWAYS — 成否にかかわらず、すべての実行の結果をキャッシュします。同じワークフローを新しいサンプルで再実行し、入力がたまたま同一のタスク（参照インデックスの作成など）をスキップしたい本番パイプラインに便利です。

CreateAHORunCache を使用して実行キャッシュを作成します：

cache_behavior — 上記のユーザーの選択
cache_s3_location — キャッシュ保存用の S3 プレフィックス（例：s3://<BUCKET>/healthomics-cache/）
name — 説明的な名前（例："dev-cache" または "production-cache"）

返された cache_id を保存し、実行時に使用します。

5D：設定ファイル

設定を .healthomics/config.toml に保存します：

omics_iam_role = "arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>"
run_output_uri = "s3://<BUCKET>/healthomics-outputs/"
run_storage_type = "DYNAMIC"
cache_id = "<CACHE_ID>"
cache_behavior = "CACHE_ON_FAILURE"  # or "CACHE_ALWAYS"
cache_s3_location = "s3://<BUCKET>/healthomics-cache/"
aws_region = "<REGION>"

フェーズ 6：ワークフローの登録

MCP ツールを使用して、ワークフローをパッケージ化し、HealthOmics にデプロイします：

ワークフローをパッケージ化する — PackageAHOWorkflow を使用します：
- main_file_content にメインのワークフローファイルのパスを設定します（例：./workflow/main.wdl）
- main_file_name に適切な名前を設定します（例：main.wdl または main.nf）
- additional_files（ファイル名 → ファイルパスの辞書）を使用して、インポートまたはモジュールを指定します
ワークフローを登録する — CreateAHOWorkflow を使用します：
- ワークフローの name を設定します
- definition_source にローカルの ZIP パスを設定するか、PackageAHOWorkflow の base64 出力を渡します
- engine に WDL、NEXTFLOW、または CWL を設定します
- 必要に応じて、container_registry_map または container_registry_map_uri を指定します
- 必要に応じて、description と storage_type を指定します（デフォルトは DYNAMIC）
登録を確認する — GetAHOWorkflow を使用して、ステータスが ACTIVE であることを確認します

実行例：

PackageAHOWorkflow(main_file_content="./workflow/main.nf", additional_files={"modules/bwa.nf": "./workflow/modules/bwa.nf", ...})
  → CreateAHOWorkflow(name="my-pipeline", definition_source=<zip_path>, engine="NEXTFLOW")
  → GetAHOWorkflow(workflow_id=<id>)  # verify ACTIVE

フェーズ 7：入力パラメーターの準備

入力ファイルをユーザーが特定できるよう支援します。

S3 内のファイルの検索

HealthOmics MCP の SearchGenomicsFiles ツールを使用して、設定済みの S3 バケット内にある FASTQ、BAM、VCF、または参照ファイルを検索します。

RODA のテストデータの使用

RODA MCP が利用可能な場合は、テスト用の公開データセットを見つけるために使用します：

関連するデータセットを検索します（例："1000 genomes"、"giab"、"clinvar"）
データセットの構造をプレビューします
適切なテストファイルを特定します

よく使用されるテストデータセット：

GIAB（Genome in a Bottle） — バリアントコーリングの検証に使用する正解データセット
1000 Genomes — 集団規模の WGS データ
ClinVar — 臨床的に重要なバリアントの注釈
ENCODE — 機能ゲノミクスデータ

parameters.json の作成

ワークフローのパラメーターテンプレートに合わせて、パラメーターファイルを作成します：

{
  "input_fastq_r1": "s3://bucket/data/sample_R1.fastq.gz",
  "input_fastq_r2": "s3://bucket/data/sample_R2.fastq.gz",
  "reference_fasta": "s3://bucket/references/GRCh38.fasta",
  "sample_name": "NA12878",
  "output_prefix": "results"
}

フェーズ 8：ワークフローの実行

実行を開始する

HealthOmics MCP の StartAHORun ツールを使用します。

workflow_id — 登録ステップで取得したもの
role_arn — .healthomics/config.toml の omics_iam_role
name — 実行内容が分かる名前
output_uri — .healthomics/config.toml の run_output_uri
parameters — ワークフローのパラメーター（parameters.json から取得）
storage_type — 設定ファイルの値（デフォルトは DYNAMIC）
cache_id — 自動的に解決されます（下記を参照）
cache_behavior — .healthomics/config.toml の値（CACHE_ON_FAILURE または CACHE_ALWAYS）

実行キャッシュの解決

ユーザーがキャッシュ ID を覚えたり指定したりする必要がないようにしてください。自動的に解決します。

.healthomics/config.toml を確認 — cache_id が設定されている場合は、それをそのまま使用します。
セッション履歴を確認 — このセッション中にキャッシュが作成されている場合は、そのキャッシュ ID を使用します。
どちらも利用できない場合は、ListAHORunCaches を呼び出して既存のキャッシュを探します。
- キャッシュがちょうど 1 つ存在する場合 → 自動的に使用します。
- キャッシュが複数存在する場合 → 名前、動作、作成日を表示して一覧を提示し、ユーザーに選択してもらいます。
- キャッシュが存在しない場合 → 作成するようユーザーに案内します（フェーズ 5C を参照）。
解決したら、cache_id を .healthomics/config.toml に保存し、次回以降は確認せずに使用できるようにします。

実行キャッシュが利用可能な場合は、必ず cache_id と cache_behavior を渡してください。 反復的な開発中に、前回の実行で既に成功した高コストのタスク（アラインメントや重複マーキングなど）を再実行せずに済みます。

実行を監視する

監視には HealthOmics MCP ツールを使用します。

GetAHORun — 全体のステータス、所要時間、失敗理由を確認します
ListAHORunTasks — 個々のタスクの進捗とステータスを確認します
GetAHORunLogs — ワークフロー実行の概要イベントを確認します
GetAHORunEngineLogs — デバッグ用にエンジンの標準出力／標準エラーを確認します
GetAHOTaskLogs — 特定のタスクのログを確認します
GetAHORunManifestLogs — リソースメトリクスを含むワークフローの概要を確認します

失敗に対処する

実行に失敗した場合：

DiagnoseAHORunFailure を使用して、以下を含む包括的な診断情報を取得します。
- 失敗理由
- エンジンログ
- 失敗したタスクのログ
- 実行可能な推奨事項
よくある問題：
- S3 オブジェクトが見つからない — 入力パスが存在することを確認します
- コンテナのプルに失敗した — ECR の権限とプルスルーキャッシュを確認します
- メモリ不足 — ワークフロー定義でタスクのメモリを増やします
- タイムアウト — タスクのタイムアウトを延長するか、無限ループがないか確認します
ワークフローを修正し、CreateAHOWorkflowVersion で新しいバージョンを作成します
新しいバージョンで再実行します

フェーズ 9：結果と次のステップ

正常に完了した後：

出力は S3 の出力先にあります
GetAHORun を使用して、正確な runOutputUri を確認します
パフォーマンスを最適化するには、AnalyzeAHORunPerformance を使用します
視覚化するには、GenerateAHORunTimeline を使用します

失敗時の対応ガイド

症状	対処方法
"HealthOmics is not available"	サポート対象のリージョンを使用します
コンテナのプルに失敗した	`CreatePullThroughCacheForHealthOmics` を使用して PTC ルールを修正します
S3 へのアクセスが拒否された	正しいバケット ARN を指定して IAM ロールのポリシーを更新します
ワークフローが CREATING のまま停止している	最大 10 分待ちます。大規模なワークフローは時間がかかります
レジストリマップが一致しない	マップの更新後にワークフローを再登録します
パラメーターの検証エラー	ワークフローのパラメーターテンプレートで名前／型の不一致がないか確認します

重要なルール

HealthOmics の呼び出しには必ず HealthOmics MCP ツールを使用します。HealthOmics の呼び出しに AWS CLI を直接使用しないでください。
コンテナの優先順位：quay.io/biocontainers → public.ecr.aws → Docker Hub。
プルスルーキャッシュは必須です。CreatePullThroughCacheForHealthOmics を使用してください。
リージョンの一貫性：S3、ECR、HealthOmics は同じリージョンを使用する必要があります。
デプロイ前にリントします：登録前に LintAHOWorkflowDefinition で WDL/CWL を検証してください。
設定ファイル：保存済みの設定を .healthomics/config.toml から読み込みます。
テストデータ：ユーザーにアップロードを依頼する前に、RODA MCP で公開データセットを確認してください。
すべての手順を説明し、破壊的な操作の前に確認します。
コスト効率を高めるため、デフォルトで DYNAMIC ストレージを使用します。
診断：失敗には DiagnoseAHORunFailure、最適化には AnalyzeAHORunPerformance を使用します。
呼び出しキャッシュ：開発時はデフォルトで CACHE_ON_FAILURE を使用します。キャッシュ ID は設定から自動的に解決し、複数のキャッシュがある場合にのみユーザーに確認します。

Markdown 対応

ログインしてコメント

基本情報

作者: awslabs
リポジトリ: awslabs/hcls-agent-skills
カテゴリ: データ・データベース
インストール数: 65
GitHub スター: 68

問題を報告