pyGenomeVizの使い方｜1.7.0のインストールからGenBank・GFF描画と比較図の保存まで

pyGenomeVizは、ゲノム上の遺伝子配置と、複数ゲノム間の相同領域を結ぶ線を描くためのPythonパッケージです。matplotlibの上に実装されており、GenBankやGFFを読み込んで数行で比較ゲノム図を作れます。

この記事では、2026年6月13日に公開された1.7.0を対象に、インストールから描画・保存までの手順をまとめます。基本描画・GenBank・GFF・BED・リンク描画のPythonコード5例は pygenomeviz 1.7.0（Python 3.14.6、matplotlib 3.11.2、biopython 1.88）で実行し、エラーなく画像が出力されることを確認済みです。1.6系以前のコードが1.7.0で落ちる原因と直し方も扱います。

まとめ：pyGenomeViz 1.7.0で比較ゲノム図を描く要点

• インストールは pip install pygenomeviz か conda install -c conda-forge pygenomeviz。1.7.0はPython 3.10以上が必須です。
• 描画の流れは「GenomeViz を作る → add_feature_track でトラックを足す → フィーチャーを置く → savefig」の4段階です。
• 読み込めるファイルは GenBank・GFF・FASTA の3形式です。BEDなどは自分で読んで add_feature に渡します。
• ゲノム間の対応は add_link で結びます。BLASTやMUMmerの自動実行は、アライナー本体を別途入れないと動きません。
• 保存形式は PNG・JPG・SVG・PDF・HTML。拡張子で決まり、HTMLは savefig_html でズームやツールチップ付きのビューアになります。
• 1.7.0ではトラックのメソッドから target_seg 引数が消えました。旧コードは track.get_segment(名前) 経由に書き換えます。

pyGenomeVizでできることと守備範囲

作者はmoshi4（Yuki Shimoyama）氏で、ライセンスはMITです。READMEでは「比較ゲノミクスのためのゲノム可視化パッケージ」と位置づけられ、GenBankとGFFの可視化、JPG・PNG・SVG・PDF・HTMLでの保存に対応すると明記されています。使い方は3通りあります。

• Python API：Jupyter Notebookや解析スクリプトの中で図を作る
• CLI：pgv-blast などのコマンドで、アライメントから図の出力までを一括実行する
• GUI：pgv-gui でStreamlit製のWebアプリを起動する

対象は線形ゲノムの図です。プラスミドや細菌ゲノムを環状に描きたい場合、作者本人がREADMEで同じ作者のpyCirclizeを案内しています。また pygenomeviz.parser が公開しているクラスは Fasta・Genbank・Gff の3つだけです。リードのアライメント（BAM）や変異（VCF）を重ねる用途向けの読み込み機能は持っていません。そうした図が主目的なら、pyGenomeVizを選ぶ理由は薄くなります。

pyGenomeVizのインストール手順（pip・conda・Docker）

Python 3.10以上とvenvでのpipインストール

PyPIのpygenomeviz 1.7.0ページのメタデータでは、1.7.0の requires-python は >=3.10、1つ前の1.6.1は >=3.9 です。Python 3.9の環境で pip install pygenomeviz を実行すると、pipは条件を満たす1.6.1を選ぶため、エラーにならないまま古い版が入ります。バージョンは導入後に必ず確認してください。

解析ごとに依存を分けるため、仮想環境（venv）に入れるのが確実です。

# 仮想環境を作って有効化（macOS / Linux）
python3 -m venv .venv
source .venv/bin/activate

# Windows（PowerShell）の場合
# .venv\Scripts\activate

pip install pygenomeviz==1.7.0
python -c "import pygenomeviz; print(pygenomeviz.__version__)"
# 1.7.0

依存パッケージとして biopython 1.80以上、matplotlib 3.6.3以上、numpy 1.21以上が一緒に入ります。venvとコンテナの隔離レベルの違いは仮想環境とは？venv・コンテナ・仮想マシンの違いと隔離レベルの選び方を実装者向けに解説で整理しています。

conda-forgeとDockerでの導入

conda-forgeのレシピも1.7.0に更新済みです。BLASTなどのバイオインフォマティクス系ツールをまとめて入れるなら、condaのほうが手間が少なくなります。

conda install -c conda-forge pygenomeviz

# Docker（公式イメージ）
docker run -it --rm -p 8501:8501 ghcr.io/moshi4/pygenomeviz:v1.7.0 pgv-gui

