WDL(Workflow Description Language) を使ってみた。

Broad Institute が開発したワークロード記述言語, WDL をインストールして使ってみました。日本語の記事が無いようだったので、作業メモを書いていきます。

1. 準備

まずインストールされているjava のバージョンを確認します。

GATK のインストールのガイドにあるように、最新のGATK 3.6 をサポートしているJava Runtime Environment(JRE) のバージョンは1.8です。コマンドラインで、

$ java -version

の返り値が1.8系でなかった場合、1.8系のJREを別途インストールする必要があります。Oracle のページから自分の環境に合わせたJRE1.8系をダウンロード & インストールしましょう。

ちなみに私の環境はMac OS X(10.12.5, Sierra) なのですが、Oracle から落としてきたJRE1.8 をインストールしても、コマンドラインのjava -version の返り値が1.6のままで変化せず、ちょっと困りました。
ググってみると、Oracle のjava は、/usr/bin ではなくて、別のディレクトリにインストールされていて、明示的にPATH を変えてやらないとそちらが参照されないようです。
以下のようにPATH にインストールしたディレクトリを指定してやれば、コマンドラインから1.8のjava が使えるようになりました。

$ export PATH=/Library/Internet\ Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/bin:$PATH

ご参考までに。今後も使っていく場合は、.bashrc あたりに書いておきましょう。

次に、いくつかJava のjar ファイルをダウンロードします。必要なjar ファイルは3つです。

• wdltool-xxx.jar

WDL を記述したり、実行したりする際のUtility パッケージになります。最新のバージョンは0.12で、こちらからDownload できます。
Utility の全部は試していないのですが、どんなUtility が収録されているのかはヘルプを読むとわかります。

$ java -jar wdltool-0.12.jar -h

• cromwell-xxx.jar

WDL を実行するためのエンジンです。最新のバージョンは28でした。
最新のファイルはこちらからDownload できます。WDLを利用する上では必須のファイルになります。同じように-h でヘルプを見ることができます。

• GenomeAnalysisTK.jar

ワークロード記述言語WDL 自体の勉強であれば、対象となるワークロードは自作ソフトウエアでも、Linux 標準コマンドでもいいので、GATK は必要ないのですが、公式サイトにあるTutorial は、GATK を題材にして進められています。

GATK は各種のゲノム解析ソフトウェアの詰め合わせで、説明しようとするとそれだけで大作の記事になってしまうので、今回は割愛します。公式Webページや、各種解説記事を参照下さい。最新のバージョンは3.7-0 で、こちらからDownload できます。
ダウンロードした、bz2 ファイルを以下のコマンドで解凍します。

$ tar xjf GenomeAnalysisTK-3.3-0.tar.bz2 

解凍後に得られたGenomeAnalysisTK.jar が本体です。ヘルプは "-h" ではなく、"--help" を使います。

$ java -jar GenomeAnalysisTK.jar --help

2. エディタ

WDL を勉強する上で、シンタックスハイライトがあればうれしいですね。Broad Institute から、Sublime Text というエディタ向けのシンタックスハイライト用プラグインが提供されています。

Sublimeは、名前は知っていたのですが使ったことがなかったので、今回試してみました。軽量でなかなかいい感じです。Sublime Text 自体はこちらからダウンロードできます。

WDL 用のプラグインのありかはこちらです。ReadMe に具体的な設定方法は記載されていますが、ダウンロードしたWDL.tmLanguage を、

~/Library/Application Support/Sublime Text 3/Packages/WDL Syntax Highlighting

ディレクトリに配置するだけです。

3. WDLスクリプトを書く

今回は、もっとも単純なワークロードとして、Linux コマンドでみなさんお馴染みの、"ls" を、無駄にWDL の枠組みで実行してみます。

WDLのスクリプトの基本は下記の公式資料の図のとおりです。

まず、ワークフロー名をmudani_ls とし、ワークフローの中でexec_ls というタスクを実行することとします。次にタスクの記述ですが、再び公式資料の図を拝借すると次のようになっています。

実行するコマンドは

$ ls -l input_file_name > output_file_name

として、lsコマンドの結果をファイルに出力するものとします。

以上を、WDLスクリプトに書くと以下のようになります。

mudani_ls.wdl

