_images/genomon_kun.png

paplot documentation

Contents:

はじめに

paplotはゲノム解析結果を自動でグラフ化するツールです。

ゲノムを解析して、このようなテキストファイルができたとします。
_images/mutation_list.PNG
このあと何をしますか?
グラフを作成しないでしょうか?
毎回手動で作成したり、似たようなスクリプトを書いていたりしないでしょうか?
データの抽出条件、ソート条件を変えて再度グラフを作成していないでしょうか?

paplotはこの作業を自動化して、皆さんのゲノム解析を少しだけ楽にする…かもしれません。

作成できるグラフ

  1. QC グラフ

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

_images/qc_dummy.png
  1. SV グラフ

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

_images/sv_dummy.png
  1. mutation-matrix グラフ

検出したmutation について縦軸を遺伝子(Gene), 横軸をサンプル(Sample) として、変異タイプ別に表示します。

_images/mut_dummy.png

quick start

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

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

# create bundle graphs of Structural Variation (mutation-matrix)
pa_plot mutation example/mutation/sample_merge.csv ./tmp DUMMY --config_file example/example.cfg

3. 結果ファイルを表示

HTMLファイルができていますか?

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

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

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

QC グラフ
_images/qc_dummy.png
SV グラフ
_images/sv_dummy.png
mutation-matrix グラフ
_images/mut_dummy.png
それぞれのグラフの使い方は How to use を参照してください。

QC グラフ

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

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

SV グラフ

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

  • 棒グラフでは全サンプルでbreakpointを集計した数を表示します。
  • 円形のグラフでは、サンプルごとにbreakpoint1と2を線でつないで表示します。
棒グラフを選択すると選択されたgenome領域にbreakpointを持つサンプルが選択されます。
選択方法は「ハイライト」と「選択したもののみ表示(他を隠す)」の2とおりあり、先頭のオプションボタンで選択できます。

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

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

_images/sv_operation3.PNG

mutation-matrix グラフ

mutation-matrix グラフでは検出したmutation について縦軸を遺伝子(Gene), 横軸をサンプル(Sample) として、変異タイプ別に表示します。

横長の棒グラフ(Sample):
 

サンプルごとに検出されたmutationの数を表示します。

縦長の棒グラフ(Gene):

遺伝子ごとのmutation数をサンプル数における割合(%)で表示します。

  • 同一のサンプルが同じ遺伝子に対して複数のmutationを持っていた場合、mutation数を1としてカウントします。
  • 同一のサンプルが同じ遺伝子に対して複数の変異タイプを持っていた場合、優先順位の高い変異タイプにカウントします。
functions:

変異タイプ(func)別に色分けして表示します。表示したくない変異タイプがある場合、functions のチェックボックスからチェックを外すことで除外できます。

sub plot:

mutationとは別にサンプルに対するデータがある場合、subplotとして表示することができます。このファイルは pa_plot コマンド実行前に設定ファイルに記入しておく必要があります。

_images/mut_operation1.PNG

操作方法

_images/mut_operation2.PNG

1. axis-X sort

横軸の並び順を変更します。

  • none ソートしない
  • ASC 昇順
  • DESC 降順

以下の要素でソートでき、複数ソート可能です。

SampleID:サンプルの名前順
Mutation num.:サンプルごとのmutation数
Genes:遺伝子ごとの変異数 ASC/DESCどちらかを選択したのち、横のリストボックスからGene名を選択し、[add sort key] ボタンをクリックしてください。
automatic Gantt-chart:
 自動的にGantt-chartを作成します。 と、いっても技術者におなじみのガントチャートではありません。次で説明します。 使用する遺伝子の数を横のエディットボックスに入力したのち、[Gantt-chart] ボタンをクリックしてください。

Gantt-chart

縦軸を遺伝子(Gene)の変異数の多い順に並べ、横軸をその遺伝子の変異を持っているかどうかで並び替えます。
まず、先頭の遺伝子から並べ、指定された遺伝子の数だけ繰り返します。
検出された遺伝子の数だけ繰り返すのが理想ですが、処理が重くなるため、関心のある遺伝子までに絞ったほうが処理が早くなります。

_images/mut_operation3.PNG

2. axis-Y sort

縦軸の並び順を変更します。

  • none ソートしない
  • ASC 昇順
  • DESC 降順

以下の要素でソートでき、複数ソート可能です。

Mutation num.:遺伝子ごとのmutation数
Gene name:遺伝子の名前順

3. sample filter