pipとcondaを同じ環境で混ぜると依存が壊れやすくなります。どちらを軸にするかはpipとcondaの違いと使い分け｜Anaconda・Miniconda・商用ライセンスまで解説を参考にしてください。

GUIと比較ワークフローに必要な追加インストール

本体だけでは、GUIとアライメントの自動実行は使えません。

aptの例は公式ドキュメントがUbuntu 22.04以降向けに載せているものです。condaの場合は conda install -c conda-forge -c bioconda pygenomeviz streamlit blast mummer mmseqs2 で揃います。

基本の描画手順：GenomeViz→トラック→フィーチャー→保存

最小構成のコードです。1000bpのトラックに3つの遺伝子を矢印で置き、PNGで保存します。

from pygenomeviz import GenomeViz

gv = GenomeViz()
gv.set_scale_xticks(ymargin=0.5)

track = gv.add_feature_track("track", 1000)
track.add_sublabel()

# add_feature(開始, 終了, 向き)  向きは 1 が正鎖、-1 が逆鎖
track.add_feature(50, 200, 1)
track.add_feature(250, 460, -1, fc="blue")
track.add_feature(500, 710, 1, fc="lime", lw=1.0, label="geneC")

gv.savefig("features.png")

fc（塗り色）、ec（枠線色）、lw（線幅）はmatplotlibのPatchの引数がそのまま通ります。形は plotstyle で arrow（既定）・bigarrow・box・bigbox・rbox・bigrbox の6種類から選べます。色指定の書式などmatplotlib自体の基本はMatplotlibとは？Pythonでグラフを描く使い方を入門から実践まで解説にまとめています。

Jupyter Notebookで画面に出したいときは fig = gv.plotfig() を使います。戻り値はmatplotlibの Figure なので、セルの最後に置けば表示されます。

GenBank・GFFファイルの読み込みと描画

GenBankファイルのCDS抽出と描画

Genbank クラスに渡したファイルから、配列長とフィーチャーを取り出して描きます。次の例は、公式のサンプルデータ（エルシニアファージ4株）の1株目を描画します。

from pygenomeviz import GenomeViz
from pygenomeviz.parser import Genbank
from pygenomeviz.utils import load_example_genbank_dataset

gbk_files = load_example_genbank_dataset("yersinia_phage")
gbk = Genbank(gbk_files[0])   # 自分のデータなら Genbank("my_genome.gbk")

gv = GenomeViz(fig_track_height=0.7)
gv.set_scale_bar(ymargin=0.5)

track = gv.add_feature_track(gbk.name, gbk.get_seqid2size())
for seg in track.segments:
    features = gbk.get_seqid2features("CDS")[seg.name]
    seg.add_features(features, label_type="product", lw=0.5)
    seg.add_sublabel()

gv.savefig("genbank_cds.png")

load_example_genbank_dataset は初回だけGitHubからデータを取得し、~/.cache/pygenomeviz/ に保存します。必要なデータがキャッシュにないオフライン環境では取得に失敗するため、手元のファイルを直接渡してください。実行すると gbk.get_seqid2size() は {'NC_070914.1': 30280} を返しました。label_type="product" はGenBankのproduct修飾子（この株の先頭CDSなら integrase）をラベルに使う指定です。

GFFファイルの座標範囲指定と部分描画

細菌ゲノム全体を1本のトラックに描くと、遺伝子が潰れて読めません。segments に座標範囲を渡すと、その領域だけを並べて描けます。

from pygenomeviz import GenomeViz
from pygenomeviz.parser import Gff
from pygenomeviz.utils import load_example_gff_file

gff = Gff(load_example_gff_file("escherichia_coli.gff.gz"))

gv = GenomeViz()
gv.set_scale_bar(ymargin=0.5)

track = gv.add_feature_track(gff.name, segments=((215000, 230000), (300000, 320000)))
track.set_segment_sep()

for segment in track.segments:
    segment.add_sublabel()
    cds = gff.extract_features(feature_type="CDS", target_range=segment.range)
    segment.add_features(cds, label_type="gene", fc="skyblue", lw=1.0, annotation=True)

# 1.7.0 で追加された強調表示
track.segments[0].add_highlight((220000, 224000), color="orange")

fig = gv.plotfig()
fig.savefig("gff_region.png", bbox_inches="tight")

