https://img.shields.io/badge/python-2.7-blue.svg https://img.shields.io/badge/python-3.5-blue.svg _images/genomon_kun.PNG

paplot documentation

Contents:

はじめに

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

ゲノムを解析して、このようなテキストファイルができたとします。

_images/mutation_list.PNG
このあと何をしますか？
グラフを作成しないでしょうか？
毎回手動で作成したり、似たようなスクリプトを書いていませんか？
データの抽出条件、ソート条件を変えて再度グラフを作成していないでしょうか？

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

作成できるレポートの種類

  1. Quality Control (QC) レポート

アライメント率やカバレッジ率など、シーケンスデータの品質を表示します。

_images/qc_dummy.PNG
  1. Chromosomal Aberration (CA) レポート

構造異常や融合遺伝子など、染色体間の変異を円形のプロットで可視化し、棒グラフでその分布を表示します。

_images/sv_dummy.PNG
  1. Mutation Matrix レポート

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

_images/mut_dummy.PNG
  1. Mutational Signature レポート

検出した変異についての特徴的なパターン (変異シグネチャ) を表示します。

_images/sig_dummy.PNG

pmsignature を使用した表現も可能です。

_images/pmsig_dummy.PNG

クイックスタート

このセクションでは以下の内容について解説します。

  1. paplot をインストール
  2. サンプルデータでコマンドを実行
  3. 結果ファイルを表示
  4. 設定ファイルを編集して自分のデータを使用する

1. paplot をインストール

paplot は python2.7 および python 3.5 で動作確認しています。
また、paplot は追加パッケージを必要としません。
より詳しいインストール手順は インストール を参照してください。
cd {インストールしたいディレクトリ}
# v0.5.4 の場合
wget https://github.com/Genomon-Project/paplot/archive/v0.5.4.zip
unzip v0.5.4.zip
cd paplot-0.5.4/

python setup.py build install
正しくインストールされたか確認します。

インストールの確認

以下を入力してください。
paplot --version
このように表示されればインストール成功です。(インストールしたバージョンが表示されます)
paplot-0.5.4

2. サンプルデータでコマンドを実行

paplot はコマンドから使用します。

基本的な使い方は次の通りです。
詳細なオプションは paplot コマンド を参照してください。
paplot subcommand [--config_file CONFIG_FILE] [--title TITLE]
                  [--ellipsis ELLIPSIS] [--overview OVERVIEW]
                  [--remarks REMARKS]
                  input output_dir project_name

必ず入力する項目

subcommand:

paplot のサブコマンドです。いずれかを選択します。

  • qc
  • ca
  • mutation
  • signature
  • pmsignature
input:

入力ファイルです。
output_dir:

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

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

サンプルデータを用意していますので実行します。

cd {paplot を解凍したディレクトリ}

# QC レポート
paplot qc example/qc_brush/data.csv ./tmp demo

# Chromosomal Aberration レポート
paplot ca example/ca_option/data.csv ./tmp demo

# Mutation Matrix レポート
paplot mutation example/mutation_option/data.csv ./tmp demo

# Mutational Signatureレポート
paplot signature "example/signature_stack/data*.json" ./tmp demo

# pmsignature レポート
paplot pmsignature "example/pmsignature_stack/data*.json" ./tmp demo

3. 結果ファイルを表示

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

{output_dir} で指定したディレクトリ
  ├ demo
  │   ├ graph_ca.html            <--- Chromosomal Aberration レポート
  │   ├ graph_mut.html           <--- Mutation Matrix レポート
  │   ├ graph_pmsignature2.html  <--- pmsignature レポート (数字は変異シグネチャの数)
  │   ├ graph_pmsignature3.html
  │   ├ graph_pmsignature4.html
  │   ├ graph_pmsignature5.html
  │   ├ graph_pmsignature6.html
  │   ├ graph_qc.html            <--- QC レポート
  │   ├ graph_signature2.html    <--- Mutational Signature レポート (数字は変異シグネチャの数)
  │   ├ graph_signature3.html
  │   ├ graph_signature4.html
  │   ├ graph_signature5.html
  │   └ graph_signature6.html
  │
  ├ js          <--- この4つのディレクトリはHTMLファイルを表示するために必要です。消さないでください。
  ├ layout
  ├ lib
  ├ style
  │
  └ index.html             <--- このファイルをウェブブラウザで開いてください。
index.html ファイルをウェブブラウザで開いてください。

注釈

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

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

QC レポート
_images/qc_dummy.PNG
Chromosomal Aberration レポート
_images/sv_dummy.PNG
Mutation Matrix レポート
_images/mut_dummy.PNG
Mutational Signature レポート
_images/sig_dummy.PNG
pmsignature レポート
_images/pmsig_dummy.PNG
それぞれのレポートの使い方は HOW TO USE GRAPHS を参照してください。
データと設定ファイルの記述方法は以下を参照してください。

[入門編]
[上級者向け]

インストール

paplot は次のマシンで動作します。
  • Linux 系サーバ (HGC スパコン含)、Linux ディストリビューション
  • MacOS X
  • Windows
paplot を実行するには python 2.7 もしくは python 3.5 が必要です。
(python 2.6 は未検証)

Linux 系の場合 (cygwin 含)

1. paplot のインストール

paplot のサイトから最新版の Source code (zip) をダウンロードします。
https://github.com/Genomon-Project/paplot/releases/
cd {インストールしたいディレクトリ}
# v0.5.4 の場合
wget https://github.com/Genomon-Project/paplot/archive/v0.5.4.zip
unzip v0.5.4.zip
cd paplot-0.5.4/

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
正しくインストールされたか確認します。
paplot --version
paplot-0.5.4
このようにバージョンが表示されれば成功です。 クイックスタート をお試しください。

注釈

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 {ダウンロードしたディレクトリ}
# 大抵は以下にあります
# cd /Users/<user name>/Downloads/paplot-<version>
インストールします。
python setup.py build install --user

3. PATH の設定

このままではターミナルは paplot がどこにあるかわからないので、インストールされている場所を PATH という環境変数に設定します。
大抵、ここにあります。

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

注釈

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

4つ見つかるはずです。
このうち、ダウンロードしたディレクトリは使用しません。
{インストールしたディレクトリ}/bin/paplot               <--- ココです
{インストールしたディレクトリ}/lib/python2.7/site-packages/paplot-0.2.6devel-py2.7.egg/EGG-INFO/scripts/paplot
{ダウンロードしたディレクトリ}/paplot-devel/paplot
{ダウンロードしたディレクトリ}/paplot-devel/build/scripts-2.7/paplot

export PATH={インストールしたディレクトリ}/bin:$PATH
export LD_LIBRARY_PATH={インストールしたディレクトリ}/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
正しくインストールされたか確認します。
paplot --version
paplot-0.5.4
このようにバージョンが表示されれば成功です。 クイックスタート をお試しください。

注釈

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 のインストール

Windows の場合、標準では python はインストールされていませんので、まず python をインストールします。
標準 python でも paplot は動きますが、今後 python を使用してデータ解析される予定でしたら、数値計算系パッケージがあらかじめ用意されている winPython もしくは Python(x,y) をインストールすることをお勧めします。
cygwin でも動きます。
cygwin の場合は Linux 系の場合 (HGC スパコン、cygwin 含) を参照してください。
python 2.7.10、python 3.5.3 で動作確認済みです。

2. paplot のインストール

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

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

Windows 標準のコマンドプロンプトを起動し、ダウンロードした zip ファイルを解凍したフォルダに移動します。
cd {zip ファイルを解凍したフォルダ}
paplot インストールコマンドを実行します。
Windowsの場合、1．による python のインストール作業では環境変数 (PATH) が設定されていません。
ここでは python をパスごと指定していますが、システム環境変数の PATH に登録することで省略することもできます。

注意

以下、python のパスは WinPython-64bit-2.7.10.3 を標準インストールしたときのものです。 実際の環境に合わせてください。

> C:\WinPython-64bit-2.7.10.3\python-2.7.10.amd64\python.exe setup.py build install
続けて、テストコマンドを実行します。
> C:\WinPython-64bit-2.7.10.3\python-2.7.10.amd64\python.exe paplot --version
paplot-0.5.4
このようにバージョンが表示されれば成功です。 クイックスタート をお試しください。

paplot コマンド

1. 基本的な使い方

paplot subcommand [--config_file CONFIG_FILE] [--title TITLE]
                  [--ellipsis ELLIPSIS] [--overview OVERVIEW]
                  [--remarks REMARKS]
                  input output_dir project_name

必ず入力する項目

subcommand:

paplot のサブコマンドです。いずれかを選択します。

  • qc
  • ca
  • mutation
  • signature
  • pmsignature
input:

入力ファイルです。複数ファイルを使用する場合は データファイルが分かれている場合 も参照してください。

 
# 1ファイルだけ入力する場合
paplot mutation {unzip_path}/example/mutation_minimal/data.csv ./tmp mutation_minimal \
--config_file {unzip_path}/example/mutation_minimal/paplot.cfg

# 複数ファイル指定する場合は , で区切る
paplot mutation \
{unzip_path}/example/mutation_split_file/SAMPLE00.data.csv,{unzip_path}/example/mutation_split_file/SAMPLE01.data.csv \
./tmp mutation_split_file1 --config_file {unzip_path}/example/mutation_split_file/paplot.cfg

# ワイルドカードを使用して、まとめて指定することも可能
# 最初と最後に " を付けること
paplot mutation "{unzip_path}/example/mutation_split_file/*.csv" ./tmp mutation_split_file2 \
--config_file {unzip_path}/example/mutation_split_file/paplot.cfg
output_dir:出力ディレクトリを指定します。ディレクトリ構成は 2. 出力ディレクトリ を参照してください。
project_name:プロジェクト名です。出力ファイルのタイトルに使用します。

2. 出力ディレクトリ

次の構成でファイルを出力します。

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

出力ファイルを移動する際は出力ディレクトリ全体を移動してください。 それぞれのグラフの使い方は HOW TO USE GRAPHS を参照してください。

3. コマンドオプション

次の項目をオプションで変更することができます。

--config_file 設定ファイルです。未指定の場合、デフォルトを使用します。
--title グラフのタイトル
--ellipsis グラフの短縮名。グラフのファイル名になるため、同一ディレクトリに複数ファイルを出力する際に設定すると便利です。
--overview index.html に表示するグラフの概要。
--remarks index.html の備考欄に出力するテキストです。未指定の場合、設定ファイル [style] セクション中、 remarks オプションの値を使用します。

デフォルト値は次の通りです。

subcommand title ellipsis overview remarks
qc QC graphs qc Quality Control of bam. なし
ca CA graphs ca Chromosomal Aberration. なし
mutation Mutation Matrix mutation Gene-sample mutational profiles. なし
signature Signature signature Mutational Signatures. なし
pmsignature PMSignature pmsignature Express mutational signatures in pmsignature. なし

Quality Control (QC) レポート

QC レポートはアライメント率やカバレッジ率など、シーケンスデータの品質を表示します。

各バーの上にマウスカーソルを乗せてみてください。各サンプルの詳細情報をポップアップとして表示します。

先頭の背の低いグラフはサンプルごとの depth 平均値です。 [*]
このグラフを範囲選択することで他のグラフの拡大ができます。
[*]

範囲選択用グラフについて

ここに示しているグラフは example データを使用したときの表示例です。 設定ファイルにより範囲選択用グラフの要素を変更できます。設定方法は 範囲選択 を参照してください。
_images/qc_operation.PNG

Chromosomal Aberration (CA) レポート

CA レポートはStructural Variation (SV) 等、染色体間の変異を円形のプロットで可視化し、棒グラフでその分布を表示します。
  • 棒グラフでは全サンプルで切断点を集計した数を表示します。
  • 円形のプロットでは、サンプルごとに切断点 1 と 2 を線でつないで表示します。
棒グラフを選択すると選択されたゲノム領域に切断点を持つサンプルが選択されます。
選択方法は [ハイライト] と [選択したもののみ表示 (他を隠す) ] の 2 通りあり、先頭のオプションボタンで選択できます。
_images/sv_operation1.PNG
棒グラフの積み上げ要素は 2 つあり、2 つの切断点が染色体をまたいでいるか、もしくは同一染色体内かで色を分けています。 [*]
チェックを外すと、その要素は表示されません。
[*]

グループ化について

ここに示しているグループ化はデフォルトの設定です。 設定ファイルによりグループ要素を変更できます。設定方法は 変異のグルーピング を参照してください。
_images/sv_operation2.PNG
サンプルごとの円形のグラフをクリックすると拡大表示します。
切断点をつなぐ線の上にマウスを乗せると詳細を表示します。
_images/sv_operation3.PNG

Mutation Matrix レポート

Mutation Matrix レポートは検出した変異について縦軸を遺伝子 (Gene)、横軸をサンプル (Sample) として、変異タイプ別に表示します。

横長の棒グラフ (Sample):
 
サンプルごとに検出された変異の数を表示します。
縦長の棒グラフ (Gene):
遺伝子ごとの変異数をサンプル数における割合 (%) で表示します。

- 同一のサンプルが同じ遺伝子に対して複数の変異を持っていた場合、変異数を 1 としてカウントします。
- 同一のサンプルが同じ遺伝子に対して複数の変異タイプを持っていた場合、優先順位の高い変異タイプにカウントします。
Mutation type:
変異タイプ別に色分けして表示します。表示したくない変異タイプがある場合、Mutation type のチェックを外すことで除外できます。
Subplot:
変異データとは別にサンプルに対するデータがある場合、サブプロットとして表示することができます。このファイルは paplot コマンド実行前に設定ファイルに記入しておく必要があります。
_images/mut_operation1.PNG

操作方法

_images/mut_operation2.PNG _images/mut_operation2_2.PNG

1. Axis-X sort

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

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

以下の要素でソートでき、ソート条件を複数指定することが可能です。