workflow mudani_ls {
        call exec_ls
}

task exec_ls {
        String FileName
        String OutputFileName

        command {
                ls -l ${FileName} > ${OutputFileName}
        }
        output {
        	File lsOutput = "${OutputFileName}"
        }
}

"task" には、入力ファイル, 出力ファイル, コマンドライン引数などを記述できます。上記の簡単な例では、ls コマンドに与えるファイル名を文字列(String) で与えています。また、コマンドの結果をリダイレクトしてファイルに保存していますが、この際の出力ファイル名も同様に文字列(String)で指定しています。

さて、このmudani_ls.wdlスクリプトですが、実行の際の入力パラメータは、json ファイルに記述し、そのjson ファイルをWDLスクリプトとともに実行エンジンに与えます。

それでは、そのjson ファイルを記述しましょう。
最初から手で書いてもいいのですが、Utility (wdltool-xxx.jar) にテンプレートを自動で作ってくれる機能がありますので、そちらを使ってみます。

$ java -jar wdltool-0.12.jar inputs mudani_ls.wdl > mudani_ls_input.json

リダイレクト先のファイル名は任意です。エディタでmudani_ls_input.json を開いてみると、次のようになっているはずです。

mudani_ls_input.json

{
  "mudani_ls.exec_ls.FileName": "String",
  "mudani_ls.exec_ls.OutputFileName": "String"
}

ここで"String" に適当な名前を記述すればいいわけです。例えば次のように編集します。

mudani_ls_input.json(編集後)

{
  "mudani_ls.exec_ls.FileName": "/Users/asahara/WDL/mudani_ls.wdl",
  "mudani_ls.exec_ls.OutputFileName": "ls_output"
}

これで一通り準備が整いました。

4. Validation

帰宅際に仕掛けたパイプラインスクリプトが、翌朝単純なエラーでこけていた。。。という悲しい経験は誰にもあるものです。
WDL では、Utiltiyに、自分の書いたWDL スクリプトに文法的な問題がないか、確認するためのツールが入っています。今回のテストのようなls コマンドは、いきなり実行しても問題ないのですが、練習も兼ねて、一応、実行前に文法のチェックをしておきましょう。

以下のようなコマンドで確認を行います。

$ java -jar wdltool-0.12.jar validate mudani_ls.wdl

文法的に問題があれば、Error メッセージがでますので、修正して下さい。

5. 実行

いよいよ実行してみましょう。実行コマンドは下記のとおりです。

$ java -jar cromwell-28.jar run mudani_ls.wdl mudani_ls_input.json

実行すると、ずらずらとWDLエンジンのログが標準出力されます。ls をしたいだけなのですが、私の環境では17秒ほどかかりました(笑)。特に問題なければ、最後に'Succeeded' の文字が見えるはずです。こんな感じです。

[2017-07-16 04:43:14,21] [info] SingleWorkflowRunnerActor workflow finished with status 'Succeeded'.
{
  "outputs": {
    "mudani_ls.exec_ls.lsOutput": "/Users/aki/WDL/cromwell-executions/mudani_ls/ac7c0153-c64f-4cf0-824d-591b5decc45c/call-exec_ls/execution/ls_output"
  },
  "id": "ac7c0153-c64f-4cf0-824d-591b5decc45c"
}

もし、Fail のメッセージがでていたら、どこかにミスがあります。ログのエラーメッセージを追ってみて下さい。

得られた出力ファイルは/Users/aki/WDL/cromwell-executions/mudani_ls/ac7c0153-c64f-4cf0-824d-591b5decc45c/call-exec_ls/execution/ls_output にあります。WDLスクリプト名(mudani_ls)の後のディレクトリ名はハッシュ値になっていて、実行の度にユニークな値が割り振られます。これにより、実行結果をふいに上書きしてしまうようなことはありません。

6. さらに先に進むために

公式Webサイトには、GATK を題材にしたTutorial (https://software.broadinstitute.org/wdl/documentation/topic?name=wdl-tutorials) が掲載されています。上記までの簡単な動作確認が完了したら、このTutorial を進めるのが良さそうです。

流石にもうちょっと複雑なワークフローでないと、このようなツールを使う意味がないですからね。。。

ではまた！