paplot documentation¶

Contents:

quick start¶

paplotをインストール
testサンプルでコマンドを実行
結果ファイルを表示

1. paplotをインストール¶

ここでうまくいかない方、個人のPCにインストールする方は install を参照してください。

HGCスパコンで使用する場合、事前に qlogin してください。

git clone -b master https://github.com/Genomon-Project/paplot.git
cd paplot

python setup.py build install --user

installの確認

以下を入力してください。

pa_plot conf

このように表示されればインストール成功です。

**********************
   hello paplot !!!
**********************

config file:/usr/lib/python2.7/site-packages/paplot-0.2.6devel-py2.7.egg/config/paplot.cfg
[genome]
('path', '')
[style]
('path', '')
[sv]
('use_chrs', '1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,X,Y')
('snippet_threshold', '1000')
(このあとにデフォルト設定の内容が表示されます)

2. testサンプルでコマンドを実行¶

テストサンプルを用意していますので実行します。

cd {paplotをインストールしたディレクトリ}

# create bar graphs of qc
pa_plot qc "example/qc/*.csv" ./tmp DUMMY --config_file example/example.cfg

# create bundle graphs of Structural Variation (SV)
pa_plot sv "example/sv/*.txt" ./tmp DUMMY --config_file example/example.cfg

3. 結果ファイルを表示¶

次の場所にHTMLファイルが2つできていますか？

{paplot をインストールしたディレクトリ}
  └ tmp
      ├ DUMMY
      │   ├ graph_qc.html     <--- qc グラフ
      │   └ graph_sv.html     <--- sv グラフ
      │
      ├ js          <--- この3つのディレクトリはHTMLファイルを表示するために必要です。消さないでください。
      ├ lib
      └ style

HTMLファイルを web ブラウザで開いてください。

※HGCスパコン等、サーバ上で実行した場合はファイルをローカルに転送するか、サーバ上の仮想ウィンドウ(NoMachime等)で表示してください。

ローカルに転送する場合は、tmp ディレクトリを丸ごとコピーしてください。

次のように見えていますか?

それぞれのグラフの使い方は How to use を参照してください。

QC グラフ¶

qcグラフではbamファイルの品質をグラフに表示します。

先頭の背の低いグラフはbamファイルごとのdepth 平均です。
このグラフを範囲選択することで他のグラフの拡大ができます。
それぞれのグラフではマウスを乗せると詳細を表示します。

SV グラフ¶

svグラフでは検出したstructural variation (SV) について棒グラフと円形のグラフで表示します。

棒グラフでは全サンプルでbreakpointを集計した数を表示します。
円形のグラフでは、サンプルごとにbreakpoint1と2を線でつないで表示します。

棒グラフを選択すると選択されたgenome領域にbreakpointを持つサンプルが選択されます。
選択方法は「ハイライト」と「選択したもののみ表示（他を隠す）」の2とおりあり、先頭のオプションボタンで選択できます。

棒グラフを構成する要素は2つあり、SV が chromosome を超えて発生しているか、もしくは同一 chromosome 内で発生しているかで色を分けています。
チェックを外すと、その要素は表示されません。

サンプルごとの円形のグラフをクリックすると拡大表示します。
breakpointをつなぐ線の上にマウスを乗せると詳細を表示します。

install¶

paplotは次のマシンで動作します。

Linux系サーバ (HGCスパコン含), Linux ディストリビューション

MacOS X

Windows

paplotを実行するにはpython 2.7 もしくはpython 3 が必要です。
(python 2.6 は未検証)

Linux系の場合 (HGCスパコン, cygwin含)

MacOS Xの場合

Windowsの場合

Linux系の場合 (HGCスパコン, cygwin含)¶

1. paplot のインストール¶

cd {install したいディレクトリ}
git clone -b master https://github.com/Genomon-Project/paplot.git
cd paplot

python setup.py build install

# 上のコマンドでエラーが出る場合
export PATH=~/.local/bin/:$PATH
export LD_LIBRARY_PATH=~/.local/lib/:$LD_LIBRARY_PATH
python setup.py build install --user

