README.md
In DrRes/jobwatcher: Build pipelines on HGC super-computer

jobwatcher

Human Genome Center(HGC)スパコンおよびその基となるUniva Grid Engine(UGE)のコマンドをRから実行するRパッケージです(非公式). {tidyverse}パッケージをベースにしており, 結果をtibble形式で得ることができます. また, watch関数を使えばqsubおよびqrecallしたジョブを監視し, 予期しないエラーが出た場合はqsubないしqrecallし直すことができます. {drake}パッケージをインストールすることでHuman Genome Center(HGC)スパコンでのパイプライン構築に使うことができます.

インストールには, 次のコマンドを実行してください.

if (!requireNamespace("devtools", quietly = TRUE)) install.packages("devtools")
devtools::install_github("drres/jobwatcher")
library(jobwatcher)

現在, qsub, qrecall, qreport, qacct, qstat関数をサポートしています. 実行環境がHuman Genome Center(HGC)スパコンまたはUniva Grid Engine(UGE)かどうかを内部で判定しており, 環境によって挙動が異なります. qsubおよびqrecall関数はUGE環境でなくとも使うことができます. その場合, qsubは指定したファイルをsystem関数を用いてshで実行します. (もし一行目冒頭に#!が記述されている実行可能ファイルであった場合はbashを介さず直接実行します.) また, qrecallはHGC環境以外ではアクティブな変更を何も加えません.

| functions | HGC | UGE | Other | |:----------|:-----------|:------------|:--------------------------| | qsub | qsub | qsub | send commands to terminal | | qrecall | qrecall | (no effect) | (no effect) | | qreport | qreport | (error) | (error) | | qacct | qreport -c | qacct | (error) | | qstat | qstat | qstat | (error) |

現在の実行環境がどのように判定されたかを確認するには, これらの関数を1度でも実行した後にoptions(jobwatcher.mode)を実行してください.

watch関数はqsubおよびqrecallしたジョブを監視し, 予期しないエラーが出た場合は指定したファイルをqsubないしqrecallし直す関数です. 監視にはqreportコマンドを利用しているため, ジョブの結果を取得するまでに実際のジョブの終了から数分程度の遅れが生じる可能性があります. 現在はHGC環境でのみ動作します.

また, qsubおよびqrecall関数にはwatch引数をとることができ, TRUEにすることでwatch関数を明示的に使わずともqsubないしqrecallしたジョブを監視することができます. qsub関数をUGE環境でなく使用した場合, watch = TRUEの指定はsystem関数でwait = TRUEとすることに相当します.

make_qsubfileを使用することで, qsub用に適したリソースの指定を手軽に行えるようになります. (SHIROKANE5への移行により,#$ -l os7などのOS指定が追加で必要になる場合が出てきました. 残念ながら専用の引数を用意していないため, other_req = "#$ -l os7"またはfirst_line = paste(binbash(), "\n#$ -l os7")などのように指定してください.)

また, write_qsubfileを使用すればスクリプトファイルのパスに書き込み時刻を含めることができます. パイプライン中でよく似たファイルを自動で複製作成する場合などに, それぞれのファイル名を(ほぼ)一意にすることに使えます.

qsub_function関数はqsubを行う関数を作成する関数です. 作成された関数を実行することでパイプラインの各qsub操作を行うことができます. パイプライン作成部分は{drake}パッケージベースです. {drake}パッケージの日本語での説明はこちらの匿名技術者集団の解説がわかりやすいです. {drake}パッケージはパイプラインを関数ベースで記述するため, qsub_functionを使ってパイプラインを構築していきます. 簡単な構築例はbuild_pipeline関数で得ることができます. 適宜編集してお使いください.

build_pipeline("your_pipeline_name", "~/your_pipeline_path")
#> ✔ Directory '~/your_pipeline_path' has been created.
#> 
#> ✔ Directory '~/your_pipeline_path/log' has been created.
#> 
#> ✔ Directory '~/your_pipeline_path/script' has been created.
#> 
#> ✔ Directory '~/your_pipeline_path/config' has been created.
#> 
#> ✔ File '~/your_pipeline_path/your_pipeline_name.sh' has been written.
#> 
#> ✔ File '~/your_pipeline_path/your_pipeline_name.R' has been written.
#> 
#> ● Please edit '~/your_pipeline_path/your_pipeline_name.R' for your own pipeline.
#> 
#> ● Then, run qsub ~/your_pipeline_path/your_pipeline_name.sh
#>

qsub_functionで作成される関数は動作に影響を与えないダミー変数を引数にとります. ここにパイプラインの他の操作を記入することで, {drake}の機能のおかげで記入された操作がすべて完了してからその操作が実行されるようになります.

上述の通りqsubおよびqrecall関数はUGE環境でなくとも使うことができるため, #$によるリソースの指定はできませんが, デスクトップ環境でも構築したパイプラインを動かすことができます. パイプラインをデスクトップ環境で構築・テストし, UGE環境にpushするといった使い方が可能です.