How to use (v0.3) - Genomon-Project/genomon_pipeline_cloud GitHub Wiki

Setup

1. AWS アカウントを作成

GenomonPipelineCloud-v0.3 はAWSのみ対応です

2. ターミナルを起動して必要なツールをインストール

Mac や Linux の場合、OS 付属のターミナルをご使用ください。 Windows の場合、cygwin もしくは Ubuntsu on Windows で動作することを確認しています。

2.1 ecsub

ecsub は AWS Elastic Container Service (ECS) を利用したタスクの作成と実行を1コマンドで利用可能にしたバッチジョブ実行エンジンです。 Univa Grid Engine (UGE) における qsub の代わりに使用します。

以下の手順でインストールします。

cd ~
wget https://github.com/aokad/ecsub/archive/v0.0.10.zip
unzip v0.0.10.zip
cd ecsub-0.0.10
python setup.py build install

インストールできたら、AWS で必要な権限を設定します。手順は以下を参照してください。

AWS IAM の設定

ecsub の動作確認をします。

まず S3バケットの準備が必要です。 ecsub をダウンロードしたディレクトリに example という名前のディレクトリがあり、その中にテストデータが入っていますので、S3バケットにアップロードします。以下の手順で行います。

１）S3バケットを任意の名前で作成します
２）./examples/tasks-wordcount.tsv の中の "ecsub-singapore" を１) で作成したバケット名に置き換えます
３）１）で作成したバケットに example ディレクトリにある wordcount.py, hamlet.txt, kinglear.txt をコピーします。 /examples/tasks-wordcount.tsv で記載しているパスと同じになるように配置してください

$ cat examples/tasks-wordcount.tsv
--env NAME      --input INPUT_FILE      --input-recursive SCRIPT        --output OUTPUT_FILE
Hamlet  s3://ecsub-singapore/wordcount/input/hamlet.txt s3://ecsub-singapore/wordcount/python   s3://ecsub-singapore/output/hamlet-count.txt
Kinglear        s3://ecsub-singapore/wordcount/input/kinglear.txt       s3://ecsub-singapore/wordcount/python   s3://ecsub-singapore/output/kinglear-count.txt

ecsub の動作確認をします。

bucket=s3://{１) で作成したバケット名}
ecsub_root={ecsubをダウンロードしたディレクトリ}
ecsub submit \
    --script ${ecsub_root}/examples/run-wordcount.sh \
    --tasks ${ecsub_root}/examples/tasks-wordcount.tsv \
    --aws-s3-bucket ${bucket}/output/ \
    --wdir /tmp/ecsub/ \
    --image python:2.7.14 \
    --aws-ec2-instance-type t2.micro \
    --disk-size 22

S3 バケットの output ディレクトリに hamlet-count.txt と kinglear-count.txt ができていれば成功です。

2.2 genomon-pipeline-cloud

ecsub のテスト実行は成功しましたか？次は genomon-pipeline-cloud のインストールと環境設定を行います。

以下の手順でインストールします。

cd ~
wget https://github.com/Genomon-Project/genomon_pipeline_cloud/archive/v0.3.0.zip
unzip v0.3.0.zip
cd genomon_pipeline_cloud-0.3.0
python setup.py build install

次に解析に使用するリファレンスゲノムやシーケンスデータを任意のS3バケットにアップロードします。