正しくインストールされたか確認します。

pa_plot conf
**********************
   hello paplot !!!
**********************

(デフォルト設定値が表示される)

このような表示が出れば成功です。

インストールが終わったら、quick start をお試しください。

注釈

PATH設定を忘れないようにする

↑でexport設定したPATHとLD_LIBRARY_PATHはログアウトすると忘れてしまいます。
再ログイン時に再設定されるよう設定ファイルに記入しておくことをお勧めします。
~/.bashrc もしくは ~/.bash_profile ファイルに次の2行を記入してください。

export PATH=~/.local/bin/:$PATH
export LD_LIBRARY_PATH=~/.local/lib/:$LD_LIBRARY_PATH

MacOS Xの場合¶

1. ソースファイルのダウンロード¶

paplotのサイトから最新版の Source code (zip) をダウンロードします。

https://github.com/Genomon-Project/paplot/releases/

git コマンドが使える方は git clone -b master https://github.com/Genomon-Project/paplot.git でもよいです。

2. paplot のインストール¶

ターミナルを起動してダウンロードしたディレクトリに移動します。

「ターミナル.app」がDockの中にない場合、次からたどることができます。
Finder → 「移動」メニュー → 「アプリケーション」を選択 → 「ユーティリティ」ディレクトリを開く → 「ターミナル」を起動

<user name>は自分のユーザ名です。
whoami コマンドで確認できます。

cd {downloadしたディレクトリ}
# 大抵は以下でOKです。
# cd /Users/<user name>/Downloads/paplot-devel

インストールします。

python setup.py build install --user

3. PATHの設定¶

このままではターミナルは pa_plot がどこにあるかわからないので、インストールされているところにPATHを通します。
大抵、ここにあります。

/Users/<user name>/Library/Python/2.7/bin

注釈

ここにない場合は find / -name pa_plot とコマンドを入力してインストールされているところを探します。

4つ見つかるはずです。
このうち、downloadしたディレクトリは使用しません。

{installしたディレクトリ}/bin/pa_plot               <--- ココです
{installしたディレクトリ}/lib/python2.7/site-packages/paplot-0.2.6devel-py2.7.egg/EGG-INFO/scripts/pa_plot
{downloadディレクトリ}/paplot-devel/pa_plot
{downloadディレクトリ}/paplot-devel/build/scripts-2.7/pa_plot

export PATH={installしたディレクトリ}/bin:$PATH
export LD_LIBRARY_PATH={installしたディレクトリ}/lib:$LD_LIBRARY_PATH

# 大抵は以下でOKです。
# <user name>は自分のユーザ名に置き換えてください。
# export PATH=/Users/<user name>/Library/Python/2.7/bin:$PATH
# export LD_LIBRARY_PATH=/Users/<user name>/Library/Python/2.7/lib:$LD_LIBRARY_PATH

正しくインストールされたか確認します。

pa_plot conf
**********************
   hello paplot !!!
**********************

(デフォルト設定値が表示される)

このような表示が出れば成功です。

インストールが終わったら、quick start をお試しください。

注釈

PATH設定を忘れないようにする

↑で設定したPATHは再起動すると忘れてしまうので、
起動するたびに export PATH=... コマンドを入力する必要があります。
ここでは、起動しても自動的に再設定されるようにします。

設定ファイルを作成します。

vi ~/.bash_profile

ファイルが開いたら i と入力して編集モードにします。
ファイルにすでに何か記入されていたら ↓ キーで最後の行に移動します。

<user name>は自分のユーザ名です。

export PATH=/Users/<user name>/Library/Python/2.7/bin:$PATH
export LD_LIBRARY_PATH=/Users/<user name>/Library/Python/2.7/lib:$LD_LIBRARY_PATH

PATHの設定で入力したものと同じパスを入力してください。
入力したら ESC キーを押して、編集モードから抜けます。その後、:wq と入力して保存して終了します。