Sample ID:
サンプルの名前順
Mutation number:
 
サンプルごとの変異数
Genes:
遺伝子ごとの変異数。ASC/DESC どちらかを選択したのち、横のリストボックスから遺伝子名を選択し、[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 number:
 遺伝子ごとの変異数
Gene name:遺伝子の名前順

3. Sample filter

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

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

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

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

_images/mut_operation4.PNG

4. Genes filter

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

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

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

Mutaitonal Signature レポート

Mutaitonal Signature レポートは検出した変異についての特徴的なパターン (変異シグネチャ) を表示します。

上段 (Signature):
変異シグネチャを表示します。
下段 (寄与度グラフ):
サンプルごとの変異について、変異シグネチャの寄与度を表示します。
_images/sig_dummy.PNG

また、最下段のリストボックスにより表示モード (View mode) を切り替えることができます。

View mode:
- Rate ... 変異の数を 1 としたときの変異シグネチャの割合を % で表示します。
- Count ... 実際の変異数に占める割合を表示します。
Sort by:
- Sample ID ... サンプル名順
- Mutation count ... 変異数の降順 (View mode が Count の場合のみ選択可能)

[View mode] で [Count] を選択し、[Sort by] で [Mutation count] を選択した場合の表示例

_images/sig_operation1.PNG

pmsignatureについても同様です。

_images/pmsig_dummy.PNG

QC レポート

ここでは、サンプルデータ [*] を使用して、QC レポートを出力するために必要な入力データと設定方法を解説します。

[*]サンプルデータは paplot をダウンロードして解凍したディレクトリ中、example ディレクトリにあります。

1. 最小データセット

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

paplot で QC レポートを作成するために最低限必要な情報はサンプル名 (Sample) と QC の値 (最低 1 項目) です。 今回の例では、QC の値に depth 平均値 (AverageDepth) を使用していますが、別の値でも問題ありません。

データファイルから一部抜粋 (example/qc_minimal/data.csv)
Sample,AverageDepth
SAMPLE1,70.0474
SAMPLE2,65.7578
SAMPLE3,63.3750
SAMPLE4,70.9654
SAMPLE5,69.9653

まず、設定ファイルの [result_format_qc] セクションに入力データの列名を登録します。

example/qc_minimal/paplot.cfg
[result_format_qc]
col_opt_id = Sample
col_opt_key1 = AverageDepth

列名は次の形式で記述します。 col_opt_{キーワード} = {実際の列名}

キーワードとは

次に、設定ファイルに [qc_chart_1] セクションを追加し、次のように設定します。

example/qc_minimal/paplot.cfg
[qc_chart_1]

# グラフのタイトル
title = Depth average

# Y 軸のラベル
title_y = Average of depth

# 積み上げ要素
# 今回は 1 項目のみなので、通常の棒グラフとして表現されます
stack1 = {key1}

# グラフの色と凡例
name_set = Average depth:#2478B4

# ポップアップのフォーマット
tooltip_format1 = Sample:{id}
tooltip_format2 = {key1:.2}

注釈

ここで使用している {key1} は [result_format_qc] セクションで入力した {キーワード} です。

編集した設定ファイルを使用して paplot を実行します。

paplot qc {unzip_path}/example/qc_minimal/data.csv ./tmp qc_minimal \
--config_file {unzip_path}/example/qc_minimal/paplot.cfg

2. ヘッダなし

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする
データファイルから一部抜粋 (example/qc_noheader/data.csv)
SAMPLE1,70.0474
SAMPLE2,65.7578
SAMPLE3,63.3750
SAMPLE4,70.9654
SAMPLE5,69.9653

データにヘッダ行がない場合、列名でなく列番号を設定します。

設定ファイルの [result_format_qc] セクションでデータの列番号を次のように設定します。

列番号は左から順に 1 始まりで数えます。

example/qc_noheader/paplot.cfg
[result_format_qc]
# ヘッダオプションを False に設定
header = False

col_opt_id = 1
col_opt_average_depth = 2

編集した設定ファイルを使用して paplot を実行します。

paplot qc {unzip_path}/example/qc_noheader/data.csv ./tmp qc_noheader \
--config_file {unzip_path}/example/qc_noheader/paplot.cfg

3. 積み上げグラフ

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

最小構成では 1 つの棒グラフを作成しました。今回はさらに積み上げグラフを追加します。

データファイルから一部抜粋 (example/qc_stack/data.csv)
Sample,AverageDepth,ReadLengthR1,ReadLengthR2
SAMPLE1,70.0474,265,270
SAMPLE2,65.7578,140,200
SAMPLE3,63.375,120,175
SAMPLE4,70.9654,120,140
SAMPLE5,69.9653,230,110

ここでは以下の構成でグラフを作成します。

  • chart_1: [棒グラフ] AverageDepth (最小構成と同じ)
  • chart_2: [積み上げグラフ] ReadLengthR1, ReadLengthR2

まず、設定ファイルの [result_format_qc] セクションに入力データの列名を登録します。

example/qc_multi_plot/paplot.cfg
[result_format_qc]
col_opt_id = Sample

# chart_1 で使用するデータ列
col_opt_keyA1 = AverageDepth

# chart_2 で使用するデータ列
col_opt_keyB1 = ReadLengthR1
col_opt_keyB2 = ReadLengthR2

列名は次の形式で記述します。 col_opt_{キーワード} = {実際の列名}

キーワードとは

次に、設定ファイルに [qc_chart_1]、[qc_chart_2] ... セクションを追加し、順番にその中の項目を記入します。

QC レポートは [qc_chart_1] → [qc_chart_2] → [qc_chart_3] の順番に表示し、必要な数だけ [qc_chart_*] セクションを増やすことができます。
* には 1 から始まる連番を入れてください。1 から順に表示します。

完成した設定ファイルは example/qc_stack/paplot.cfg を参照してください。

3-1. 単純な棒グラフ

chart_1 は単純な棒グラフです。

記載方法は最小構成と同じですので、ここでは割愛します。

3-2. 積み上げグラフ

chart_2 はリード長 (R1, R2) の積み上げグラフです。

example/qc_multi_plot/paplot.cfg
[qc_chart_2]

# 表示する文字列を設定します
title = Read length
title_y = Read length

# グラフの積み上げ要素
# stack1 → 2 → ... の順に下から表示します。stack1 を一番下に表示します
stack1 = {keyB1}
stack2 = {keyB2}

# 凡例の文字列と色を設定します
# stack1 → 2 → ... の順に , で区切って書きます
name_set = Read length r1:#2478B4, Read length r2:#FF7F0E

# ポップアップの表示内容
tooltip_format1 = Sample:{id}
tooltip_format2 = Read1: {keyB1:,}
tooltip_format3 = Read2: {keyB2:,}

注釈

ここで使用している {key*} は [result_format_qc] セクションで入力した {キーワード} です。

編集した設定ファイルを使用して paplot を実行します。

paplot qc {unzip_path}/example/qc_multi_plot/data.csv ./tmp qc_multi_plot \
--config_file {unzip_path}/example/qc_multi_plot/paplot.cfg

3-3. name_set の書き方

凡例名と色を定義します。

{要素の凡例名}:{セルの色} を積み上げ要素ごとに記入します。セルの色は省略可能です。

name_set = average_depth:#2478B4

# 複数ある場合は , で区切って書きます
# stack1 → 2 → ... の順に stack の数だけ書きます
name_set = Read length r1:#2478B4, Read length r2:#FF7F0E

セルの色を省略した場合、以下の色を上から順にローテーションで使用します。

_images/default_color.PNG

4. 様々なグラフ

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

前章では 1 つの棒グラフと積み上げグラフを作成しました。今回は複数のグラフを作成します。

データファイルから一部抜粋 (example/qc_variation/data.csv)
Sample,AverageDepth,ReadLengthR1,ReadLengthR2,TotalReads,MappedReads,2xRatio,10xRatio,20xRatio,30xRatio
SAMPLE1,70.0474,265,270,94315157,56262203,0.9796,0.768,0.6844,0.6747
SAMPLE2,65.7578,140,200,50340277,33860998,0.8489,0.7725,0.7655,0.6131
SAMPLE3,63.375,120,175,90635480,88010999,0.9814,0.8236,0.6045,0.5889
SAMPLE4,70.9654,120,140,72885114,89163960,0.9047,0.8303,0.7032,0.6801
SAMPLE5,69.9653,230,110,92572101,28793615,0.9776,0.9452,0.672,0.6518

ここでは以下の構成でグラフを作成します。

  • chart_1: [棒グラフ] AverageDepth (最小構成と同じ)
  • chart_2: [積み上げグラフ] ReadLengthR1, ReadLengthR2 (前章と同じ)
  • chart_3: [棒グラフ] MappedReads を TotalReads で割る
  • chart_4: [積み上げグラフ] 2xRatio, 10xRatio, 20xRatio, 30xRatio (下段の値を引く)

まず、設定ファイルの [result_format_qc] セクションに入力データの列名を登録します。

example/qc_variation/paplot.cfg
[result_format_qc]
col_opt_id = Sample

# chart_1 で使用するデータ
col_opt_average_depth = AverageDepth

# chart_2 で使用するデータ
col_opt_read_length_r1 = ReadLengthR1
col_opt_read_length_r2 = ReadLengthR2

# chart_3 で使用するデータ
col_opt_mapped_reads = MappedReads
col_opt_total_reads = TotalReads

# chart_4 で使用するデータ
col_opt_ratio_2x = 2xRatio
col_opt_ratio_10x = 10xRatio
col_opt_ratio_20x = 20xRatio
col_opt_ratio_30x = 30xRatio

列名は次の形式で記述します。 col_opt_{キーワード} = {実際の列名}

キーワードとは

次に、設定ファイルに [qc_chart_1]、[qc_chart_2]、[qc_chart_3] ... セクションを追加し、順番にその中の項目を記入します。

QC レポートは [qc_chart_1] → [qc_chart_2] → [qc_chart_3] の順番に表示し、必要な数だけ [qc_chart_*] セクションを増やすことができます。
* には 1 から始まる連番を入れてください。1 から順に表示します。

完成した設定ファイルは example/qc_variation/paplot.cfg を参照してください。

4-1. 単純な棒グラフ

chart_1 (Depth average) は単純な棒グラフです。

記載方法は最小構成と同じですので、ここでは割愛します。

4-2. 単純な積み上げグラフ

chart_2 (Read length) は積み上げグラフです。

記載方法は前章と同じですので、ここでは割愛します。

4-3. 棒グラフ (列同士の数値演算)

chart_3 (Mapped reads) はマップ率の棒グラフです。今回はマップリード数をリード総数で割り算させて出力します。

example/qc_variation/paplot.cfg
[qc_chart_3]

# 表示する文字列を設定します
title = Mapped reads/Total reads
title_y = Rate

# 凡例の文字列と色を設定します
name_set = Mapped reads/Total reads:#2478B4

# グラフの値
stack1 = {mapped_reads/total_reads}

# ポップアップの表示内容
tooltip_format1 = Sample:{id}
tooltip_format2 = {mapped_reads/total_reads:.2}
上記では、 stack1 = {mapped_reads/total_reads} と記入することで、マップリード数をリード総数で割り算しています。
ここで {mapped_reads-total_reads} と書くと引き算に、 {mapped_reads+total_reads} と書くと足し算にすることができます。

なお、ポップアップでも同様に数値演算させています。
tooltip_format2 = {mapped_reads/total_reads:.2}

もし、ポップアップではそれぞれの値を表示したい場合は
tooltip_format2 = Mapped: {mapped_reads}, Total: {total_reads} 等と書くとそれぞれの値が表示されます。

ポップアップ記述方法詳細は ユーザ定義フォーマット を参照してください。

4-4. 積み上げグラフ (列同士の数値演算)

chart_4 (Depth coverage) はカバレッジの積み上げグラフです。

単純に積み上げず、数値演算を加えて前段の値を引き算します。

example/qc_variation/paplot.cfg
[qc_chart_2]

# 表示する文字列を設定します
title = Depth coverage
title_y = Coverage

# 凡例の文字列と色を設定します
name_set = Ratio 30x:#2478B4, Ratio 20x:#FF7F0E, Ratio 10x:#2CA02C, Ratio 2x:#D62728

# グラフの値
stack1 = {ratio_30x}
stack2 = {ratio_20x-ratio_30x}
stack3 = {ratio_10x-ratio_20x}
stack4 = {ratio_2x-ratio_10x}

# ポップアップの表示内容
tooltip_format1 = ID:{id}
tooltip_format2 = ratio__2x: {ratio_2x:.2}
tooltip_format3 = ratio_10x: {ratio_10x:.2}
tooltip_format4 = ratio_20x: {ratio_20x:.2}
tooltip_format5 = ratio_30x: {ratio_30x:.2}

上記では、stack1 に ratio_30x を、stack2 に ratio_20x から ratio_30x を引いたものを表示しています。

編集した設定ファイルを使用して paplot を実行します。

paplot qc {unzip_path}/example/qc_variation/data.csv ./tmp qc_variation \
--config_file {unzip_path}/example/qc_variation/paplot.cfg

5. 範囲選択

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

前章で作成した複数のグラフに対し、範囲選択用のグラフを追加します。

データ列は AverageDepth を使用します。

もし、別のデータ列を使用する場合は設定ファイルの [result_format_qc] セクションに col_opt_{name} として登録してください。

範囲選択用のグラフは [qc_chart_brush] というセクション名で一つだけ追加することができます。

example/qc_brush/paplot.cfg
[qc_chart_brush]
stack = {average_depth}
name_set = average:#E3E5E9

編集した設定ファイルを使用して paplot を実行します。

paplot qc {unzip_path}/example/qc_brush/data.csv ./tmp qc_brush \
--config_file {unzip_path}/example/qc_brush/paplot.cfg

Chromosomal Aberration レポート

ここでは、サンプルデータ [*] を使用して、Chromosomal Aberration レポートを出力するために必要な入力データと設定方法を解説します。

[*]サンプルデータは paplot をダウンロードして解凍したディレクトリ中、example ディレクトリにあります。

1. 最小データセット

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

paplot で Chromosomal Aberration レポートを作成するために最低限必要な項目は次の 5 つです。

  • サンプル名 (Sample)
  • 切断点 1 の染色体 (Chr1)
  • 切断点 1 の位置 (Break1)
  • 切断点 2 の染色体 (Chr2)
  • 切断点 2 の位置 (Break2)
データファイルから一部抜粋 (example/ca_minimal/data.csv)
Sample,Chr1,Break1,Chr2,Break2,
SAMPLE1,14,16019088,12,62784483,
SAMPLE1,9,99412502,7,129302434,
SAMPLE1,13,84663781,18,52991509,
SAMPLE2,11,101374238,22,26701405,
SAMPLE2,2,121708638,7,137424167,
SAMPLE3,22,34268355,10,19871820,
SAMPLE3,8,107868940,hs37d5,20517614,
SAMPLE4,8,135644313,3,116748248,
SAMPLE4,7,6037836,21,34855497,
SAMPLE4,7,109724564,14,106387943,

設定ファイルの [result_format_ca] セクションでデータの列名を次のように設定します。

example/ca_minimal/paplot.cfg
[result_format_ca]
col_chr1 = Chr1
col_break1 = Break1
col_chr2 = Chr2
col_break2 = Break2
col_opt_id = Sample

編集した設定ファイルを使用して paplot を実行します。

paplot ca {unzip_path}/example/ca_minimal/data.csv ./tmp ca_minimal \
--config_file {unzip_path}/example/ca_minimal/paplot.cfg

2. ヘッダなし

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする
データファイルから一部抜粋 (example/ca_noheader/data.csv)
SAMPLE00,intronic,GATA3
SAMPLE00,UTR3,CDH1
SAMPLE00,exonic,GATA3
SAMPLE01,splicing,WASF3
SAMPLE01,intronic,WASF3
SAMPLE01,exonic,NRAS
SAMPLE02,intronic,FBXW7
SAMPLE02,intronic,GATA3
SAMPLE02,ncRNA_intronic,ACVR2B
SAMPLE03,exonic,CAP2
SAMPLE03,intronic,PIK3CA
SAMPLE03,downstream,SEPT12

データにヘッダ行がない場合、列名でなく列番号を設定します。

設定ファイルの [result_format_ca] セクションでデータの列番号を次のように設定します。

列番号は左から順に 1 始まりで数えます。

example/ca_noheader/paplot.cfg
[result_format_ca]
# ヘッダオプションを False に設定
header = False

col_chr1 = 2
col_break1 = 3
col_chr2 = 4
col_break2 = 5
col_opt_id = 1

編集した設定ファイルを使用して paplot を実行します。

paplot ca {unzip_path}/example/ca_noheader/data.csv ./tmp ca_noheader \
--config_file {unzip_path}/example/ca_noheader/paplot.cfg

3. 変異のグルーピング

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

最小構成で作成した変異には自動的にグルーピングされており、染色体内の変異 (緑) と染色体間の変異 (紫) に色分けされています。

ここでは、グループを手動で設定するように変更します。

データファイルから一部抜粋 (example/ca_group/data.csv)
Sample,Chr1,Break1,Chr2,Break2,Label
SAMPLE1,14,16019088,12,62784483,C
SAMPLE1,9,99412502,7,129302434,B
SAMPLE1,13,84663781,18,52991509,A
SAMPLE2,11,101374238,22,26701405,B
SAMPLE2,2,121708638,7,137424167,C
SAMPLE2,16,43027789,22,23791492,C
SAMPLE3,22,34268355,10,19871820,A
SAMPLE3,14,56600342,hs37d5,5744957,B
SAMPLE3,Y,12191863,hs37d5,29189687,A
SAMPLE4,8,135644313,3,116748248,D
SAMPLE4,7,6037836,21,34855497,D
SAMPLE4,7,109724564,14,106387943,A

今回の例では、必須項目である Sample, Chr1, Break1, Chr2, Break2 列に加えて、Label 列が追加してあります。

まず、グルーピングに使用する列名 Label を設定ファイルに追加します。

設定ファイルの [result_format_ca] セクションでデータの列名を次のように設定します。

example/ca_group/paplot.cfg
[result_format_ca]
col_opt_group = Label

これで Label 列を使用してグルーピングされますが、追加で色も指定できます。

example/ca_group/paplot.cfg
[ca]
# グループの色指定
# {値}:{色名もしくは RGB 値} をグループの数だけ , 区切りで記入する
group_colors = A:#66C2A5,B:#FC8D62,C:#8DA0CB,D:#E78AC3

# 指定したグループのみ表示する
limited_group =

# 指定したグループを表示しない
nouse_group =

編集した設定ファイルを使用して paplot を実行します。

paplot ca {unzip_path}/example/ca_group/data.csv ./tmp ca_group \
--config_file {unzip_path}/example/ca_group/paplot.cfg

4. ポップアップの情報追加

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

マウスカーソルを乗せた時に表示する情報 (ポップアップ) をカスタマイズすることができます。

最小構成で表示するポップアップはこのようになっています。

_images/data_ca1.png

ここにもう少し情報を追加して変異の詳細を確認できるように変更します。

変更後

_images/data_ca2.png
データファイルから一部抜粋 (example/ca_option/data.csv)
Sample,Chr1,Break1,Dir1,Chr2,Break2,Dir2,MutationType,Gene1,Gene2
SAMPLE1,14,16019088,-,12,62784483,+,deletion,LS7T1EG444,4GRRIO5AVR
SAMPLE1,9,99412502,-,7,129302434,+,translocation,FQFW16UF5U,QP779MLPNV
SAMPLE1,13,84663781,+,18,52991509,-,deletion,Q9VX1I9U3I,7XM09ETN40
SAMPLE1,1,153160367,+,22,33751554,+,inversion,CEE2SPV1R1,PVYYQIVS8G
SAMPLE1,18,12249358,-,3,146222593,+,translocation,HH9OL7CK6G,XD80LI4E6Q
SAMPLE1,21,8658030,+,X,133492043,-,tandem_duplication,I20EVP15ZM,WPE8O5H237
SAMPLE1,12,120178477,+,1,155354923,-,deletion,IMYXD3TCA4,3MNN5J0MDN
SAMPLE2,11,101374238,+,22,26701405,+,translocation,FZ7LOS66RD,9WYBJR57E0
SAMPLE2,2,121708638,-,7,137424167,-,translocation,5655M5E46B,HB14VJXDHV
SAMPLE2,16,43027789,+,22,23791492,-,inversion,REFSIL0H2M,L5EA31R8U0
SAMPLE2,19,3862589,-,16,37135239,+,deletion,1IRWHVZLH8,6FUR9YMZOH
SAMPLE2,20,50294222,+,1,164250235,-,inversion,DOH5G0YRQ9,9TWYMR5CZ2
SAMPLE2,X,67392415,+,15,3327412,+,translocation,EM36MRX9B3,G4FPLN527D
SAMPLE3,22,34268355,+,10,19871820,+,tandem_duplication,9SVRQCFVCO,2BEWSO91FZ

今回の例では、必須項目である Sample, Chr1, Break1, Chr2, Break2 に加えて、次の 5 つを追加してあります。

  • 変異タイプ (MutationType)
  • ブレークポイント 1 の遺伝子名 (Gene1)
  • ブレークポイント 2 の遺伝子名 (Gene2)
  • ブレークポイント 1 の Direction (Dir1)
  • ブレークポイント 2 の Direction (Dir2)

このうち、変異タイプ (MutationType) と遺伝子名 (Gene1, Gene2)、Direction (Dir1, Dir2) を使用します。

まず、ポップアップの情報として追加したい列名を設定ファイルに記載します。

設定ファイルの [result_format_ca] セクションでデータの列名を次のように設定します。

example/ca_option/paplot.cfg
[result_format_ca]
col_opt_dir1 = Dir1
col_opt_dir2 = Dir2
col_opt_type = MutationType
col_opt_gene_name1 = Gene1
col_opt_gene_name2 = Gene2
col_opt_dir1 = Dir1
col_opt_dir2 = Dir2

オプションの列名は次の形式で記述します。 col_opt_{キーワード} = {実際の列名}

キーワードとは

次に、ポップアップの表示内容を変更します。

example/ca_option/paplot.cfg
[ca]
# 最小構成での設定
# tooltip_format = [{chr1}] {break1:,}; [{chr2}] {break2:,}
# 次のように変更
tooltip_format = [{chr1}] {break1:,} ({dir1}) {gene_name1}; [{chr2}] {break2:,} ({dir2}) {gene_name2}; {type}

編集した設定ファイルを使用して paplot を実行します。

paplot ca {unzip_path}/example/ca_option/data.csv ./tmp ca_option \
--config_file {unzip_path}/example/ca_option/paplot.cfg

ポップアップ (tooltip_format) 記述方法詳細は ユーザ定義フォーマット を参照してください。

Mutation Matrix レポート

ここでは、サンプルデータ [*] を使用して、Mutation Matrix レポートを出力するために必要な入力データと設定方法を解説します。

[*]サンプルデータは paplot をダウンロードして解凍したディレクトリ中、example ディレクトリにあります。

1. 最小データセット

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

paplot で Mutation Matrix を作成するために最低限必要な項目はサンプル名 (Sample)、遺伝子名 (Gene)、変異タイプ (MutationType) の3つです。

データファイルから一部抜粋 (example/mutation_minimal/data.csv)
Sample,MutationType,Gene
SAMPLE00,intronic,GATA3
SAMPLE00,UTR3,CDH1
SAMPLE00,exonic,GATA3
SAMPLE01,splicing,WASF3
SAMPLE01,intronic,WASF3
SAMPLE01,exonic,NRAS
SAMPLE02,intronic,FBXW7
SAMPLE02,intronic,GATA3
SAMPLE02,ncRNA_intronic,ACVR2B
SAMPLE03,exonic,CAP2
SAMPLE03,intronic,PIK3CA
SAMPLE03,downstream,SEPT12

今回の例では列名を Sample, MutationType, Gene としていますが、任意に設定できます。

設定ファイルの [result_format_mutation] セクションでデータの列名を次のように設定します。

example/mutation_minimal/paplot.cfg
[result_format_mutation]
col_group = MutationType
col_gene = Gene
col_opt_id = Sample

編集した設定ファイルを使用して paplot を実行します。

paplot mutation {unzip_path}/example/mutation_minimal/data.csv ./tmp mutation_minimal \
--config_file {unzip_path}/example/mutation_minimal/paplot.cfg

2. ヘッダなし

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする
データファイルから一部抜粋 (example/mutation_noheader/data.csv)
SAMPLE00,intronic,GATA3
SAMPLE00,UTR3,CDH1
SAMPLE00,exonic,GATA3
SAMPLE01,splicing,WASF3
SAMPLE01,intronic,WASF3
SAMPLE01,exonic,NRAS
SAMPLE02,intronic,FBXW7
SAMPLE02,intronic,GATA3
SAMPLE02,ncRNA_intronic,ACVR2B
SAMPLE03,exonic,CAP2
SAMPLE03,intronic,PIK3CA
SAMPLE03,downstream,SEPT12

データにヘッダ行がない場合、列名でなく列番号を設定します。 列番号は左から順に 1 始まりで数えます。

設定ファイルの [result_format_mutation] セクションでデータの列番号を次のように設定します。

example/mutation_noheader/paplot.cfg
[result_format_mutation]
# ヘッダオプションを False に設定
header = False

col_group = 2
col_gene = 3
col_opt_id = 1

編集した設定ファイルを使用して paplot を実行します。

paplot mutation {unzip_path}/example/mutation_noheader/data.csv ./tmp mutation_noheader \
--config_file {unzip_path}/example/mutation_noheader/paplot.cfg

3. ポップアップの情報追加

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

マウスカーソルを乗せた時に表示する情報 (ポップアップ) をカスタマイズすることができます。

最小構成で表示するポップアップ (グリッド部分) は以下の通りサンプル、遺伝子、変異タイプが表示されています。

変更前

_images/data_mut1.png

情報を追加して変異の場所と変異の内容を確認できるようにします。

変更後

_images/data_mut2.png
データファイルから一部抜粋 (example/mutation_option/data.csv)
Sample,Chr,Start,Ref,Alt,MutationType,Gene
SAMPLE00,chr10,8114472,A,C,intronic,GATA3
SAMPLE00,chr13,28644892,G,-,intronic,FLT3
SAMPLE00,chr13,28664636,-,G,intronic,FLT3
SAMPLE00,chr16,68795521,-,T,UTR3,CDH1
SAMPLE00,chr10,8117068,G,T,exonic,GATA3
SAMPLE00,chr3,178906688,G,A,intronic,PIK3CA
SAMPLE00,chr13,28603715,G,-,intergenic,FLT3
SAMPLE00,chr14,103368263,G,C,intronic,TRAF3

今回の例では、必須項目であるサンプル名 (Sample)、遺伝子名 (Gene)、変異タイプ (MutationType) に加えて、以下の 4 項目を追加しています。

  • 染色体 (Chr)
  • 変異開始位置 (Start)
  • リファレンスの塩基 (Ref)
  • 変異の塩基 (Alt)

まず、追加した列名を設定ファイルに記載します。

設定ファイルの [result_format_mutation] セクションでデータの列名を次のように設定します。

example/mutation_option/paplot.cfg
[result_format_mutation]
col_opt_chr = Chr
col_opt_start = Start
col_opt_ref = Ref
col_opt_alt = Alt

オプションの列名は次の形式で記述します。 col_opt_{キーワード} = {実際の列名}

キーワードとは

次に、ポップアップの表示内容を変更します。

example/mutation_option/paplot.cfg
[mutation]
# 変更前 (最小構成の設定)
# tooltip_format_checker_partial = Mutation Type[{group}]
# 次のように変更
tooltip_format_checker_partial = Mutation Type[{group}] {chr}:{start:,} [{ref} -> {alt}]

編集した設定ファイルを使用して paplot を実行します。

paplot mutation {unzip_path}/example/mutation_option/data.csv ./tmp mutation_option \
--config_file {unzip_path}/example/mutation_option/paplot.cfg

今回はグリッド部分のポップアップを変更しました。その他のポップアップ設定項目は ポップアップの表示内容 を参照してください。

また、記載方法に関するより詳細な解説は ユーザ定義フォーマット を参照してください。

Mutational Signature レポート

ここでは、サンプルデータ [*] を使用して、Mutational Signature レポートを出力するために必要な入力データと設定方法を解説します。

[*]サンプルデータは paplot をダウンロードして解凍したディレクトリ中、example ディレクトリにあります。

Mutaitonal Signature 実行手順 に従いデータを準備する場合、設定ファイルの変更は必要ありません。

1. jsonフォーマット

paplotで Mutational Signature レポートを作成するためには Mutation Matrix レポートや Chromosomal Aberration レポート、QC レポートとは異なり、jsonファイル形式で変異シグネチャのデータを用意する必要があります。

ここでは、paplotが使用する変異シグネチャのデータフォーマットについて解説します。

exampleのデータファイルをテキストエディタで開くと次のようになっています。(長いため一部省略しています)

example/signature_stack/data2.json
{
  "signature":[
                [ # signature 1
                  [0.0018,0.0003,0.0002,0.0005,0.0014,0.0008,0.0002,0.0007,0.0012,0.0003,0.0002,0.0004,0.0271,0.0107,0.0016,0.0145],  # C -> A
                  [0.0023,0.0007,0.0001,0.002,0.0027,0.0005,0.0004,0.0032,0.0007,0.0004,0.0001,0.0013,0.1546,0.0306,0.0055,0.1931],   # C -> G
                  [0.0043,0.0016,0.0027,0.0019,0.0096,0.0026,0.0046,0.0053,0.0045,0.0021,0.0034,0.0028,0.2612,0.0517,0.0284,0.1335],  # C -> T
                  [0.0012,0.0007,0.0004,0.0003,0.0003,0.0003,0,0,0.0003,0.0001,0.0003,0,0.0005,0.0001,0.0001,0.0002],                 # T -> A
                  [0.0008,0.0003,0.0008,0.0007,0.0002,0.0004,0.0009,0.0005,0.0004,0.0003,0.0006,0.0003,0.0003,0.0004,0.0002,0.0004],  # T -> C
                  [0.0001,0.0001,0.0001,0.0001,0,0.0001,0.0001,0,0.0001,0.0001,0.0009,0.0002,0.0001,0,0.0001,0.0005]                  # T -> G
                ],
                [ # signature 2
                  [0.0266,0.0222,0.0026,0.02,0.0205,0.0145,0.0012,0.0155,0.0155,0.0094,0.0009,0.011,0.0224,0.0177,0.0019,0.0307],
                  [0.0127,0.0079,0.0035,0.0145,0.0058,0.0048,0.0015,0.0115,0.0034,0.0032,0,0.0071,0.0047,0.0145,0.0006,0.0246],
                  [0.0232,0.0099,0.042,0.0184,0.014,0.0108,0.0219,0.02,0.0137,0.0102,0.0264,0.0128,0.0048,0.0186,0.0153,0.0165],
                  [0.0096,0.0084,0.0094,0.0175,0.0075,0.0076,0.0046,0.0123,0.0044,0.0035,0.0028,0.008,0.0176,0.0047,0.0031,0.0139],
                  [0.0245,0.0087,0.0144,0.0235,0.0098,0.0096,0.0051,0.0102,0.0105,0.0053,0.0042,0.0108,0.0114,0.0081,0.0038,0.0098],
                  [0.0046,0.0006,0.0036,0.0035,0.0025,0.0009,0.0028,0.0082,0.0023,0.0005,0.004,0.0048,0.0041,0.0012,0.0056,0.0104]
                ]
              ],
  "id":["PD3851a","PD3890a","PD3904a"],
  "mutation":[[0,0,0.0594],[0,1,0.7677],[0,2,0.1727],[1,0,0.1474],[1,1,0.4064],[1,2,0.4461]],
  "mutation_count":[4001,7174,5804]
}

Mutational Signature レポートを作成するためのデータ要素

signature:
変異パターンの確率値です。
各変異シグネチャごと、置換パターン (“C > A” 等) ごと、コンテキスト (“TpCpA > TpApA” 等) ごとにそれぞれの値を記入します。
base の数は 3 か 5 のどちらかを設定できますが、混在させることはできません。

サンプルデータの base は 3 であるため、コンテキストとして、次の並び順に 16 ケースの値を記述します。

ANA,ANC,ANG,ANT,CNA,CNA,CNG,CNT,GNA,GNC,GNG,GNT,TNA,TNA,TNG,TNT

もし base=5 とする場合は、次の順に 256 ケースの記述が必要です。

AANAA,AANAC,AANAG,AANAT,AANCA,AANCC,AANCG,AANCT,AANGA,AANGC,AANGG,AANGT,AANTA,AANTC,AANTG,AANTT,
ACNAA,ACNAC,ACNAG,ACNAT,ACNCA,ACNCC,ACNCG,ACNCT,ACNGA,ACNGC,ACNGG,ACNGT,ACNTA,ACNTC,ACNTG,ACNTT,
AGNAA,AGNAC,AGNAG,AGNAT,AGNCA,AGNCC,AGNCG,AGNCT,AGNGA,AGNGC,AGNGG,AGNGT,AGNTA,AGNTC,AGNTG,AGNTT,
ATNAA,ATNAC,ATNAG,ATNAT,ATNCA,ATNCC,ATNCG,ATNCT,ATNGA,ATNGC,ATNGG,ATNGT,ATNTA,ATNTC,ATNTG,ATNTT,
CANAA,CANAC,CANAG,CANAT,CANCA,CANCC,CANCG,CANCT,CANGA,CANGC,CANGG,CANGT,CANTA,CANTC,CANTG,CANTT,
CCNAA,CCNAC,CCNAG,CCNAT,CCNCA,CCNCC,CCNCG,CCNCT,CCNGA,CCNGC,CCNGG,CCNGT,CCNTA,CCNTC,CCNTG,CCNTT,
CGNAA,CGNAC,CGNAG,CGNAT,CGNCA,CGNCC,CGNCG,CGNCT,CGNGA,CGNGC,CGNGG,CGNGT,CGNTA,CGNTC,CGNTG,CGNTT,
CTNAA,CTNAC,CTNAG,CTNAT,CTNCA,CTNCC,CTNCG,CTNCT,CTNGA,CTNGC,CTNGG,CTNGT,CTNTA,CTNTC,CTNTG,CTNTT,
GANAA,GANAC,GANAG,GANAT,GANCA,GANCC,GANCG,GANCT,GANGA,GANGC,GANGG,GANGT,GANTA,GANTC,GANTG,GANTT,
GCNAA,GCNAC,GCNAG,GCNAT,GCNCA,GCNCC,GCNCG,GCNCT,GCNGA,GCNGC,GCNGG,GCNGT,GCNTA,GCNTC,GCNTG,GCNTT,
GGNAA,GGNAC,GGNAG,GGNAT,GGNCA,GGNCC,GGNCG,GGNCT,GGNGA,GGNGC,GGNGG,GGNGT,GGNTA,GGNTC,GGNTG,GGNTT,
GTNAA,GTNAC,GTNAG,GTNAT,GTNCA,GTNCC,GTNCG,GTNCT,GTNGA,GTNGC,GTNGG,GTNGT,GTNTA,GTNTC,GTNTG,GTNTT,
TANAA,TANAC,TANAG,TANAT,TANCA,TANCC,TANCG,TANCT,TANGA,TANGC,TANGG,TANGT,TANTA,TANTC,TANTG,TANTT,
TCNAA,TCNAC,TCNAG,TCNAT,TCNCA,TCNCC,TCNCG,TCNCT,TCNGA,TCNGC,TCNGG,TCNGT,TCNTA,TCNTC,TCNTG,TCNTT,
TGNAA,TGNAC,TGNAG,TGNAT,TGNCA,TGNCC,TGNCG,TGNCT,TGNGA,TGNGC,TGNGG,TGNGT,TGNTA,TGNTC,TGNTG,TGNTT,
TTNAA,TTNAC,TTNAG,TTNAT,TTNCA,TTNCC,TTNCG,TTNCT,TTNGA,TTNGC,TTNGG,TTNGT,TTNTA,TTNTC,TTNTG,TTNTT

寄与度グラフ描画データ

この項目はオプションです。

寄与度グラフは、各変異シグネチャに関連づけられている変異はどれくらいの数かを示す積み上げグラフです。 入力 json ファイルに id, mutation, mutation_count が設定されている場合、サンプル毎に変異シグネチャの寄与度グラフ ( 例 ) を作成します。

id:
サンプル名のリストです。
mutation_count:
サンプルごとの変異数です。
上記の例の場合、PD3851a の変異数=4001、PD3890a の変異数=7174、PD3904a の変異数=5804 となります。
mutation:
サンプルごと、変異シグネチャごとの割合を設定します。
[sample index, signature index, value] の順に記載します。

sample index は id で記載した順に 0 からカウントします。
上記の例の場合の sample index は PD3851a=0、PD3890a=1、PD3904a=2 となります。

signature index は signature で記載した順に 0 からカウントします。
上記の例の場合の signature index は signature1 = 0、signature2 = 1、background = 2 となります。

注釈

キーは変更可能です。キーを変更した場合は設定ファイル ([result_format_signature] セクションの key_* オプション) を変更してください。

example/signature_stack/paplot.cfg
[result_format_signature]
# json ファイルのキー
key_signature = signature
key_id = id
key_mutation = mutation
key_mutation_count = mutation_count

注釈

json ファイルの確認

paplot は python の json パッケージを使用しているため、次のコマンドで読めれば OK です。

json パッケージを使用したファイル確認例 (ファイル名が “data2.json” の場合)

$ python
>>> import json
>>> json.load(open("data2.json"))

2. 最小データセット

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

入力データ形式は 1. jsonフォーマット 参照。

Mutaitonal Signature 実行手順 の手順でデータの準備を行う場合、設定ファイルの変更は必要ありません。

データファイル (変異シグネチャ数は 2)

example/signature_minimal/data.json
{
  "signature":[
    # signature 1
    [
      [0.0021,0.0006,0.0002,0.0007,0.0017,0.001,0.0003,0.0009,0.0014,0.0006,0.0003,0.0006,0.027,0.0108,0.0016,0.0147],
      [0.0025,0.0009,0.0002,0.0022,0.0029,0.0007,0.0005,0.0034,0.0009,0.0006,0.0002,0.0014,0.1504,0.0301,0.0053,0.1884],
      [0.0046,0.0018,0.0031,0.0021,0.0097,0.0029,0.0049,0.0055,0.0047,0.0024,0.0037,0.003,0.2557,0.0513,0.0286,0.1312],
      [0.0014,0.0009,0.0007,0.0006,0.0004,0.0005,0.0003,0.0003,0.0004,0.0003,0.0005,0.0002,0.0008,0.0003,0.0003,0.0005],
      [0.001,0.0004,0.0011,0.001,0.0003,0.0007,0.0012,0.0008,0.0006,0.0004,0.0007,0.0005,0.0005,0.0007,0.0004,0.0007],
      [0.0003,0.0003,0.0003,0.0003,0.0001,0.0003,0.0003,0.0003,0.0002,0.0002,0.0011,0.0004,0.0003,0.0002,0.0003,0.0009]
    ],
    # signature 2
    [
      [0.022,0.0183,0.0028,0.0171,0.0192,0.0148,0.0026,0.0157,0.0143,0.0108,0.0018,0.0116,0.0181,0.016,0.0021,0.0246],
      [0.0133,0.0088,0.0037,0.0136,0.0095,0.008,0.003,0.0131,0.0065,0.0063,0.0016,0.0095,0.0044,0.0135,0.0016,0.0171],
      [0.0195,0.0098,0.0283,0.0159,0.0138,0.0112,0.0156,0.0183,0.0128,0.0108,0.0186,0.0127,0,0.0146,0.0095,0.0115],
      [0.0095,0.0085,0.0102,0.0155,0.0077,0.0102,0.0096,0.0135,0.0054,0.0052,0.0058,0.0089,0.0145,0.0076,0.0058,0.016],
      [0.0192,0.0089,0.0135,0.0198,0.0089,0.0113,0.0092,0.0117,0.0092,0.0063,0.0064,0.01,0.0107,0.0096,0.0061,0.0123],
      [0.0059,0.0028,0.0068,0.0063,0.0039,0.0044,0.0076,0.0101,0.004,0.0028,0.007,0.0064,0.006,0.0046,0.008,0.0132]
    ]
  ]
}

設定ファイル

example/signature_minimal/paplot.cfg
[signature]
tooltip_format_signature_title = {sig}
tooltip_format_signature_partial = {route}: {#sum_item_value:6.2}

signature_y_max = -1

alt_color_CtoA = #1BBDEB
alt_color_CtoG = #211D1E
alt_color_CtoT = #E62623
alt_color_TtoA = #CFCFCF
alt_color_TtoC = #ACD577
alt_color_TtoG = #EDC7C4

[result_format_signature]
format = json
background = False
key_signature = signature

paplot を実行します。

paplot signature signature_minimal/data.json ./tmp signature_minimal \
--config_file ./signature_minimal/paplot.cfg

上記のコマンドを実行すると以下の場所にレポートが作成されます。

ここで出力されるレポートファイルの名称 graph_signature2.html には変異シグネチャ数が反映されています。

変異シグネチャ数は paplot 実行時に入力データ (data.json) から paplot が読み取ります。

./tmp
  ┗ signature_minimal
      ┗ graph_signature2.html

3. 複数データファイルの変異シグネチャ

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

入力データ形式は 1. jsonフォーマット 参照。

Mutaitonal Signature 実行手順 の手順でデータの準備を行う場合、設定ファイルの変更は必要ありません。

変異シグネチャ解析においては、クラスタリング数を 2 や 3 などに固定せず、2 ～ 6 など幅を持たせた数で試験的に解析を行い、結果をみて適切なクラスタ数を決定することがあります。

今回のセクションでは、変異シグネチャのデータファイルを複数使用します。

今回の場合、以下のファイル構成になります。

example/signature_multi_class/

   # データファイル
  ┣ data2.json  # signature num = 2
  ┣ data3.json  # signature num = 3
  ┣ data4.json  # signature num = 4
  ┣ data5.json  # signature num = 5
  ┣ data6.json  # signature num = 6

   # 設定ファイル
  ┗ paplot.cfg

変異シグネチャのデータファイルごとに paplot を実行します。

paplot signature signature_multi_class/data2.json ./tmp signature_multi_class \
--config_file ./signature_multi_class/paplot.cfg

paplot signature signature_multi_class/data3.json ./tmp signature_multi_class \
--config_file ./signature_multi_class/paplot.cfg

paplot signature signature_multi_class/data4.json ./tmp signature_multi_class \
--config_file ./signature_multi_class/paplot.cfg

paplot signature signature_multi_class/data5.json ./tmp signature_multi_class \
--config_file ./signature_multi_class/paplot.cfg

paplot signature signature_multi_class/data6.json ./tmp signature_multi_class \
--config_file ./signature_multi_class/paplot.cfg

下記のようにまとめて実行することもできます。

paplot signature "signature_multi_class/data*.json" ./tmp signature_multi_class \
--config_file ./signature_multi_class/paplot.cfg

上記のコマンドを実行すると以下の場所にレポートが作成されます。

ここで出力されるレポートファイルの名称 graph_signature2.html には変異シグネチャ数が反映されています。

変異シグネチャ数は paplot 実行時に入力データ (data.json) から paplot が読み取ります。

./tmp
  ┗ signature_multi_class
      ┣ graph_signature2.html
      ┣ graph_signature3.html
      ┣ graph_signature4.html
      ┣ graph_signature5.html
      ┗ graph_signature6.html

4. 寄与度グラフ

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

レポートに変異の内訳グラフを追加します。 Mutaitonal Signature 実行手順 によりデータの準備を行う場合、あらかじめ出力するように設定しています。

入力データ形式は 1. jsonフォーマット 参照。

複数データ実行方法は 3. 複数タイプの変異シグネチャ 参照。

paplot を実行します。

paplot signature "signature_stack/data*.json" ./tmp signature_stack \
--config_file ./signature_stack/paplot.cfg

pmsignature レポート

ここでは、サンプルデータ [*] を使用して、pmsignature レポートを出力するために必要な入力データと設定方法を解説します。

[*]サンプルデータは paplot をダウンロードして解凍したディレクトリ中、example ディレクトリにあります。

pmsignature 実行手順 の手順でデータの準備を行う場合、設定ファイルの変更は必要ありません。

1. jsonフォーマット

paplot で pmsignature レポートを作成するためには Mutation Matrix レポートや Chromosomal Aberration レポート、QC レポートとは異なり、json ファイル形式で pmsignature データを用意する必要があります。

ここでは、paplot が使用する pmsignature データのフォーマットについて解説します。

exampleのデータファイルをテキストエディタで開くと次のようになっています。(長いため一部省略しています)

example/pmsignature_stack/data2.json
{
  "ref":[
          [ # pmsignature 1
            [0.338,0.15,0.183,0.327],  # ref1 (A,C,G,T)
            [0.362,0.191,0.177,0.267], # ref2 (A,C,G,T)
            [0,0.731,0,0.268],         # ref3 (A,C,G,T)
            [0.31,0.165,0.251,0.272],  # ref4 (A,C,G,T)
            [0.295,0.193,0.168,0.341]  # ref5 (A,C,G,T)
          ],
          [ # pmsignature 2
            [0.179,0.414,0.084,0.321],
            [0.007,0.025,0.004,0.962],
            [0,0.999,0,0],
            [0.472,0.104,0.041,0.381],
            [0.277,0.175,0.284,0.262]
          ]
        ],
  "alt":[
          [ # pmsignature 1
            [0,0,0,0],                 # altA (A,C,G,T)
            [0.194,0,0.091,0.445],     # altC (A,C,G,T)
            [0,0,0,0],                 # altG (A,C,G,T)
            [0.093,0.163,0.011,0]      # altT (A,C,G,T)
          ],
          [ # pmsignature 2
            [0,0,0,0],
            [0.059,0,0.437,0.502],
            [0,0,0,0],
            [0,0,0,0]
          ]
        ],
  "strand":[
            [0.461,0.538],  # pmsignature 1
            [0.512,0.487]   # pmsignature 2
           ],
  "id":["PD3851a","PD3890a","PD3904a"],
  "mutation":[[0,0,0.535],[0,1,0.038],[0,2,0.426],[1,0,0.186],[1,1,0.156],[1,2,0.656]],
  "mutation_count":[702,2312,2096]
}
_images/exec_pmsig1.PNG

pmsignature レポートを作成するためのデータ要素

ref:
各 pmsignature のリファレンス塩基 (A → C → G → T の順) の値です。
paplot が再計算しますので、合計して 1 になる必要はありません。
今回の例では base の数が 5 ですが、3 や 7 など奇数であれば変更可能です。
alt:
各 pmsignature の alternative 塩基 (各中央のリファレンス塩基に対して A → C → G → T の順) の値です。
各リファレンス塩基 A, C, G, Tの 4 つの値を A → C → G → T の順に記入します。したがって、各 pmsignature には合計 16 の値が必要です。
通常、中央の塩基は C または T に固定されているため、参照塩基が A または G の値はゼロに設定できます。
strand:
各 pmsignature の strand (plus → minus の順) の値です。
strand が無い場合は [0,0] を記入します。

寄与度グラフ描画データ

この項目はオプションです。

寄与度グラフは、各 pmsignature に関連づけられている変異はどれくらいの数かを示す積み上げグラフです。 入力 json ファイルに id, mutation, mutation_count が設定されている場合、サンプル毎に pmsignature の寄与度グラフ ( 例 ) を作成します。

id:
サンプル名のリストです。
mutation_count:
サンプルごとの変異数です。
上記の例の場合、PD3851a の変異数=702、PD3890a の変異数=2312、PD3904a の変異数=2096 となります。
mutation:
サンプルごと、pmsignature ごとの割合を設定します。
[sample index, pmsignature index, value] の順に記載します。

sample index は id で記載した順に 0 からカウントします。
上記の例の場合の sample index は PD3851a=0、PD3890a=1、PD3904a=2 となります。

pmsignature index は ref で記載した順に 0 からカウントします。
background を使用する場合、signature1, signature2, ..., background の順にカウントします。
上記の例の場合の pmsignature index は signature1 = 0、signature2 = 1、background = 2 となります。

注釈

キーは変更可能です。キーを変更した場合は設定ファイル ([result_format_pmsignature] セクションの key_* オプション) を変更してください。

example/pmsignature_stack/paplot.cfg
[result_format_pmsignature]
format = json
background = True
key_ref = ref
key_alt = alt
key_strand = strand
key_id = id
key_mutation = mutation
key_mutation_count = mutation_count

注釈

json ファイルの確認

paplot は python の json パッケージを使用しているため、次のコマンドで読めれば OK です。

json パッケージを使用したファイル確認例 (ファイル名が “data2.json” の場合)

$ python
>>> import json
>>> json.load(open("data2.json"))

2. 最小データセット

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

入力データ形式は 1. jsonフォーマット 参照。

pmsignature 実行手順 に従いデータの準備を行う場合、設定ファイルの変更は必要ありません。

データファイル (pmsignature 数は 2)

example/pmsignature_minimal/data.json
{
  "ref":[[[0.189,0.395,0.088,0.326],[0.019,0.029,0.01,0.94],[0,0.999,0,0],[0.467,0.103,0.054,0.374],[0.278,0.175,0.276,0.268]]],
  "alt":[[[0,0,0,0],[0.063,0,0.415,0.521],[0,0,0,0],[0,0,0,0]]],
  "strand":[[0.514,0.485]]
}

設定ファイル

example/pmsignature_minimal/paplot.cfg
[pmsignature]
tooltip_format_ref1 = A: {a:.2}
tooltip_format_ref2 = C: {c:.2}
tooltip_format_ref3 = G: {g:.2}
tooltip_format_ref4 = T: {t:.2}
tooltip_format_alt1 = C -> A: {ca:.2}
tooltip_format_alt2 = C -> G: {cg:.2}
tooltip_format_alt3 = C -> T: {ct:.2}
tooltip_format_alt4 = T -> A: {ta:.2}
tooltip_format_alt5 = T -> C: {tc:.2}
tooltip_format_alt6 = T -> G: {tg:.2}
tooltip_format_strand = + {plus:.2} - {minus:.2}

color_A = #06B838
color_C = #609CFF
color_G = #B69D02
color_T = #F6766D
color_plus = #00BEC3
color_minus = #F263E2

[result_format_pmsignature]
format = json
background = True
key_ref = ref
key_alt = alt
key_strand = strand

paplot を実行します。

paplot pmsignature pmsignature_minimal/data.json ./tmp pmsignature_minimal \
--config_file ./pmsignature_minimal/paplot.cfg

上記のコマンドを実行すると以下の場所にレポートが作成されます。

ここで出力されるレポートファイルの名称 graph_pmsignature2.html には pmsignature 数が反映されています。

pmsignature 数は paplot 実行時に入力データ (data.json) から paplot が読み取ります。

./tmp
  ┗ pmsignature_minimal
      ┗ graph_pmsignature2.html

注釈

この例では pmsignature の出力に background を設定しています。 そのため、1 つの pmsignature に background signature を割り当てていますので、実際に表示されている pmsignature は 1 つ少ないように見えますがこれで正しい表示です。

3. 複数データファイルの pmsignature

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

入力データ形式は 1. jsonフォーマット 参照。

pmsignature 実行手順 の手順でデータの準備を行う場合、設定ファイルの変更は必要ありません。

pmsignature 解析においては、クラスタリング数を 2 や 3 などに固定せず、2 ～ 6 など幅を持たせた数で試験的に解析を行い、結果をみて適切なクラスタ数を決定することが一般的です。

したがって今回のセクションでは、pmsignature のデータファイルを複数使用します。

今回の場合、以下のファイル構成になります。

example/pmsignature_multi_class/

   # データファイル
  ┣ data2.json  # pmsignature num = 2
  ┣ data3.json  # pmsignature num = 3
  ┣ data4.json  # pmsignature num = 4
  ┣ data5.json  # pmsignature num = 5
  ┣ data6.json  # pmsignature num = 6

   # 設定ファイル
  ┗ paplot.cfg

pmsignature のデータファイルごとに paplot を実行します。

paplot pmsignature pmsignature_multi_class/data2.json ./tmp pmsignature_multi_class \
--config_file ./pmsignature_multi_class/paplot.cfg

paplot pmsignature pmsignature_multi_class/data3.json ./tmp pmsignature_multi_class \
--config_file ./pmsignature_multi_class/paplot.cfg

paplot pmsignature pmsignature_multi_class/data4.json ./tmp pmsignature_multi_class \
--config_file ./pmsignature_multi_class/paplot.cfg

paplot pmsignature pmsignature_multi_class/data5.json ./tmp signature_multi_class \
--config_file ./pmsignature_multi_class/paplot.cfg

paplot pmsignature pmsignature_multi_class/data6.json ./tmp pmsignature_multi_class \
--config_file ./pmsignature_multi_class/paplot.cfg

下記のようにまとめて実行することもできます。

paplot pmsignature "pmsignature_multi_class/data*.json" ./tmp pmsignature_multi_class \
--config_file ./pmsignature_multi_class/paplot.cfg

上記のコマンドを実行すると以下の場所にレポートが作成されます。

ここで出力されるレポートファイルの名称 graph_signature2.html には pmsignature 数が反映されています。

pmsignature 数は paplot 実行時に入力データ (data.json) から paplot が読み取ります。

./tmp
  ┗ pmsignature_multi_class
      ┣ graph_pmsignature2.html
      ┣ graph_pmsignature3.html
      ┣ graph_pmsignature4.html
      ┣ graph_pmsignature5.html
      ┗ graph_pmsignature6.html

注釈

この例では pmsignature の出力に background を設定しています。 そのため、1 つの pmsignature に background signature を割り当てていますので、実際に表示されている pmsignature は 1 つ少ないように見えますがこれで正しい表示です。

4. 寄与度グラフ

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

レポートに変異の内訳グラフを追加します。 pmsignature 実行手順 の手順でデータの準備を行う場合、あらかじめ出力するように設定しています。

入力データ形式は 1. jsonフォーマット 参照。

複数データ実行方法は 3. 複数データファイルの pmsignature 参照。

paplot を実行します。

paplot pmsignature "pmsignature_stack/data*.json" ./tmp pmsignature_stack \
--config_file ./pmsignature_stack/paplot.cfg

注釈

この例では pmsignature の出力に background を設定しているため、実際に出力される pmsignature は 1 少ない数が表示されます。 (寄与度グラフの最後の pmsignature は background シグネチャです)

5. Backgroundなし

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

通常、pmsignature は background ありで作成しますが、background なしで作成することもできます。

手順詳細は pmsignature 実行手順 を参照ください。

  1. pmsignature を background なしで作成します。
library(pmsignature)

# use sample data
inputFile <- system.file("extdata/Nik_Zainal_2012.mutationPositionFormat.txt.gz", package="pmsignature")
G <- readMPFile(inputFile, numBases = 5, trDir = TRUE)

# background を使用する場合
# BG_prob <- readBGFile(G)
# Param <- getPMSignature(G, K = 3, BG = BG_prob)
# Boot <- bootPMSignature(G, Param0 = Param, bootNum = 100, BG = BG_prob)

# background を使用しない場合
Param <- getPMSignature(G, K = 3)
Boot <- bootPMSignature(G, Param0 = Param, bootNum = 100)

# save .Rdata
resultForSave <- list(Param, Boot)
save(resultForSave, file="pmsignature_ind3.Rdata")
  1. 作成した Rdata を json に変換します。
R --vanilla --slave --args ./pmsignature_ind3.Rdata ./pmsignature_ind3.json < {path to genomon_Rscripts}/pmsignature/convert_toJson_ind.R
  1. 設定ファイルで background オプションを False に設定します。
example/pmsignature_nobackground/paplot.cfg
[result_format_pmsignature]
background = False
  1. paplot を実行します。
paplot pmsignature pmsignature_nobackground/data.json ./tmp pmsignature_nobackground \
--config_file ./pmsignature_nobackground/paplot.cfg

共通項目

ここでは、サンプルデータ [*] を使用して、それぞれのレポートで共通している事柄について解説します。

[*]サンプルデータは paplot をダウンロードして解凍したディレクトリ中、example ディレクトリにあります。

1. データ区切り

データファイルがタブ区切りであった場合、次のように設定します。

# Mutation Matrix レポートの場合
[result_format_mutation]
sept = \t

# スペース区切りの場合
sept = " "

QC レポートの場合は [result_format_qc] セクション、Chromosomal Aberration レポートの場合は [result_format_ca] セクションを変更してください。

2. コメント行

# This is comment.
# Please skip this line.

ID,Type,Gene
SAMPLE00,intronic,GATA3
SAMPLE00,UTR3,CDH1

このようにデータファイルにコメント行がある場合、次のようにコメント行の開始文字を設定することで、読み飛ばしできます。 開始文字が統一されていない場合は読み飛ばしできませんので、手動で削除してください。

# Mutation Matrix レポートの場合
[result_format_mutation]
comment = #

QC レポートの場合は [result_format_qc] セクション、Chromosomal Aberration レポートの場合は [result_format_ca] セクションを変更してください。

3. データファイルが分かれている場合

多くの場合、がんゲノム研究においては複数のシーケンスデータを使用します。paplot が生成するレポートも複数のサンプルの情報で構成されています。 paplot で複数のサンプルを使用して入力データを準備するには、次の2つの方法があります。

  • case1: マージされたファイルを入力する

    この場合、サンプル名が記述されたデータ列があるはずです。 col_opt_id で指定してください。

  • case2: サンプルごとに分かれたファイルを入力する

    ファイル名の一部をサンプル名として使用します。 suffix を必ず指定してください。

これまでのサンプルでは、case1 について記述してきました。ここでは case2 の入力方法を解説します。

このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

今回の例では以下のようにサンプル毎にデータが分かれています。

example/mutation_split_file/

   # データファイル
  ┣ SAMPLE00.data.csv  # SAMPLE00の結果ファイル
  ┣ SAMPLE01.data.csv  # SAMPLE01の結果ファイル
  ┣ SAMPLE02.data.csv  # SAMPLE02の結果ファイル
  ┣ SAMPLE03.data.csv  # SAMPLE03の結果ファイル
  ┣ SAMPLE04.data.csv  # SAMPLE04の結果ファイル

   # 設定ファイル
  ┗ paplot.cfg
データファイルから一部抜粋 (example/mutation_split_file/SAMPLE00.data.csv)
MutationType,Gene
intronic,GATA3
intronic,FLT3
intronic,FLT3
UTR3,CDH1
exonic,GATA3

設定ファイルで suffix を設定します。

example/mutation_split_file/paplot.cfg
 [result_format_mutation]
 suffix = .data.csv

 # 今回は col_opt_id は使用しません
 col_opt_id =

suffix を指定すると、suffix 手前までのファイル名をサンプル名として使用します。

_images/id_suffix.PNG

編集した設定ファイルを使用して paplot を実行します。

# Mutation Matrix レポートの場合

# 複数ファイル指定する場合は , で区切る
paplot mutation {unzip_path}/example/mutation_split_file/SAMPLE00.data.csv,{unzip_path}/example/mutation_split_file/SAMPLE01.data.csv ./tmp mutation_split_file \
--config_file {unzip_path}/example/mutation_split_file/paplot.cfg

# ワイルドカードを使用して、まとめて指定することも可能
# 最初と最後に " を付けること
paplot mutation "{unzip_path}/example/mutation_split_file/*.csv" ./tmp mutation_split_file \
--config_file {unzip_path}/example/mutation_split_file/paplot.cfg

QC レポートの場合は [result_format_qc] セクション、Chromosomal Aberration レポートの場合は [result_format_ca] セクションを変更してください。

4. キーワード

4-1. キーワードとは

paplot では設定ファイルに記入した各データ列をキーワードとして使用できます。

設定ファイルで次のように記入したとします。

[result_format_mutation]
# 必須項目
# col_{key} = {実際の列名}
#
col_gene = Gene
col_group = MutationType

# オプション
# col_opt_{key} = {実際の列名}
#
col_opt_id = Sample
col_opt_start = Start
col_opt_end = End

col_{key} = {実際の列名} もしくは col_opt_{key} = {実際の列名} と記入した項目のうち、{key} がキーワードになります。

キーワードは任意で増やすことができますが、以下の点にご注意ください。

  • 大文字と小文字の区別はありません。たとえば、CHR、Chr、chr はすべて同一とみなしますので、ご注意ください。
  • 半角英数字 (1-9, a-z, A-Z) および “_” 以外は使用できません。
  • col_opt_id は予約済みですので、サンプル名以外の用途には使用できません。
  • Mutation Matrix レポートと Chromosomal Aberration レポートにおいては col_opt_group も予約済みですので、グループ化以外の用途には使用できません。
  • Mutational Signature レポートと pmsignature レポートには追加できません。

5. ユーザ定義フォーマット

マウスカーソルを乗せた時に表示する情報 (ポップアップ) の内容はある程度変更することができます。

表示箇所ごとにそれぞれ設定しますが、書き方は同一です。

設定例

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

表示例：
type[exome], chr1:2000:2001, [A -> T]

{} で囲った文字がキーワードで、実際の値に置き換えられます。

キーワードとは

5-1. 数値計算

キーワードを 1 つ以上使用して数値計算させることもできます。その場合、計算式を {} で囲います。

{key1/key2*100}%

表示例：
3.33333333333333%

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

{key1/key2*100:.2}%

表示例：
3.33%

5-2. 桁区切り

数値に桁区切りを付けて表示したい場合、キーワードの後に :, と書きます。

{key1}%

表示例：
123456789

{key1:,}%

表示例：
123,456,789

設定ファイル解説

1. Mutation Matrix

全設定項目

###################### Mutation Matrix
[mutation]
# 遺伝子のサンプルに対する検出比 (%)
# 値より小さい遺伝子はプロット対象から除外する
# 0 の場合はすべて出力する
use_gene_rate = 0

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

# 入力されていた場合、その遺伝子はプロット対象から除外する
# , 区切りで複数指定可能
#
# nouse_gene = NONE,MUC4
nouse_gene =

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

# 入力されていた場合、その変異タイプはプロット対象から除外する
# , 区切りで複数指定可能
# 空白行を除去する場合、_blank_ と記入する
nouse_group = _blank_,unknown,synonymous_SNV

# 変異タイプのプロット色を指定する。変異タイプ名:(RGB もしくは色名)
# , 区切りで複数指定可能
# 未入力の変異タイプはデフォルト色を使用する
group_color = stopgain:#E85299,frameshift_deletion:#F39600,frameshift_insertion:#E60011,nonframeshift_deletion:#9CAEB7

# ポップアップの表示内容
# 詳細は次項目「ポップアップの表示内容」に記載
tooltip_format_checker_title1 = Sample:{id}, Gene:{gene}, {#sum_item_value}
tooltip_format_checker_partial = Mutation Type[{group}]
tooltip_format_gene_title = Gene:{gene}, {#sum_item_value}
tooltip_format_gene_partial = Mutation Type:{group}, {#item_value}
tooltip_format_id_title = Sample:{id}, {#sum_item_value}
tooltip_format_id_partial = Mutation Type:{group}, {#item_value}

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

# 複数入力時に使用
suffix =

# データ区切り
sept = \t

# ヘッダ有り無し (ない場合はFalse)
header = True

# コメント行の先頭文字
comment = #

# 変異タイプが 1 行に複数入力されている場合の区切り文字
sept_func = ;

# 遺伝子が 1 行に複数入力されている場合の区切り文字
sept_gene = ;

# -----------------------
# 使用する列名を定義
# -----------------------
# グループ化するデータの列名 (ここでは変異タイプを使用する)
col_group = MutationType
# 遺伝子の列名
col_gene = Gene
# サンプル名の列名
col_opt_id = Sample

# 出力フォーマット
# 通常、変更する必要はありません。
[merge_format_mutation]
# カラムがない場合、何で埋めるか
lack_column_complement = NA

ポップアップの表示内容

表示箇所ごとに6種類設定しますが、書き方は同一です。

設定項目と表示との対応

_images/conf_mut4.PNG

記載方法は ユーザ定義フォーマット を参照してください。

データ列とは別に以下も特殊キーワードとして使用することができます。

Mutation Matrixの集計について limited_group や nouse_group 等のオプションを使用して変異を限定した場合、使用しなかった変異はカウントしません。
{#number_id}:サンプル数
{#number_gene}:遺伝子数
{#number_mutaion}:
 変異の数 (同一サンプルが同一遺伝子で複数回検出されても1としてカウントする)
{#sum_mutaion}:検出した変異の総数
{#item_value}:積み上げグラフの1項目の値
{#sum_item_value}:
 積み上げグラフの合計値

サブプロットとしてクリニカルデータを追加

このセクションで生成するレポートを見る
このセクションで使用するデータセットを見る
このセクションで使用するデータセットをダウンロードする

クリニカルデータのような変異以外のサンプルに関する情報をサブプロットとして Mutation Matrix に追加することができます。

_images/data_mut3.PNG

example では別ファイルとして以下のデータファイルを用意しています。

example/mutation_subplot/data_subplot.csv
Sample,Gender,Age,BMI
SAMPLE00,F,30,40
SAMPLE01,F,62,25
SAMPLE02,F,59,34
SAMPLE03,M,66,26
SAMPLE04,M,53,40
SAMPLE05,F,79,27
SAMPLE06,M,64,29
SAMPLE07,M,54,22
SAMPLE08,F,55,35

今回の例では、Sample、Gender、Age、BMIを用意していますが、そのうち、必須項目は Sample (サンプル名) です。 変異のファイルとサブデータのファイルがサンプル名で紐づけられることが重要です。

設定ファイルにサブプロットの設定を追加します。

重要 : path にサブプロットデータファイルのパスを記入してください。

[mutation_subplot_type1_1] セクションを追加し、次のように設定します。

example/mutation_subplot/paplot.cfg
### sample for subplot
[mutation_subplot_type1_1]

# サブプロットのタイトル
title = Clinical Gender

# サブプロットのデータファイルのパスを設定します
path = {unzip_path}/example/mutation_subplot/data_subplot.csv

# データ区切り
sept = ,

# ヘッダ有り無し (ヘッダがない場合は False)
header = True

# コメント行の先頭文字
comment =

# -----------------------
# 使用する列名を定義
# -----------------------
# サンプル名の列名 (ヘッダがない場合は列番号)
col_id = Sample
# データの列名
col_value = Gender

# 表示形式 (欄外参照)
# fix/range/gradient から選択
mode = fix

# サブプロットの色と凡例 (欄外参照)
name_set = M:Male:blue, F:Female:red
サブプロットの表示位置

サブプロットの表示位置は 2 つあり、type1 はサンプルグラフの下に、type2 は最後に表示します。

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

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

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

サブプロットの表示形式

表示形式 (mode) は3種類あり、fix/range/gradient から選択します。

_images/conf_mut3.PNG
name_set の書き方

サブプロットの色と凡例を定義します。

{値}:{表示文字列}:{セルの色} を各値ごとに記入します。{セルの色} は省略可能です。

mode = fix の場合

name_set = 0:Male:blue, 1:Female:red, 2:Unknown:gray

mode = range の場合

{値} には範囲開始の値を記入します。

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)

編集した設定ファイルを使用して paplot を実行します。

paplot mutation {unzip_path}/example/mutation_subplot/data.csv ./tmp mutation_subplot \
--config_file {unzip_path}/example/mutation_subplot/paplot.cfg

2. QC

全設定項目

###################### qc
[qc]
# (none)

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

# 複数入力時に使用
suffix = .qc.csv

# データ区切り
sept = ,

# ヘッダ有り無し (ない場合は False)
header = True

# コメント行の先頭文字
comment = #

# 使用する列名を定義
col_opt_id = Sample
col_opt_key1 = AverageDepth

# 出力フォーマット
# 通常、変更する必要はありません。
[merge_format_qc]
# カラムがない場合、何で埋めるか
lack_column_complement = NA

# 領域選択用のグラフ設定
[qc_chart_brush]
stack = {key1}
name_set = Average depth:#E3E5E9

# グラフ設定 (グラフごとに用意する)
[qc_chart_1]
title = Depth average
title_y = Average of depth
stack1 = {key1}
name_set = Average depth:#2478B4
tooltip_format1 = Sample:{id}
tooltip_format2 = {key1:.2}

ポップアップの表示内容

記載方法は ユーザ定義フォーマット を参照してください。

3. Chromosomal Aberration

全設定項目

###################### sv
[genome]
# ゲノムサイズを羅列したファイル (CSV形式)
# 初期値は hg19 で 標準ファイルは paplot インストールディレクトリ配下の genome ディレクトリにあります
#
# for example.
# (linux)
# path = ~/tmp/genome/hg19.csv
# (windows)
# path = C:\genome\hg19_part.csv
path =

[ca]
# 使用する染色体 (, で区切る)
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

# 円形のプロットにて染色体の色を指定する場合、次のようにします (色名もしくは RGB 値が使用可能です)
# use_chrs = 1:Chr1:crimson, 2:Chr2:lightpink, 3:Chr3:mediumvioletred, 4:Chr4:violet, 5:Chr5:darkmagenta, 6:Chr6:#F39600

# 積み上げグラフの染色体分割サイズ (bps)
selector_split_size = 5000000

##################
# group setting
# [result_format_ca] col_opt_group が設定されている場合のみ有効
##################

# 入力されていた場合、そのグループのみ出力する
# 未入力の場合、検出されたグループすべて出力する
# , 区切りで複数指定可能
#
limited_group = stopgain,frameshift_deletion,frameshift_insertion

# 入力されていた場合、そのグループはプロット対象から除外する
# , 区切りで複数指定可能
# 空白行を除去する場合、_blank_ と記入する
nouse_group = _blank_,unknown,synonymous_SNV

# グループのプロット色を指定する。グループ名:(色名もしくは RGB 値)
# , 区切りで複数指定可能
# 未入力のグループはデフォルト色を使用する
group_colors = stopgain:#E85299,frameshift_deletion:#F39600,frameshift_insertion:#E60011

# 円形プロットのポップアップ表示内容
tooltip_format = [{chr1}] {break1:,}; [{chr2}] {break2:,}

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

# 複数入力時に使用
suffix = .result.txt

# データ区切り
sept = \t

# ヘッダ有り無し (ヘッダがない場合は False)
header = True

# コメント行の先頭文字
comment = #

# -----------------------
# 使用する列名を定義
# -----------------------

# 切断点 1 の染色体
col_chr1 = Chr_1

# 切断点 1 の位置
col_break1 = Pos_1

# 切断点 2 の染色体
col_chr2 = Chr_2

# 切断点 2 の位置
col_break2 = Pos_2

# グループ化するデータの列名
col_opt_group =

# サンプル名の列名
col_opt_id =

# 出力フォーマット
# 通常、変更する必要はありません。
[merge_format_ca]
# カラムがない場合、何で埋めるか
lack_column_complement = NA
# データ区切り
sept = ,

表示する染色体を限定する

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

[ca]
# 使用する染色体 (, で区切る)
# 初期値
# 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

# 染色体 1、5、7 を使用する場合
use_chrs = 1,5,7

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

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

ヒト以外のゲノムを使用する

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

先頭列に染色体名、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

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

_images/qa_genome_size.PNG

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

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

ポップアップの表示内容

記載方法は ユーザ定義フォーマット を参照してください。
SV には Mutation Matrix のような特殊キーワードはありません。

4. Mutational Signature

全設定項目

###################### Mutational Signature
[signature]

# ポップアップの表示内容
tooltip_format_signature_title = {sig}
tooltip_format_signature_partial = {route}: {#sum_item_value:6.2}
tooltip_format_mutation_title = {id}
tooltip_format_mutation_partial = {sig}: {#sum_item_value:.2}

# Mutational Signature のY軸最大値 (-1 の場合、それぞれのデータの最大値を使用する)
signature_y_max = -1

# signatureのbarの色
alt_color_CtoA = #1BBDEB
alt_color_CtoG = #211D1E
alt_color_CtoT = #E62623
alt_color_TtoA = #CFCFCF
alt_color_TtoC = #ACD577
alt_color_TtoG = #EDC7C4

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

# 入力形式 (現在は json のみ)
format = json

# background を使用しているかどうか
background = True

# jsonファイルのkey名
key_id = id
key_mutation = mutation
key_signature = signature
key_mutation_count = mutation_count

ポップアップの表示内容

記載方法は ユーザ定義フォーマット を参照してください。

表示箇所ごとに 4 種類設定しますが、書き方は同一です。
それぞれ次のキーワードが使用できます。

tooltip_format_signature_title

キーワード 解説
{sig} 変異シグネチャの色別グループのラベル。’C > A’ や ‘C > G’ 等
{#sum_group_value} 変異シグネチャの色別グループの合計値

tooltip_format_signature_partial

キーワード 解説
{route} 変異シグネチャの棒グラフ 1 本分のラベル。’ApCpA’ や ‘CpCpA’ 等
{#sum_item_value} 変異シグネチャの棒グラフ 1 本分の値

tooltip_format_mutation_title (積み上げグラフ)

キーワード 解説
{id} key_id で入力したサンプル名です。
{#sum_mutaion_all} 全変異数

tooltip_format_mutation_partial (積み上げグラフ)

キーワード 解説
{sig} 変異シグネチャの名前 “Signature {番号}” で表示します。
{#sum_item_value} 積み上げグラフの合計値

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

# 変異シグネチャ - タイトル
tooltip_format_signature_title = {sig}

# 変異シグネチャ - 各項目
tooltip_format_signature_partial = {route}: {#sum_item_value:6.2}

# 寄与度グラフ - タイトル
tooltip_format_mutation_title = {id}

# 寄与度グラフ - 変異シグネチャごと
tooltip_format_mutation_partial = {sig}: {#sum_item_value:.2}
_images/conf_sig1.PNG

5. pmsignature

全設定項目

###################### pmsignature
[pmsignature]

# ポップアップの表示内容
tooltip_format_ref1 = A: {a:.2}
tooltip_format_ref2 = C: {c:.2}
tooltip_format_ref3 = G: {g:.2}
tooltip_format_ref4 = T: {t:.2}
tooltip_format_alt1 = C -> A: {ca:.2}
tooltip_format_alt2 = C -> G: {cg:.2}
tooltip_format_alt3 = C -> T: {ct:.2}
tooltip_format_alt4 = T -> A: {ta:.2}
tooltip_format_alt5 = T -> C: {tc:.2}
tooltip_format_alt6 = T -> G: {tg:.2}
tooltip_format_strand = + {plus:.2} - {minus:.2}
tooltip_format_mutation_title = {id}
tooltip_format_mutation_partial = {sig}: {#sum_item_value:.2}

# pmsignature の四角形の色
color_A = #06B838
color_C = #609CFF
color_G = #B69D02
color_T = #F6766D
color_plus = #00BEC3
color_minus = #F263E2

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

# 入力形式 (現在は json のみ)
format = json

# background を使用しているかどうか
background = True

# json ファイルの key 名
key_id = id
key_mutation = mutation
key_ref = ref
key_alt = alt
key_strand = strand
key_mutation_count = mutation_count

ポップアップの表示内容

記載方法は ユーザ定義フォーマット を参照してください。

表示箇所ごとに4種類設定しますが、書き方は同一です。
それぞれ次のキーワードが使用できます。

tooltip_format_ref* (pmsignature 下段の 5 つの四角形)

キーワード 解説
{a} A の値
{c} C の値
{g} G の値
{t} T の値

tooltip_format_alt* (pmsignature 上段の 1 つの四角形)

キーワード 解説
{ca} C → Aの値
{cg} C → Gの値
{ct} C → Tの値
{ta} T → Aの値
{tc} T → Cの値
{tg} T → Gの値

tooltip_format_strand

キーワード 解説
{plus} プラスの値
{minus} マイナスの値

tooltip_format_mutation_title (積み上げグラフ)

キーワード 解説
{id} key_id で入力したサンプル名です。
{#sum_mutaion_all} 全変異数

tooltip_format_mutation_partial (積み上げグラフ)

キーワード 解説
{sig} 変異シグネチャの名前 “Signature {番号}” で表示します。
{#sum_item_value} 積み上げグラフの合計値

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

# pmsignature - 下段の 5 つの四角形
tooltip_format_ref1 = A: {a:.2}
tooltip_format_ref2 = C: {c:.2}
tooltip_format_ref3 = G: {g:.2}
tooltip_format_ref4 = T: {t:.2}

# pmsignature - 上段の四角形
tooltip_format_alt1 = C -> A: {ca:.2}
tooltip_format_alt2 = C -> G: {cg:.2}
tooltip_format_alt3 = C -> T: {ct:.2}
tooltip_format_alt4 = T -> A: {ta:.2}
tooltip_format_alt5 = T -> C: {tc:.2}
tooltip_format_alt6 = T -> G: {tg:.2}

# pmsignature - strand
tooltip_format_strand = + {plus:.2} - {minus:.2}

# 寄与度グラフ - タイトル
tooltip_format_mutation_title = {id}

# 寄与度グラフ - 変異シグネチャごと
tooltip_format_mutation_partial = {sig}: {#sum_item_value:.2}
_images/conf_pmsig1.PNG

Mutaitonal Signature 実行手順

ここでは pmsignature を使用した場合のデータの準備方法を解説します。

注釈

実行前に R の環境構築と pmsignature および関連パッケージのインストールが必要です。
インストールおよび、実行コマンドの詳しい解説は pmsignature を参照ください。

別のツールを用いてシグネチャ解析を行った場合は、 仕様 に準拠する json ファイルを別途準備ください。

1. 結果ファイルの整形

pmsignature に入力する変異のデータファイルは以下のフォーマットである必要があります。

  • ヘッダなし、コメント行なし
  • 左から、サンプル名、染色体 (先頭に chr が必要です) 、位置、リファレンスの塩基、変異の塩基 の順でデータが記載されていること
  • タブ区切り

余分なデータ列は取り除いてください。

PD3851a chr1    809687  G       C
PD3851a chr1    819245  G       T
PD3851a chr1    1911011 C       G
PD3945a chr5    143183408       G       T
PD3945a chr5    143240819       C       A

テキストの整形には表計算ソフト等を用いるのが最も簡単ですが、データ列の取り出しだけであれば以下のようなコマンドの組み合わせで実行することもできます。

input_file={入力ファイル}

# 1,2,3,5,6番目の列を取り出す例
cut -s -f 1,2,3,5,6 $input_file > ./output.txt

# 順番を入れ替える例 (1番目の列を最後に移動する)
cut -s -f 1 $input_file > ./tmp1.txt
cut -s -f 2,3,4,5 $input_file > ./tmp2.txt
paste ./tmp2.txt ./tmp1.txt > ./output.txt

# chrを先頭につける例 (2番目の列がchr列とする)
cut -s -f 2 $input_file | sed "s/^/chr/" | sed -e "s/^chr[Cc]hr/chr/g" > tmp1.txt

# 先頭1行がヘッダなので取り除く例
tail -n +2 $input_file > tmp1.txt

2. pmsignature の実行

pmsignature を type="full" で実行してパラメータを出力します。

今回の例では、pmsignature のサンプルデータを使用しているため .txt.gz 形式ですが、1. の結果ファイルを入力する場合は圧縮する必要はありません。

R console
library(pmsignature)

# use sample data
inputFile <- system.file("extdata/Nik_Zainal_2012.mutationPositionFormat.txt.gz", package="pmsignature")
G <- readMPFile(inputFile, numBases = 3, type = "full", trDir = FALSE)

Param <- getPMSignature(G, K = 3)
Boot <- bootPMSignature(G, Param0 = Param, bootNum = 100)

# save .Rdata
resultForSave <- list(Param, Boot)
save(resultForSave, file="pmsignature_full3.Rdata")

3. paplot で使用できるように Rdata を変換する

  1. で作成した “pmsignature_full3.Rdata” ファイルを paplot で読み込めるように .json 形式に変換します。

変換スクリプトを用意していますので、以下より最新版をダウンロードし、適切な場所に解凍してください。 インストールの必要はありません。

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

入力ファイル、出力したいファイル名の順に引数を渡します。

R --vanilla --slave --args ./pmsignature_full3.Rdata ./pmsignature_full3.json \
< {path to genomon_Rscripts}/pmsignature/convert_toJson_full.R

重要

R パッケージ “rjson” が必要です。ロードエラーが発生した場合はインストールしてください。

4. paplot の実行

  1. で作成した “pmsignature_full3.json” ファイルを使用して、paplot を実行します。上述の方法で実行した場合、設定ファイルの変更は必要ありません。

paplot 実行例

paplot signature pmsignature_full3.Rdata ./temp signature_test

pmsignature 実行手順

ここでは pmsignature を使用した場合のデータの準備方法を解説します。

注釈

実行前に R の環境構築と pmsignature および関連パッケージのインストールが必要です。
インストールおよび、実行コマンドの詳しい解説は pmsignature を参照ください。

別のツールを用いて pmsignature 解析を行った場合は、 仕様 に準拠する json ファイルを別途準備ください。

1. 結果ファイルの整形

signature 参照

2. pmsignature の実行

pmsignature を type="independent" (default) で実行したのち、パラメータを .Rdata ファイルに出力します。

今回の例では、pmsignature のサンプルデータを使用しているため .txt.gz 形式ですが、1. の結果ファイルを入力する場合は圧縮する必要はありません。

library(pmsignature)

# use sample data
inputFile <- system.file("extdata/Nik_Zainal_2012.mutationPositionFormat.txt.gz", package="pmsignature")
G <- readMPFile(inputFile, numBases = 5, trDir = TRUE)

# use background
BG_prob <- readBGFile(G)

Param <- getPMSignature(G, K = 3, BG = BG_prob)
Boot <- bootPMSignature(G, Param0 = Param, bootNum = 100, BG = BG_prob)

# save .Rdata
resultForSave <- list(Param, Boot)
save(resultForSave, file="pmsignature_ind3.Rdata")

3. paplot で使用できるように Rdata を変換する

  1. で作成した”pmsignature_ind3.Rdata” ファイルを paplot で読み込めるように .json 形式に変換します。

変換スクリプトを用意していますので、以下より最新版をダウンロードし、適切な場所に解凍してください。 インストールの必要はありません。

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

入力ファイル、出力したいファイル名の順に引数を渡します。

R --vanilla --slave --args ./pmsignature_ind3.Rdata ./pmsignature_ind3.json \
< {path to genomon_Rscripts}/pmsignature/convert_toJson_ind.R

4. paplot の実行

  1. で作成した “pmsignature_ind3.json” ファイルを使用して、paplot を実行します。上述の方法で実行した場合、設定ファイルの変更は必要ありません。

paplot 実行例

paplot signature pmsignature_ind3.Rdata ./temp signature_test

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

1. 変更方法

色やテキストなど、グラフの見た目はある程度変更することができます。
グラフの見た目は 2 つのファイルで設定します。

1 つ目は設定ファイルです。
グラフのバーの色や凡例、ポップアップの文字列のように入力データに依存する要素は設定ファイルで設定します。
設定ファイルの記入例は以下を参照ください。

[入門編]
[上級者向け]
2 つ目は style ファイルです。
入力データに依存しない要素を設定します。
ここでは、style ファイルについて記載します。

1-1. style ファイルを編集する

デフォルトの style ファイルはここにあります。
{paplot をインストールしたディレクトリ}/example/default.js
このファイルをコピーして 新しい style ファイルを作成します。
ここでは、例としてこのように作成します。 {paplotをインストールしたディレクトリ}/example/mystyle.js
ファイル名は任意ですが、拡張子は .js にしてください。

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

注釈

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

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

// 色名で指定する場合
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. paplot を実行する

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

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

上で作成したファイルは次のディレクトリにコピーされています。
すでに paplot で出力した HTML ファイルを変更する場合、スタイルファイル (mystyle.js) を編集し、再読み込み (ウェブブラウザで F5) すれば反映されます。
./tmp
  ├ style_test
  │   └ graph_qc.html
  │
  ├ js
  ├ layout
  ├ lib
  └ style
      ├ default.js     <--- デフォルト
      └ mystyle.js     <--- 今回作成したファイル

2. 設定項目

// ----------------------------------------
// 共通
// ----------------------------------------
(function(){
style_general = {
    font_family: "'Helvetica Neue', Helvetica, Arial, sans-serif",
}

// ----------------------------------------
// QC レポート
// ----------------------------------------
style_qc = {

    // 領域選択用グラフ
    // Y 方向ボーダーライン
    brush_border_y_color: "#DDDDCC",
    brush_border_y_opacity: 0.5,

    // 通常グラフ
    // Y 方向ボーダーライン
    plot_border_y_color: "#DDDDCC",
    plot_border_y_opacity: 0.2,

    // Y 軸ラベル
    title_y_font_size: "12px",

    // 凡例
    legend_title_font_size: "16px",
    legend_text_font_size: "12px",
};

// ----------------------------------------
// Chromosomal Aberration レポート
// ----------------------------------------

// 横長の棒グラフ
style_sv_bar = {

    // X 軸ラベル
    title_x: "Chromosome",
    title_x_font_size: "14px",
    axis_x_font_size: "9px",

    // Y 軸ラベル
    title_y: "Mutations with CA breakp.",
    title_y_font_size: "12px",

    // 凡例
    legend_title: "Genome-wide CAs identify",
    legend_title_font_size: "16px",
    legend_text_font_size: "12px",

    // X 方向ボーダーライン
    border_x_main_color: "#E0E0E0",
    border_x_main_width: "1px",
    border_x_sub_color: "#A6A6A6",
    border_x_sub_width: "1px",

    // Y 方向ボーダーライン
    border_y_color: "#DDDDCC",
    border_y_opacity: 0.5,
};

// 円形のプロット
style_sv_thumb = {

    // 円の弧 (fill: 塗りつぶし色, stroke: 枠線色)
    arc_fill_opacity: 1.0,
    arc_stroke_opacity: 1.0,

    // 切断点をつなぐ曲線
    link_width: "1px",
    link_opacity: 1.0,
};

// 円形のプロット (クリックで表示される方)
style_sv_detail = {

    // 表示ウィンドウ
    win_header_text_color: "#000000",
    win_header_background_color: "#CFCFCF",
    win_border_color: "#D3D3D3",
    win_border_width: "1px",
    win_background_color: "white",

    // 円の弧  (fill: 塗りつぶし色, stroke: 枠線色)
    arc_fill_opacity: 1.0,
    arc_stroke_opacity: 1.0,

    // 円の弧のラベル
    arc_label_fontsize: "10px",
    arc_label_color: "#333333",

    // 切断点をつなぐ曲線
    link_width: "2px",
    link_opacity: 1.0,

    // 切断点をつなぐ曲線 (マウスを乗せた時)
    link_select_color: "#d62728",
    link_select_width: "3px",
    link_select_opacity: 1.0,
};

// ----------------------------------------
// Mutaion Matrix レポート
// ----------------------------------------
style_mut = {

    // -------------------------
    // 横長のグラフ (サンプル)
    // -------------------------
    // タイトル
    title_sample: "Sample",
    title_sample_font_size: "14px",

    // Y 軸ラベル
    title_sample_y: "Number of mutation",
    title_sample_y_font_size: "12px",

    // X 方向ボーダーライン
    virtical_border_x_color: "#CCCCEE",
    virtical_border_x_width: "1px",

    // Y 方向ボーダーライン
    virtical_border_y_color: "#DDDDCC",
    virtical_border_y_opacity: 0.5,

    // -------------------------
    // 縦長のグラフ (遺伝子)
    // -------------------------
    // タイトル
    title_gene: "Genes",
    title_gene_font_size: "14px",

    // Y 軸ラベル
    title_gene_y1: "% Samples",
    title_gene_y2: "with mutations",
    title_gene_y1_font_size: "12px",
    title_gene_y2_font_size: "12px",

    // X 方向ボーダーライン
    horizon_border_x_color: "#CCCCEE",
    horizon_border_x_width: "1px",

    // Y 方向ボーダーライン
    horizon_border_y_color: "#DDDDCC",
    horizon_border_y_opacity: 0.5,

    // 凡例
    legend_title: "Mutation type",
    legend_title_font_size: "16px",
    legend_text_font_size: "12px",

    // 遺伝子名
    gene_text_font_size: "9px",

    // -------------------------
    // サブプロット
    // -------------------------
    // X 方向ボーダーライン
    sub_border_color: "#FFFFFF",
    sub_border_width: "1px",

};

// ----------------------------------------
// Mutational Signature レポート
// ----------------------------------------
style_signature = {

    // -------------------------
    // 寄与度グラフ (Count)
    // -------------------------
    // タイトル
    title_integral: "Signature contribution",
    title_integral_font_size: "16px",

    // Y 軸ラベル
    title_integral_y: "Count",
    title_integral_y_font_size: "12px",

    // 凡例
    legend_integral_title_font_size: "16px",
    legend_integral_text_font_size: "12px",

    // -------------------------
    // 寄与度グラフ (Rate)
    // -------------------------
    // タイトル
    title_rate: "Signature contribution",
    title_rate_font_size: "16px",

    // Y 軸ラベル
    title_rate_y: "Rate",
    title_rate_y_font_size: "12px",

    // 凡例
    legend_rate_title_font_size: "16px",
    legend_rate_text_font_size: "12px",

    // -------------------------
    // 寄与度グラフ (共通)
    // -------------------------
    // Y 方向ボーダーライン
    plot_border_y_color: "#DDDDCC",
    plot_border_y_opacity: 0.5,

    // -------------------------
    // 変異シグネチャ
    // -------------------------
    // 変異シグネチャ名
    signature_title_font_size: "12px",

    // Y 軸ラベル
    signature_title_y: "Probaility",
    signature_title_y_font_size: "12px",

    // X 軸ラベル
    signature_title_x_font_size: "12px",

    // Y 方向ボーダー
    border_y_color: "#DDDDCC",
    border_y_opacity: 0.5,
};

// ----------------------------------------
// pmsignature レポート
// ----------------------------------------
style_pmsignature = {

    // -------------------------
    // 寄与度グラフ (Count)
    // -------------------------
    // タイトル
    title_integral: "Signature contribution",
    title_integral_font_size: "16px",

    // Y 軸ラベル
    title_integral_y: "Count",
    title_integral_y_font_size: "12px",

    // 凡例
    legend_integral_title_font_size: "16px",
    legend_integral_text_font_size: "12px",

    // -------------------------
    // 寄与度グラフ (Rate)
    // -------------------------
    // タイトル
    title_rate: "Signature contribution",
    title_rate_font_size: "16px",

    // Y 軸ラベル
    title_rate_y: "Rate",
    title_rate_y_font_size: "12px",

    // 凡例
    legend_rate_title_font_size: "16px",
    legend_rate_text_font_size: "12px",

    // -------------------------
    // 寄与度グラフ (共通)
    // -------------------------
    // Y 方向ボーダーライン
    plot_border_y_color: "#DDDDCC",
    plot_border_y_opacity: 0.5,

    // -------------------------
    // 変異シグネチャ
    // -------------------------
    // 変異シグネチャ名
    signature_title_font_size: "12px",

    // 各ボックスのラベル
    signature_alt_font_size: "10px",
    signature_ref_font_size: "10px",
    signature_strand_font_size: "10px",

};
})();
透過度 (opacity) について、設定値と見た目は次の通りです。
0~1 の間で設定することができ、0 で透明、1 で不透明となります。
_images/link-opacity.PNG

インストールに関すること

paplot conf でエラー

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

このようなエラーの場合、PATH の設定が正しくありません。
$ paplot conf
-bash: /usr/bin/paplot: No such file or directory
このようなエラーの場合、LD_LIBRARY_PATH の設定が正しくありません。
$ paplot conf
Traceback (most recent call last):
  File "/usr/bin/paplot", line 4, in <module>
    __import__('pkg_resources').run_script('paplot===0.2.7devel', 'paplot')
(省略)
pkg_resources.DistributionNotFound: The 'paplot===0.2.7devel' distribution was not found and is required by the application
paplot ファイルがない場合はインストールが成功していない可能性があります。
成功した場合は最後の 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

各レポートに関すること

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

paplot v0.4.0 より画像保存機能が追加されました。
それぞれのプロットにある [Export] ボタンをクリックしてください。
メニューが表示されますので、SVG / PNG どちらか希望するフォーマットを選択してください。

_images/qa_export.PNG
出力フォーマット

  • SVG ... タグで記載されたテキストファイルです。SVG 対応の画像編集ソフトウェアのほか、各種ウェブブラウザでも表示できます。
  • PNG ... 画像ファイルです。背景透過処理を施しています。
なお、1 プロットのみ保存したい場合は、それぞれのプロットの上で右クリックで保存することも可能です。

_images/qa_export2.PNG

注釈

この機能は以下のウェブブラウザで確認しています。うまく動かない場合は、最新のバージョンにアップデートするか、別のウェブブラウザをお試しください。

  • Windows
    • Firefox (47.0)
    • Chrome (51.0)
    • Internet Explorer11 (11.0)
  • Mac
    • Firefox (45.2)
    • Chrome (52.0)
    • Safari (9.1.2)

Chromeの場合

フォーマット選択後、自動的にダウンロードされます。

Firefoxの場合

フォーマット選択後、ダウンロードに関するメッセージが表示されますので、任意の場所に保存してください。

_images/qa_export_firefox.PNG

IEの場合

  • SVG ... フォーマット選択後、ダウンロード画面が表示されますので、任意の場所に保存してください。
  • PNG ... 画像が新しいタブで表示されますので、右クリックして「名前を付けて画像を保存…」を選択してください。

Safariの場合

  • SVG ... 画像が新しいタブで表示されますので、右クリックして「ページを別名で保存…」を選択してください。
各項目は次のように指定してください。
書き出し名「{任意の名前}.svg」
フォーマット「ページのソース」

  • PNG ... 画像が新しいタブで表示されますので、右クリックして「イメージを別名で保存…」を選択してください。

注意

新しいタブが開かない場合、以下の設定を確認ください。 Safari→環境設定→セキュリティ→Webコンテンツ→「ポップアップウィンドウを開かない」チェックを外す

表示に時間がかかる

データの数が多すぎると表示に時間がかかる、もしくは表示されないことがあります。

データの数 (変異の数)、サンプル数および表示マシンの性能に依存しますので一概には規定できませんが、表示されない場合はサンプル数や検出ソフトのフィルタ条件の見直し等が必要です。

リリースノート

注意

バージョン間で設定ファイルの互換性はありません。
バージョンアップの際は、お手数ですが最新の設定ファイルを変更してご使用ください

v0.5.4

  • サンプルデータ追加
  • 設定ファイルの項目見直し

v0.5.3

フォントサイズに関するオプションを変更可能にする

v0.5.2

  • サブコマンド新規追加 signature, pmsignature
  • サブコマンド名称変更 sv -> ca

v0.4.0

画像保存機能追加

v0.3.1

Mutation Matrix レポートについて、不具合修正

v0.3.0

サブコマンド新規追加 mutation

v0.2.8

結果ファイルマージ機能について仕様変更

v0.2.7

新規作成 qc, sv

ライセンス

paplot is licensed under the MIT License

Copyright (c) 2017 Ai Okada and Yuichi Shiraishi
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

コンタクト

ご質問やフィードバックなど，お気軽にご連絡ください．
genomon.devel@gmail.com

対面形式，skype でのアポイントはこちらで受け付けています．
Genomon Office Hour: https://genomon-office.youcanbook.me/

Javascript Libraries

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