横長の棒グラフ(Sample)の縦軸の最大値を設定します。

いくつかのサンプルだけ飛びぬけて変異数が多く、他はそれほど変異がないような場合、この機能を使用することで、グラフが見やすくなることがあります。
表示したい最大値を横のエディットボックスに入力したのち、[update filter] ボタンをクリックしてください。
空白にすると、すべてを表示します。(初期値)

フィルター適用前と適用後

最大値を200に設定した場合の表示例

_images/mut_operation4.PNG

4. genes filter

縦軸に表示する遺伝子に対してフィルタを設定します。

Rate:検出された遺伝子のサンプル数における割合(%)。初期値は0%(フィルタリングなし)
Display maximum:
 表示する遺伝子の最大数。

いずれも横のエディットボックスに入力したのち、[update filter] ボタンをクリックしてください。

install

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

  • Linux系サーバ (HGCスパコン含), Linux ディストリビューション
  • MacOS X
  • Windows
paplotを実行するにはpython 2.7が必要です。
(python 2.6 は未検証)

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含) を参照してください。

python 2.7.10 で動作確認済みです。

2. paplot のインストール

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

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

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

C:\\Program Files\\\WinPython-64bit-2.7.10.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-2.7.10.2\python-2.7.10.amd64\Scripts\pa_plot"
pa_plotの実際の場所を記入してください。
数字はインストールしたpythonのバージョンにより変化します。

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

pythonコマンドプロンプトで、先ほど作成したバッチファイルを実行します。
>pa_plot.cmd conf
**********************
   hello paplot !!!
**********************

(デフォルト設定値が表示される)
このような表示が出れば成功です。

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

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

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

Genomonデータを使用する

Genomonに関しては、各バージョンの設定ファイルを用意しています。
※カスタマイズする場合は 自分のデータを使用する を参照して変更してください。

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

Genomonの結果ファイルをもとにしたバージョンの見分け方

version mutation sv qc post-analysis
Genomon 2.0.0 ~ 2.0.3 ヘッダなし ヘッダなし 結果なし 結果なし
Genomon 2.0.4 ~ 2.0.5 ヘッダあり ヘッダなし 結果あり 結果なし
Genomon 2.2.0 ヘッダあり ヘッダあり 結果あり 結果あり

実行例

genomon_root={Genomonを実行したディレクトリ}
sample={Genomon実行時のサンプルファイル名のディレクトリ}
output_dir={paplotの出力ディレクトリ}
project_name={プロジェクト名}
paplot_install_dir={paplotをインストールしたディレクトリ}

# for Genomon 2.3.0
pa_plot qc ${genomon_root}/post_analysis/${sample}/merge_qc.txt ${output_dir} ${project_name} --config_file ${paplot_install_dir}/config_template/genomon_v2_3_0_merge.cfg
pa_plot sv ${genomon_root}/post_analysis/ACC_000/merge_sv_filt_pair_controlpanel.txt ./ACC_230_m ACC --config_file ./config_template/genomon_v2_3_0_merge.cfg
pa_plot mutation ${genomon_root}/post_analysis/ACC_000/merge_mutation_filt_pair_controlpanel.txt ./ACC_230_m ACC --config_file ./config_template/genomon_v2_3_0_merge.cfg

# for Genomon 2.2.0
pa_plot qc ${genomon_root}/post_analysis/${sample}/merge_qc.txt ${output_dir} ${project_name} --config_file ${paplot_install_dir}/config_template/genomon_v2_2_0_merge.cfg
pa_plot sv ${genomon_root}/post_analysis/${sample}/merge_sv_filt_pair_controlpanel.txt ${output_dir} ${project_name} --config_file ${paplot_install_dir}/config_template/genomon_v2_2_0_merge.cfg
pa_plot mutation ${genomon_root}/post_analysis/${sample}/merge_mutation_filt_pair_controlpanel.txt ${output_dir} ${project_name} --config_file ${paplot_install_dir}/config_template/genomon_v2_2_0_merge.cfg

# for Genomon 2.0.4 or Genomon 2.0.5
pa_plot qc "${genomon_root}/summary/*/*.tsv" ${output_dir} ${project_name} --config_file ${paplot_install_dir}/config_template/genomon_v2_0_5_v2_0_4.cfg
pa_plot sv "${genomon_root}/sv/*/*.genomonSV.result.txt" ${output_dir} ${project_name} --config_file ${paplot_install_dir}/config_template/genomon_v2_0_5_v2_0_4.cfg
pa_plot mutation "${genomon_root}/mutation/*/*_genomon_mutations.result.txt" ${output_dir} ${project_name} --config_file ${paplot_install_dir}/config_template/genomon_v2_0_5_v2_0_4.cfg