Windows系の場合¶

1. Pythonのインストール¶

winPython もしくはPython(x,y)をインストールするのが手軽だと思います。
cygwinでも動きます。
cygwinの場合は Linux系の場合 (HGCスパコン, cygwin含) を参照してください。

winPython http://winpython.github.io/

Python(x,y) http://python-xy.github.io/

python 2.7.10 と python 3.5.1 は動作確認済みです。

2. paplot のインストール¶

paplotのサイトから最新版の Source code (zip) をダウンロードします。
ダウンロードしたファイルは適当なフォルダに解凍します。

https://github.com/Genomon-Project/paplot/releases/

インストールしたフォルダにコマンドプロンプトがありますので、起動します。
WinPython-64bit-3.5.1.2 を標準でインストールした場合、ここにあります。

C:\\Program Files\\WinPython-64bit-3.5.1.2\\WinPython Command Prompt.exe

起動した画面に以下を入力します。

cd {zipを解凍したフォルダ}
python setup.py build install

Windowsの場合、 pa_plot コマンドにパスが通っていないのでバッチファイルを使用します。
zipを解凍したフォルダに pa_plot.cmd がありますので、ノートパッド等テキストエディタで開いて編集します。

set pa_plot="C:\Program Files\WinPython-64bit-3.5.1.2\python-3.5.1.amd64\Scripts\pa_plot"

pa_plotの実際の場所を記入してください。
数字はインストールしたpythonのバージョンにより変化します。

編集したバッチファイルをpythonコマンドプロンプトと同じフォルダにコピーします。

pythonコマンドプロンプトで、先ほど作成したバッチファイルを実行します。

>pa_plot.cmd conf
**********************
   hello paplot !!!
**********************

(デフォルト設定値が表示される)

このような表示が出れば成功です。

注意：Windows標準のコマンドプロンプトでは動作しません。
必ずPythonのコマンドプロンプトを使用してください。

以降、pa_plot コマンドは pa_plot.cmd と読み替えてください。

インストールが終わったら、quick start をお試しください。

pa_plot コマンド¶

1. コマンドオプション¶

pa_plot {qc, sv} [-h] [--version] [--config_file CONFIG_FILE] [--remarks REMARKS] input output_dir project_name

必須

{qc, sv}

paplotのサブコマンドです。どちらかを選択します。
input

入力ファイルです。ワイルドカード (*) を使用して複数指定することができます。最初と最後に " をつけてください。
output_dir

出力ディレクトリを指定します。ディレクトリ構成は 2. 出力ディレクトリを参照してください。
project_name

プロジェクト名です。出力ファイルのタイトルに使用します。

任意

--config_file

設定ファイルです。未指定の場合、デフォルトを使用します。
--remarks

index.htmlの備考欄に出力するテキストです。未指定の場合、設定ファイルの値を使用します。

その他

-h

ヘルプを表示します。
--version

バージョンを表示します。

2. 出力ディレクトリ¶

output_dir オプションで指定した場所に次の構成でファイルを出力します。

{output_dir}
  ├ {project_name}
  │   ├ graph_qc.html     <--- qc グラフ
  │   └ graph_sv.html     <--- sv グラフ
  │
  ├ js          <--- この3つのディレクトリはHTMLファイルを表示するために必要です。消さないでください。
  ├ lib
  ├ style
  │
  └ index.html             <--- index このファイルをブラウザで開いてください。

出力ファイルを移動する場合は {output_dir} ごと移動してください。

出力ファイルの操作方法は QC グラフ を参照してください。

自分のデータを使用する¶

自分のデータを使用するにはconfigファイルを編集して自分のファイルフォーマットを指定します。

configファイルのサンプルは以下にあります。

{paplotをインストールしたディレクトリ}/example/example.cfg

[genome]
# ゲノムサイズのファイル（CSV形式）（デフォルトはhg19, installディレクトリ配下のgenomeディレクトリにあります）
#
# for example.
# (linux)
# path = ~/tmp/genome/hg19.csv
# (windows)
# path = C:\genome\hg19_part.csv
path =