annotation=True は1.7.0で入った引数で、ラベルが重ならないよう引き出し線付きで配置します。注釈を使った図は gv.savefig() ではなく、gv.plotfig() で得た Figure の savefig() で保存するよう、GenomeViz APIドキュメントの警告に書かれています。凡例やサブトラックを足した図も同じ扱いです。

BED6の読み込みとフィーチャーへの変換

BEDを読むクラスはありません。ただ add_feature は開始・終了・向きを受け取るだけなので、以下の条件に限定したBED6なら、標準ライブラリの csv で読み込めます。この例では、見出し・コメント・空行を含まず、全行の染色体名がchr1、座標が0〜3000の範囲内、strandが「+」または「-」のタブ区切りファイルを使います。

import csv
from pygenomeviz import GenomeViz

gv = GenomeViz()
gv.set_scale_xticks()
track = gv.add_feature_track("chr1", 3000)

with open("genes.bed") as f:
    for chrom, start, end, name, score, strand in csv.reader(f, delimiter="\t"):
        track.add_feature(int(start), int(end), 1 if strand == "+" else -1, label=name)

gv.savefig("bed.png")

座標の基準はそろっています。サンプルのGenBankで complement(70..1107) と書かれたCDSを読み込むと、位置は [69:1107](-) になりました。Biopython経由の座標は開始が0始まりで、BEDの開始位置と同じ基準です。BEDの値は変換せずに渡して構いません。このコードはBED6専用です。BED3ではnameやstrandの補完が必要で、BED12のブロック構造を描くには各ブロックを読み取り、個別のフィーチャーとして配置する処理が必要です。

複数ゲノムの比較図を描くadd_link

比較図の本体は、トラック同士を結ぶリンクです。add_link には「(トラック名, 開始, 終了)」のタプルを2つ渡します。

from pygenomeviz import GenomeViz

gv = GenomeViz(track_align_type="center")
gv.set_scale_bar()

a = gv.add_feature_track("genome A", 1000)
b = gv.add_feature_track("genome B", 1200)
a.add_feature(150, 300, 1)
b.add_feature(50, 200, 1)
a.add_feature(500, 700, -1)
b.add_feature(700, 900, 1)

gv.add_link(("genome A", 150, 300), ("genome B", 50, 200))
# 片側の開始と終了を逆にすると逆位（inverted）として色分けされる
gv.add_link(("genome A", 700, 500), ("genome B", 700, 900), inverted_color="red", curve=True)

gv.savefig("links.png")

リンクを結べるのは、追加した順で隣り合うトラック同士だけです。1本目と3本目を直接結ぼうとすると、LinkTrackNotFoundError（Target feature tracks must be adjacent feature tracks!!）で止まります。比較したい順にトラックを並べてください。track_align_type="center" は長さの違うゲノムを中央揃えにする指定です。実データでは、BLASTなどの結果を pygenomeviz.align の Blast(...).run() で計算し、AlignCoord.filter で絞り込み、ループで add_link に流し込みます。

コードを書かずに使うCLIとpgv-gui

GenBankファイルを並べて比較図を出すだけなら、CLIワークフローで足ります。

# サンプルデータをカレントディレクトリに取得
pgv-download yersinia_phage

# タンパク質レベルで比較し、長さ100以上・同一性30%以上のヒットだけを結ぶ
pgv-blast NC_070914.gbk NC_070915.gbk NC_070916.gbk NC_070918.gbk \
          -o pgv-blast_example --seqtype protein --show_scale_bar --curve \
          --feature_linewidth 0.3 --length_thr 100 --identity_thr 30

出力形式は --formats で png・jpg・svg・pdf・html から選べます。ワークフローを定期実行する場合は、Nextflowとは何か？データ解析パイプラインを自動化するワークフロー管理ツールの特徴とメリットを解説で紹介しているパイプライン管理ツールに組み込むと、再実行の管理が楽になります。

pgv-gui を実行すると、Streamlit製のWebアプリが http://localhost:8501 で起動します。ポートは -p で変えられます。GenBankをアップロードして図を作れるので、Pythonを書かない共同研究者に渡すときに使えます。インストール前に試したいなら、公式のデモページ（pygenomeviz.streamlit.app）で操作感を確認できます。Streamlit自体の仕組みはStreamlitとは？できること・使い方・料金を実例コードで解説【Python】を参照してください。

図の保存形式とdpi・HTMLビューア

savefig はファイル名の拡張子で形式を判別します。前述のGenBank例（30,280bp・1トラック）を各形式で保存したときのファイルサイズは次のとおりでした。