# for Genomon 2.0.0 ~ 2.0.3
pa_plot sv "${genomon_root}/sv/*/*.genomonSV.result.txt" ${output_dir} ${project_name} --config_file ${paplot_install_dir}/config_template/genomon_v2_0_0.cfg
pa_plot mutation "${genomon_root}/mutation/*/*_genomon_mutations.result.txt" ${output_dir} ${project_name} --config_file ${paplot_install_dir}/config_template/genomon_v2_0_0.cfg

自分のデータを使用する

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

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

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

Genomonデータを使用する場合は各バージョンの設定ファイルを用意していますので、 Genomonデータを使用する 参照してください。

警告

必須項目はハイライトで示しています。正しく設定してください。
サンプル名の指定方法については、 suffixとID も参照してください。

1. 全般

1
2
3
4
5
6
7
8
###################### general
[style]
# グラフのレイアウトファイル
# ~/tmp/paplot/style/rainbow.js
path =

# index.html の備考欄に出力するテキスト(HTMLタブ使用可, 半角英数字のみ)
remarks =

2. SV

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
###################### sv
[genome]
# ゲノムサイズのファイル(CSV形式)(デフォルトはhg19, installディレクトリ配下のgenomeディレクトリにあります)
#
# for example.
# (linux)
# path = ~/tmp/genome/hg19.csv
# (windows)
# path = C:\genome\hg19_part.csv
path =