[style]
# グラフのレイアウトファイル
# ~/tmp/paplot/style/rainbow.js
path =

# index.html の備考欄に出力するテキスト(HTMLタブ使用可)
remarks =

[sv]
# 使用するchromosomes (,で区切る)
use_chrs = 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,X,Y

[qc]
# qcでどのグラフを表示するか (表示しない場合Falseにする)
chart_coverage=True
chart_average=True
chart_mapped=True
chart_insert=True
chart_duplicate=True
chart_length=True

[result_format_sv]
# sv の入力ファイルフォーマット

# suffix (col_pos_IDが指定されていない場合、ファイル名のsuffixより前をIDとする)
suffix = .result.txt

# データ区切り(タブ区切りの場合)
sept = \t
# ,区切りの場合
sept = ,
# スペース区切りの場合
sept = " "

# 先頭1行がヘッダかどうか (先頭行がヘッダの場合はTrue)
header = False

# 先頭に指定文字がある行は飛ばす
comment = #

##### データ列の位置
# ヘッダ行がある場合、カラム名 (テキスト) を入力する
# ヘッダ行がない場合、カラムインデックス (数値) を入力する

# 必須
col_chr1 = Chr_1
col_break1 = Pos_1
col_chr2 = Chr_2
col_break2 = Pos_2

# 任意
col_opt_dir1 = Dir_1
col_opt_dir2 = Dir_2
col_opt_type = Variant_Type
col_opt_gene_name1 = Gene_1
col_opt_gene_name2 = Gene_2

[result_format_qc]
# qc の入力ファイルフォーマット
# (svとほぼ同)

suffixとID

列と設定の対応¶

SVの場合

name	input type	required	description
col_chr1	text	o	chromosome of break point 1
col_break1	numeric	o	position of break point 1
col_chr2	text	o	chromosome of break point 2
col_break2	numeric	o	position of break point 2
col_opt_ID	text	x	サンプルを識別できる名称
col_opt_dir1	text	x	direction of break point 1
col_opt_dir2	text	x	direction of break point 2
col_opt_type	text	x	type of variation
col_opt_gene_name1	text	x	gene name of break point 1
col_opt_gene_name2	text	x	gene name of break point 2

注釈

任意設定の5項目はポップアップでの詳細表示にのみ使用されます。

col_opt_dir1

col_opt_dir2

col_opt_gene_name1

col_opt_gene_name2

col_opt_type

QCの場合

name	input type	required	description
col_total_reads	numeric	o	number of total reads
col_mapped_reads	numeric	o	number of mapped reads
col_duplicate_reads	numeric	o	number of duplicate reads
col_mean_insert_size	numeric	o	mean of insert size
col_average_depth	numeric	o	average of depth
col_read_length_r1	numeric	o	number of read_length_r1
col_read_length_r2	numeric	o	number of read_length_r2
col_ratio_2x	0.0～1.0	o	coverage (depth=2)
col_ratio_10x	0.0～1.0	o	coverage (depth=10)
col_ratio_20x	0.0～1.0	o	coverage (depth=20)
col_ratio_30x	0.0～1.0	o	coverage (depth=30)
col_opt_ID	text	x	サンプルを識別できる名称

作成したconfigファイルは pa_plot コマンドの --config_file オプションで指定します。

実行例

pa_plot qc "example/qc/*.csv" ./tmp DUMMY --config_file example/example.cfg

グラフをカスタマイズする¶

1. 変更方法¶

色やテキストなど、グラフの見た目はある程度変更することができます。

サンプルデータを用意していますので変更してみます。

1-1. スタイルファイルを編集する¶

{paplotをインストールしたディレクトリ}/example/default.js

このファイルをコピーして {paplotをインストールしたディレクトリ}/example/mystyle.js というファイルを作成します。

※ファイル名は任意ですが、拡張子は .js にしてください。

作成したファイルを開いて次の箇所を変更します。