解像度は dpi 引数で決まり、既定は100です。基本の描画例を既定のまま保存すると1719×340ピクセル、gv.savefig("features.png", dpi=300) では5157×1021ピクセルになりました。論文投稿では、まず投稿先が指定する形式と解像度に従ってください。PDFやSVGが受け付けられる場合はベクター形式も選択できますが、容量は図の複雑さや保存設定によって変わります。

HTMLは、JavaScriptのビューアを1ファイルに埋め込むためサイズが大きくなります。代わりに、ブラウザ上でパン・ズーム、フィーチャーのツールチップ表示、色や文字の変更ができます。注釈や凡例を足した図をHTMLにする場合は、fig = gv.plotfig(fast_render=False) で作った図を gv.savefig_html("x.html", figure=fig) に渡します。

1.7.0の変更点と旧コードの移行

GitHubのv1.7.0リリースノートに載っている主な変更です。

• 追加：add_annotation()、add_promoter()、add_lollipop()、add_highlight()、add_features() の annotation 引数
• 変更：Trackクラスの描画メソッドから target_seg 引数を削除
• 変更：Python 3.9のサポートを終了
• 修正：savefigで pad_inches=0.5 を明示的に指定

既存のスクリプトで影響が出るのは target_seg の削除です。1.7.0では、トラックの add_feature や add_sublabel は先頭セグメントのメソッドをそのまま呼びます。そのため旧コードの target_seg="..." は、呼び出しの時点ではエラーにならず、matplotlibの描画オブジェクトまで渡ってから落ちます。実行時のエラーは次のとおりでした。

# track.add_feature(1, 100, 1, target_seg="t") のあと savefig
AttributeError: Arrow.set() got an unexpected keyword argument 'target_seg'

# track.add_sublabel(target_seg="t") のあと savefig
AttributeError: 'Text' object has no property 'target_seg'

エラーが出るのは savefig の行なので、原因の行を探しにくいのが厄介な点です。対象のセグメントを取り出してから呼ぶ形に書き換えます。

# 1.6系まで
track.add_sublabel(target_seg="contig_2")

# 1.7.0
track.get_segment("contig_2").add_sublabel()

よくあるエラーと対処

BLASTが見つからないときの RuntimeError: Failed to run 'BLAST' aligner!! は、CLIの pgv-blast でもAPIの Blast(...).run() でも同じメッセージです。macOS・Linuxでは which makeblastdb blastn tblastx で、必要な3コマンドがPATH上にあるかを確かめてください。見つかる場合は、直前のログにある実行コマンドとエラー内容を確認します。

よくある質問

pyGenomeVizは商用や論文で無料で使えますか？

MITライセンスなので、著作権表示とライセンス文を残せば無償で利用できます。論文で使う場合、リポジトリの CITATION.cff に「pyGenomeViz: A genome visualization python package for comparative genomics」（Yuki Shimoyama）という引用情報が用意されています。

pyGenomeVizで環状ゲノムは描けますか？

描けません。pyGenomeVizは線形ゲノム向けで、環状の図には同じ作者のpyCirclizeがREADMEで案内されています。

BEDやVCFのファイルは読み込めますか？

専用の読み込みクラスはありません。1.7.0で使えるのは Fasta・Genbank・Gff の3つです。BEDは標準ライブラリで読み、開始位置をそのまま add_feature に渡せます。

Jupyter Notebookで図を表示するにはどうすればよいですか？

fig = gv.plotfig() でmatplotlibの Figure を作り、セルの最後に fig を置きます。ファイルに保存するだけなら gv.savefig() で足ります。

uvでインストールしても使えますか？

PyPIに公開されている通常のパッケージなので、uv pip install pygenomeviz で入ります。1.7.0からは開発側のパッケージ管理もryeからuvに切り替わっています。uvの基本操作はuvとは？Pythonの環境構築・パッケージ管理・バージョン管理の使い方を徹底解説で解説しています。

関連記事

• Matplotlibとは？Pythonでグラフを描く使い方を入門から実践まで解説
• pipとcondaの違いと使い分け｜Anaconda・Miniconda・商用ライセンスまで解説
• 仮想環境とは？venv・コンテナ・仮想マシンの違いと隔離レベルの選び方を実装者向けに解説
• uvとは？Pythonの環境構築・パッケージ管理・バージョン管理の使い方を徹底解説
• Streamlitとは？できること・使い方・料金を実例コードで解説【Python】