[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

# 入力フォーマット (自分のデータに合わせて変更する)
[result_format_sv]

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

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

# 先頭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
col_opt_ID =

# 出力フォーマット (data_sv.csv)
[merge_format_sv]

# カラムがない場合、何で埋めるか
lack_column_complement = NA

# データ区切り
sept = ,

3. QC

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
###################### qc
[qc]
# qcでどのグラフを表示するか (表示しない場合Falseにする)
chart_coverage=True
chart_average=True
chart_mapped=True
chart_insert=True
chart_duplicate=True
chart_length=True

# 入力フォーマット (自分のデータに合わせて変更する)
# 項目はSVとほぼ同
[result_format_qc]
suffix =

sept = \t
header = True
comment = #

# column index (required)
col_duplicate_reads = #_duplicate_reads
col_mapped_reads = #_mapped_reads
col_total_reads = #_total_reads
col_average_depth = average_depth
col_mean_insert_size = mean_insert_size
col_ratio_2x = 2x_ratio
col_ratio_10x = 10x_ratio
col_ratio_20x = 20x_ratio
col_ratio_30x = 30x_ratio
col_read_length_r1 = read_length_r1
col_read_length_r2 = read_length_r2

# column index (option)
col_opt_ID = id

# 出力フォーマット (data_qc.csv)
# 記載項目はSVとほぼ同
[merge_format_qc]
lack_column_complement = NA
sept = ,

4. mutation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
###################### mutation
[mut]
# geneのサンプルに対する検出比(%)
# 値より小さいgeneはplot対象から除外する
# 0の場合はすべて出力する
use_gene_rate = 0

# 入力されていた場合、そのgeneのみ出力する
# 未入力の場合、検出されたgeneすべて出力する
# , 区切りで複数指定可能
#
# limited_genes = TP,TTN,APC,BRAF,CDH1,FLT3
limited_genes =

# 入力されていた場合、そのgeneはplot対象から除外する
# , 区切りで複数指定可能
#
# nouse_genes = NONE,MUC4
nouse_genes =

# 入力されていた場合、その変異タイプ(func)のみ出力する
# 未入力の場合、検出されたfuncすべて出力する
# , 区切りで複数指定可能
#
# limited_funcs = exome,splicing
limited_funcs =

# 入力されていた場合、そのfuncはplot対象から除外する
# , 区切りで複数指定可能
# 空白行を除去する場合、(blank)と記入する
nouse_funcs = (blank),unknown,synonymous_SNV

# funcのplot色を指定する。func名:(RGBもしくはカラー名)
# , 区切りで複数指定可能
# 未入力のfuncはデフォルト色を使用する
func_colors = stopgain:#E85299,frameshift_deletion:#F39600,frameshift_insertion:#E60011,nonframeshift_deletion:#9CAEB7

# ポップアップウィンドウの表示内容
# 詳細は以下
tooltip_format_checker_title1 = ID:{id}, gene:{gene}, {#sum_item_value}
tooltip_format_checker_partial = type[{func}], {chr}:{start}:{end}, [{ref} -----> {alt}]
tooltip_format_gene_title = gene:{gene}, {#sum_item_value}
tooltip_format_gene_partial = func:{func}, {#item_value}
tooltip_format_id_title = ID:{id}, {#sum_item_value}
tooltip_format_id_partial = func:{func}, {#item_value}

# 入力フォーマット (自分のデータに合わせて変更する)
# 項目はSVとほぼ同
[result_format_mutation]
suffix =
sept = \t
header = True
comment = #

# funcが1セルに複数入力されている場合の区切り文字
sept_func = ";"
# geneが1セルに複数入力されている場合の区切り文字
sept_gene = ";"

# column index (required)

# func列
col_func = Merge_Func

# gene列
col_gene = Gene.refGene

# column index (option)
# chromosome
col_opt_chr = Chr
# 開始位置
col_opt_start = Start
# 終了位置
col_opt_end = End
# リファレンスの塩基配列
col_opt_ref = Ref
# 対象の塩基配列
col_opt_alt = Alt
# id (sample) 列
col_opt_ID = id

# 出力フォーマット (data_mut.csv)
# 記載項目はSVとほぼ同
[merge_format_mutation]
lack_column_complement = NA
sept = ,

ポップアップウィンドウの表示内容

ポップアップで表示する内容はある程度変更することができます。
表示箇所ごとに6種類設定できますが、書き方は同一です。

tooltip_format_checker_partial = type[{func}], {chr}:{start}:{end}, [{ref} -----> {alt}]

表示例:
type[exome], chr1:2000:2001, [A -----> T]
{}で囲った文字がキーワードで、実際の値に置き換えられます。
キーワードとはconfigファイルで各データ列を設定した項目のうち、col_ もしくは col_opt_ を除いた名前です。

  • col_func = Merge_Func
  • col_gene = Gene.refGene
  • col_opt_chr = Chr
  • col_opt_start = Start
  • col_opt_end = End
  • col_opt_ref = Ref
  • col_opt_alt = Alt
  • col_opt_ID = id
デフォルトで設定しているのは上記ですが、任意で増やすことができます。
その場合は、実際のデータの列名を指定してください。

col_opt_new = New_columun_name

データ列とは別に以下も特殊キーワードとして使用することができます。
全てconfigファイルにより除外されたmutationを除いた数です。

{#number_id}:サンプル数
{#number_gene}:遺伝子数
{#number_mutaion}:
 mutation数(同一サンプルが同一遺伝子で複数回検出されても1としてカウントする)
{#sum_mutaion}:mutation総検出数
{#item_value}:積み上げグラフの1項目の値
{#sum_item_value}:
 積み上げグラフの合計値
数値計算させることもできます。その場合、計算式を{}で囲います。

{#number_mutaion_gene/#number_id*100}%

表示例:
3.33333333333333%

表示桁数を指定したい場合は計算式の後に ":.2" と書きます。小数点以下3桁の場合は ":.3" と書きます。

{#number_mutaion_gene/#number_id*100:.2}%

表示例:
3.33%

デフォルトでの設定内容と表示との対応

# グリッド - タイトル
tooltip_format_checker_title1 = ID:{ID}, gene:{gene}, {#sum_item_value}

# グリッド - funcごと
tooltip_format_checker_partial = type[{func}], {chr}:{start}:{end}, [{ref} -----> {alt}]

# 遺伝子グラフ - タイトル
tooltip_format_gene_title = gene:{gene}, {#sum_item_value}

# 遺伝子グラフ - funcごと
tooltip_format_gene_partial = func:{func}, {#item_value}

# サンプルグラフ - funcごと
tooltip_format_id_title = ID:{id}, {#sum_item_value}

# サンプルグラフfuncごと
tooltip_format_id_partial = func:{func}, {#item_value}
_images/conf_mut4.PNG

サブプロットについて

mutation-matrixグラフでは解析結果とは別にサンプルに対する情報を表示することができます。

表示場所は2つあり、type1はサンプルグラフの下に、type2は最後に表示します。

type1を表示する場合はセクション名を[mut_subplot_type1_*]とします。
type2を表示する場合はセクション名を[mut_subplot_type2_*]とします。

* には1から始まる連番を入れてください。1から順に表示します。

_images/conf_mut1.PNG
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
# mut_subplot_type1_1
[mut_subplot_type1_1]

# ファイルのパス
path = /path/to/file1

###########################
# ファイルフォーマット

# ファイルのデータ区切り
sept = ,

# 先頭1行がヘッダかどうか
header = True

# コメント行
comment = #

# 表示データの列
col_value = average_depth

# id 列(main plotと紐づけられること)
col_ID = id

###########################
# サブプロットのフォーマット

# サブプロットのタイトル
title = bam's average depth

# 表示形式
# fix, range, gradientから選択
mode = gradient

# 凡例のフォーマット
# 値:表示文字列:セルの色を各値ごとに記入する。セルの色は省略可能
#
# mode=fixの場合
# name_set = 0:Male:blue, 1:Female:red, 2:Unknown:gray
#
# mode=fixの場合、値には範囲開始の値を入れる
# name_set = 0:0-19, 20:20-39, 40:40-59, 60:60over
#
# mode = gradientの場合、最初と最後の値を入れる。MIN/MAXを使用すると、データから自動的に設定する
# 自動設定の場合
# name_set = MIN:min, MAX:max
# 手動設定の場合
# name_set = 0:min (0), 40:max (40)
name_set = MIN:min, MAX:max

# mut_subplot_type2_1
[mut_subplot_type2_1]
title = Clinical Gender
path = /path/to/file2
sept = ,
header = True
comment =
col_value = gender
col_ID = barcode
mode = fix
name_set = 0:Male:blue, 1:Female:red, 2:Unknown:gray

#mut_subplot_type2_2
[mut_subplot_type2_2]
title = Clinical Age
path = /path/to/file3
sept = ,
header = True
comment =
col_value = age
col_ID = barcode
mode = range
name_set = 0:0-19, 20:20-39, 40:40-59, 60:60over

titleとnameset

_images/conf_mut2.PNG

表示モードの違い

_images/conf_mut3.PNG

suffixとID

paplotではサンプル名が必要です。ファイル入力では、以下のことに注意してください。

  • case1: 1ファイルのみ入力 複数サンプルの結果が、1ファイルにまとめられていると想定しています。サンプル名となる列を col_opt_ID で必ず指定してください。
  • case2: サンプルごとに分かれた複数のファイルを入力し、データ中にサンプル名となるものはない。 ファイル名の一部をサンプル名として使用します。 suffix を必ず指定してください。
  • case3: サンプルごとに分かれた複数のファイルを入力し、データ中にサンプル名となるデータがある。 サンプル名となる列を col_opt_ID で必ず指定してください。
_images/id_suffix.PNG

列と設定の対応

_images/col_pos.PNG

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
_images/option_sv.PNG

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

pa_plot コマンド

1. コマンドオプション

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

必須

{qc, sv, mutation}:
 paplotのサブコマンドです。どちらかを選択します。
input:入力ファイルです。ワイルドカード (*) を使用して複数指定することができます。最初と最後に " をつけてください。
output_dir:出力ディレクトリを指定します。ディレクトリ構成は 2. 出力ディレクトリ を参照してください。
project_name:プロジェクト名です。出力ファイルのタイトルに使用します。

任意

--config_file 設定ファイルです。未指定の場合、デフォルトを使用します。
--remarks index.htmlの備考欄に出力するテキストです。未指定の場合、設定ファイルの値を使用します。
-h ヘルプを表示します。
--version バージョンを表示します。

2. 出力ディレクトリ

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

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

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

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

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

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値の代わりに指定することができます。

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グラフの色が変更されていますか?

_images/style-qc_change.PNG

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

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

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

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

2. qcグラフ

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

_images/style-qc.PNG

3. sv (サムネイル)

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

_images/style-sv-thumb.PNG

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

_images/link-tension.PNG

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

_images/link-opacity.PNG

4. sv (詳細表示)

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

_images/style-sv-detail.PNG

5. sv (グラフ)

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

_images/style-sv-bar.PNG

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
  • IE ... Snapcrab for IE
    1. OS 標準アプリケーション
  • Windows ... Snipping Tool (「スタート」→「すべてのプログラム」→「アクセサリ」→「Snipping Tool」)
  • MacOSX ... グラブ (Finder → 「移動」メニュー → 「アプリケーション」を選択 → 「ユーティリティ」ディレクトリを開く → 「グラブ」)

グラフの色が黒くなる

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


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

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

_images/qa_lack_color.PNG

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で使用されている名称と同じでなければなりません。

_images/qa_genome_size.PNG

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 パッケージを使用しています。