今回はqcグラフのcoverage グラフの色を変更します。

// 7行目
// 変更前
bar_coverage_color: [
  "#1F77B4", // ratio_30x
  "#FF7F0E", // ratio_20x
  "#2CA02C", // ratio_10x
  "#D62728", // ratio_2x
],

// 変更後
 bar_coverage_color: [
  "blue",    // ratio_30x
  "pink",    // ratio_20x
  "#CCFF66", // ratio_10x
  "#330066", // ratio_2x
],

注釈

色の指定はRGBもしくは色名で指定することができます。

// RGBで指定する場合
bar_select_color: "#1F77B4",
// color nameで指定する場合
bar_select_color: "red",

RGBで指定する場合

Red → Green → Blueの順に 00～FF まで、6桁の16進表記で指定し、先頭に # をつけてください。

色名(カラーネーム)について

UNIX X11カラーといい、わかりやすくするために140色に名称がついています。
ここで定義されている色名であれば、RGB値の代わりに指定することができます。

https://www.w3.org/TR/css3-color/#svg-color

1-2. 設定ファイルを編集する¶

{paplotをインストールしたディレクトリ}/example/example.cfg

このファイルを開いて次の箇所を変更します。

スタイルファイルを今回作成したものを使用するように変更します。

[style]
path = {paplotをインストールしたディレクトリ}/example/mystyle.js

# ~/tmpにインストールした場合はこのようになる
# ~/tmp/paplot/example/mystyle.js

1-3. 出力する¶

cd {paplotをインストールしたディレクトリ}
pa_plot qc "example/qc/*.csv" ./tmp STYLE --config_file example/example.cfg

作成されたHTMLファイルをブラウザで開いてください。

次のようにQCのcoverageグラフの色が変更されていますか？

1-4. 出力されたファイルを変更する¶

上で作成したファイルは次のディレクトリにコピーされています。

すでにpaplotで出力したHTMLファイルを変更する場合、スタイルファイル (mystyle.js) を編集し、再読み込み(ブラウザで F5 )すれば反映されます。

./tmp
  ├ STYLE
  │   ├ graph_qc.html
  │   └ graph_sv.html
  │
  ├ js
  ├ lib
  └ style
      ├ default.js     <--- デフォルト
      └ mystyle.js     <--- 今回作成したファイル

2. qcグラフ¶

スタイルの対応は次の通りです。

3. sv (サムネイル)¶

スタイルの対応は次の通りです。

linkのテンション(張り具合)について、設定値と見た目は次の通りです。

linkの透過度について、設定値と見た目は次の通りです。

4. sv (詳細表示)¶

スタイルの対応は次の通りです。

5. sv (グラフ)¶

スタイルの対応は次の通りです。

about install¶

`pa_plot conf` でエラー¶

PATH もしくは LD_LIBRARY_PATH の設定が不足しているときにおこります。
install を確認してください。

このようなエラーの場合、PATH の設定が正しくありません。

$ pa_plot conf
-bash: /usr/bin/pa_plot: No such file or directory

このようなエラーの場合、LD_LIBRARY_PATH の設定が正しくありません。

$ pa_plot conf
Traceback (most recent call last):
  File "/usr/bin/pa_plot", line 4, in <module>
    __import__('pkg_resources').run_script('paplot===0.2.7devel', 'pa_plot')
(省略)
pkg_resources.DistributionNotFound: The 'paplot===0.2.7devel' distribution was not found and is required by the application

pa_plot ファイルがない場合はインストールが成功していない可能性があります。
成功した場合は最後の3行がこのように表示されます。
paplot-0.2.7の数字はバージョンによって変化します。

$ python setup.py build install

(最後の3行)
Installed /usr/lib/python2.7/site-packages/paplot-0.2.7devel-py2.7.egg
Processing dependencies for paplot===0.2.7devel
Finished processing dependencies for paplot===0.2.7devel

about graphs¶

グラフを画像で保存したい¶