１）S3にリファレンスゲノムをおきます S3 リファレンスファイル用のバケットを作成し、リファレンス (https://genomon-portal.hgc.jp/data/_GRCh37.zip) をダウンロードして解凍してuploadします。 32Gありますので、結構時間がかかります。
２）レポート機能の設定ファイルを１）で作成したバケットにコピーします。レポート作成機能 (paplot) の設定ファイルは以下よりダウンロードできます
- paplot-dna
- paplot-rna
３）シーケンスデータ (.fastq, ペアリードのみ) をS3 にアップロードします。

アップロードしたデータのパスに合わせて genomon-pipeline-cloud の設定ファイルを編集します。 genomon-pipeline-cloud をダウンロードしたディレクトリに example_conf というディレクトリがあります。その中にパラメータ設定ファイル (.cfg) とサンプル設定ファイル (.csv) のテンプレートがありますので、編集して使用します。

４）param_dna_ecsub.cfg をエディタで開き、"s3://genomon-bucket/" という記述を１）で作成したバケット名に置換します。
５）sample_dna.csv を開いて、３）でアップロードしたサンプルのパスになるよう編集します。基本的な記載方法は本家ドキュメントを参照してください
- DNA サンプル設定ファイルについて
- RNA サンプル設定ファイルについて

設定が終わったら、Quick Start を動かして動作確認します。 ${YOUR_BUCKET}/genomon_pipeline_cloud_test ディレクトリに paplot/sample_dna/paplot.tar.gz ができていれば成功です。

How to use

基本的な使い方はGenomonPipelineと同様ですので、詳しくは本家ドキュメントを参照ください。

Genomon-doc

genomon_pipeline_cloud {解析タイプ (dna or rna)} \
    {サンプル設定ファイル} \
    {解析結果出力先} \
    {パイプライン設定ファイル}

使用例

$ genomon_pipeline_cloud dna \
    ./example_conf/sample_dna.csv \
    s3://${S3_BUCKET}/dna \
    ./example_conf/param_dna_awsub.cfg

注意事項

Ctrl-Cやエラーによりパイプラインが途中で止まってしまった場合、AWS上に解析途中のインスタンスが残ってしまうことがあります。そのままでは課金されてしまいますので、AWSコンソールからインスタンスを削除するようにしてください。

AWS の設定オプション

以下はオプションですので、必要に応じて設定してください。

オンデマンドインスタンスの制限緩和

AWSには同時に作成できるインスタンスの数に制限（大体20）があります。デフォルトのままでは同時に解析できるサンプル数はおよそ4程度ですので、以下の手順で制限緩和を行います。 ※制限緩和を行なっても実際にインスタンスを作成しない限りコストはかかりませんので可能であれば、制限緩和を行うことをお勧めします。

AWSコンソールから「EC2」→「制限」より以下項目で制限緩和のリクエストを出します。

実行中のオンデマンドインスタンスの数: EC2
実行中のオンデマンドインスタンスの数: (使用したいインスタンスタイプ)

AWS S3 の公開設定

レポートをweb上で表示するのであれば、「static website hosting」を有効にし、以下内容でパケットポリシーを設定します。

# 行はコメントなので、実際は記入しません。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "PublicReadForGetBucketObjects",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": [
                # {YOUR-BUCKET} は実際のバケット名
                # "arn:aws:s3:::{YOUR-BUCKET}/*" で全体公開しても良いが
                # レポートディレクトリのみに公開範囲を限定した方が安心
                "arn:aws:s3:::{YOUR-BUCKET}/dna/paplot/*"
            ],
            "Condition": {
                "IpAddress": {
                    # 自分のマシンのグローバルネットワークアドレスを設定した方が安心
                    "aws:SourceIp": "xxx.xxx.xxx.0/24"
                }
            }
        }
    ]
}

カウントをまたいで S3 バケットを共有する

以下のようにしてパケットポリシーを設定します

S3バケット→「アクセス権限」→「アクセスコントロールリスト」→ 「他のAWSアカウントのアクセス」→「＋アカウントの追加」 AWSアカウントを記入して、「バケットの読み取りアクセス権限」にチェックして「保存」

その他機能

前提条件：バッチジョブ実行エンジンとして ecsub を使用していること

バッチジョブ実行ログを表示する

バッチジョブが失敗してしまった時、ジョブそのもののログを見ると原因が分かることがあります。
ecsub は AWS CloudWatch にログを保存していますので、以下のようにしてアクセスします。

直接URLを張り付ける

ecsubでジョブを実行すると、インスタンス起動してジョブを投入した後に以下のようなメッセージが表示されます。

2019-05-17 13:19:32.737561 [bwa-alignment-tasks-aokada-20190517-131631-fU4PB:000] For detail, see log-file: https://ap-northeast-1.console.aws.amazon.com/cloudwatch/home?region=ap-northeast-1#logEventViewer:group=ecsub-bwa-alignment-tasks-aokada-20190517-131631-fU4PB;stream=ecsub/bwa-alignment-tasks-aokada-20190517-131631-fU4PB_task/54b2c9f4-16f6-42f2-b750-3179d1d88a26

WEB ブラウザを開いて、AWS マネジメントコンソールにログインした後、"see log-file: " より後の "https://" から始まる URL をコピーしてWEBブラウザに貼り付けてください。

ログが表示されます。最初はセットアップログですので、「すべて」をクリックして最新のログを表示してください。

AWS マネジメントコンソールからアクセスする

GenomonPipelineCloudの実行ログが残っておらず、ログのURLが残っていない場合は以下の順にアクセスします。

AWS CloudWatch > ログ > 該当するログストリームを表示

ログストリーム名は「ecsub-{タスク名}-{user}-{日付}-{乱数}」の構成になっています。

バッチジョブ実行で使用したリソースを表示する

バッチジョブが失敗してしまった時、ジョブそのものに問題がなく、リソース不足（主にディスク容量の不足）が原因のことがあります。
ecsub は AWS CloudWatch にインスタンスメトリクスを保存していますので、以下のようにしてアクセスします。

AWS CloudWatch > メトリクス > ECSUBを選択

さらに ClusterName, InstanceId を選択 > 表示したいメトリクスにチェック

インスタンス名は「{タスク名}-{user}-{日付}-{ID}」の構成になっています。
ID は GenomonPipelineCloud 実行時に作成したsample.csv 該当セクションの記入順に0から割り振られています。

制限事項

開発中のため、以下内容で既存のGenomonPipeline (v2.5.3) との機能差があります。

コントロールパネルに未対応
アノテーションを付与に未対応
解析結果のマージ機能に未対応
途中で止めて再開した時、すでに終了しているステージをスキップできない