画像で保存する機能はありません。
ブラウザやOSに付属のスクリーンショットで代用ください。

スクリーンショットでを作成するには以下のようなアプリケーションがあります。

1. ブラウザのアドオンを使用する。

代表的なアドオン

firefox ... Screengrab

chrome ... Full Page Screen Capture

1. OS 標準アプリケーション

Windows ... Snipping Tool (「スタート」→「すべてのプログラム」→「アクセサリ」→「Snipping Tool」)

MacOSX ... グラブ (Finder → 「移動」メニュー → 「アプリケーション」を選択 → 「ユーティリティ」ディレクトリを開く → 「グラブ」)

グラフの色が黒くなる¶

設定が不足していると黒色で表示されます。
styleファイルで該当する項目を設定してください。


デフォルトのままであれば、styleファイルは {html出力ディレクトリ}/style/default.js にあります。
該当する項目は グラフをカスタマイズする で確認してください。

svでchr10の設定が不足している例。

SVで表示するchromosomeを限定するにはどうしたらよいか¶

configファイルで次の項目を編集してください。

[sv]
# 使用するchromosomes (,で区切る)
# default
# use_chrs = 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,X,Y

# chromosome 1,5,7を使用する場合
use_chrs = 1,5,7

編集したconfigファイルは次のようにしてコマンドから指定します。

pa_plot {input files} {output directory} {title} --config_file {config file}

SVでヒト以外のゲノムを使用するにはどうしたらよいか¶

genomeサイズが入力されたファイルが必要です。

先頭列にchromosome名、2列目にサイズをカンマ , 区切りで入力してください。

1,249250621
2,243199373
3,198022430
7,159138663
8,146364022
X,141213431
Y,135534747
9_gl000201_random,36148
11_gl000202_random,40103
17_gl000204_random,81310
17_gl000205_random,174588
Un_gl000214,137718

chromosome名は分析したいファイルのChr1, Chr2で使用されている名称と同じでなければなりません。

configファイルで用意したゲノムサイズのファイルを指定してください。

[genome]
# ゲノムサイズのファイル（CSV形式）（デフォルトはhg19, installディレクトリ配下のgenomeディレクトリにあります）
#
# for example.
# (linux)
# path = ~/tmp/genome/hg19.csv
# (windows)
# path = C:\genome\hg19_part.csv
path = {ここにゲノムサイズのファイルのパスを指定する}

編集したconfigファイルは次のようにしてコマンドから指定します。

pa_plot {input files} {output directory} {title} --config_file {config file}

Javascript Libraries¶

paplot は次のjavascript パッケージを使用しています。

D3.js
dc.js

paplot documentation¶

quick start¶

1. paplotをインストール¶

2. testサンプルでコマンドを実行¶

3. 結果ファイルを表示¶

QC グラフ¶

SV グラフ¶

install¶

Linux系の場合 (HGCスパコン, cygwin含)¶

1. paplot のインストール¶

MacOS Xの場合¶

1. ソースファイルのダウンロード¶

2. paplot のインストール¶

3. PATHの設定¶

Windows系の場合¶

1. Pythonのインストール¶

2. paplot のインストール¶

pa_plot コマンド¶

1. コマンドオプション¶

2. 出力ディレクトリ¶

自分のデータを使用する¶

列と設定の対応¶

グラフをカスタマイズする¶

1. 変更方法¶

1-1. スタイルファイルを編集する¶

1-2. 設定ファイルを編集する¶

1-3. 出力する¶

1-4. 出力されたファイルを変更する¶

2. qcグラフ¶

3. sv (サムネイル)¶

4. sv (詳細表示)¶

5. sv (グラフ)¶

about install¶

pa_plot conf でエラー¶

about graphs¶

グラフを画像で保存したい¶

グラフの色が黒くなる¶

SVで表示するchromosomeを限定するにはどうしたらよいか¶

SVでヒト以外のゲノムを使用するにはどうしたらよいか¶

Javascript Libraries¶

`pa_plot conf` でエラー¶