plannotate-plasmid-annotation

pLannotate プラスミドアノテーション

概要

pLannotate は、Addgene、NCBI、fpbase から収集した 5,000 を超える特徴の厳選ライブラリに対して BLAST 検索を実行し、プラスミド配列にアノテーションを付与します。プロモーター、ターミネーター、抗生物質耐性遺伝子、複製起点、タグ、蛍光タンパク質を特定し、プラスミドの環状トポロジーを正しく処理することで、単純な線形アラインメントで生じる特徴の分断によるアーティファクトを回避します。結果は、SnapGene、Benchling、BioPython での後続利用向けのアノテーション付き GenBank ファイル、共有やレビューに使えるインタラクティブな HTML プラスミドマップ、プログラムによるフィルタリング用の CSV テーブルとして出力されます。Python API とコマンドラインインターフェースの両方が用意されており、探索的な利用のための Streamlit ウェブアプリも同梱されています。

使用する場面

• 共同研究者から受け取った、または Addgene からダウンロードした、マップのないプラスミド配列にアノテーションを付与する場合
• アセンブリや変異導入の後に、期待される要素（プロモーター、挿入配列、耐性マーカー、複製起点）がすべて存在することを確認する場合
• 完全な特徴テーブルが必要な GenBank 登録や Addgene への寄託を準備する場合
• コンビナトリアルクローニングで作製した合成コンストラクトのライブラリに一括でアノテーションを付与する場合
• SnapGene や Benchling のライセンスなしで、共有可能なインタラクティブプラスミドマップ（HTML）を作成する場合
• クローニング前に、新規に合成した遺伝子ブロックに意図しない調節エレメントや隠れた ORF がないか確認する場合
• プライマー設計やクローニングシミュレーションのワークフローを備えた多機能な GUI プラスミドエディターが必要な場合は、代わりに SnapGene または Benchling を使用してください。pLannotate は、自動化とスクリプトによるアノテーションに最適です
• 完全な細菌ゲノムや大規模な線状染色体配列にアノテーションを付与する場合は、代わりに Prokka を使用してください。pLannotate は、最大約 50 kb のプラスミドサイズの配列に最適化されています

前提条件

• Python パッケージ：plannotate、biopython（任意。GenBank の解析に使用）
• システム依存関係：BLAST+ が PATH 上で利用可能である必要があります（conda 経由で自動的にインストールされます。pip の場合は手動インストールが必要です）
• 入力：FASTA 形式のプラスミド配列、またはプレーンな Python 文字列
• データ要件：配列は通常 1～20 kb です。非常に大きなプラスミド（>50 kb）は処理に時間がかかる場合があります

# Install via pip (requires BLAST+ on PATH)
pip install plannotate

# Install via conda (recommended — handles BLAST+ automatically)
conda install -c conda-forge -c bioconda plannotate

# Verify installation
plannotate --help
python -c "import plannotate; print('plannotate OK')"

クイックスタート

from plannotate import annotate, write_genbank, create_bokeh_chart
from Bio import SeqIO

# Load plasmid from FASTA
record = next(SeqIO.parse("plasmid.fasta", "fasta"))
sequence = str(record.seq)

# Annotate (circular, against Addgene database)
results = annotate(sequence, linear=False, db="addgene")
print(f"Found {len(results)} features")
print(results[["Feature", "Feature_type", "pct_identity", "pct_query_cov"]].to_string())

# Export GenBank file
write_genbank(sequence, results, output_file="plasmid_annotated.gb")

# Generate interactive HTML map
create_bokeh_chart(sequence, results, output_file="plasmid_map.html")
print("Outputs: plasmid_annotated.gb, plasmid_map.html")

ワークフロー

ステップ 1：プラスミド配列を読み込む

FASTA ファイル、GenBank ファイル（既存のアノテーションを削除して再アノテーション）、または生の配列文字列からプラスミド配列を読み込みます。アノテーションを付与する前に、長さと塩基組成を検証します。

from Bio import SeqIO
import os

# Option A: Load from FASTA
def load_fasta(path):
    record = next(SeqIO.parse(path, "fasta"))
    seq = str(record.seq).upper()
    return seq, record.id

# Option B: Load from GenBank (strip annotations, keep sequence)
def load_genbank(path):
    record = next(SeqIO.parse(path, "genbank"))
    seq = str(record.seq).upper()
    return seq, record.id

# Option C: Raw sequence string
raw_seq = "ATGCGTAAAGGAGAAGAACTTTTCACTGGAGTTGTCCCAATTCTTGTTGAATTAGATGGTGATGTT"

# Validate sequence
def validate_plasmid(seq, name="plasmid"):
    valid_bases = set("ATGCNRYSWKMBDHV")
    invalid = set(seq.upper()) - valid_bases
    if invalid:
        raise ValueError(f"Invalid bases in {name}: {invalid}")
    if len(seq) < 100:
        raise ValueError(f"Sequence too short ({len(seq)} bp); minimum 100 bp")
    gc = (seq.count("G") + seq.count("C")) / len(seq) * 100
    print(f"{name}: {len(seq):,} bp, GC={gc:.1f}%")
    return seq

seq, plasmid_id = load_fasta("plasmid.fasta")
validate_plasmid(seq, plasmid_id)

ステップ 2：BLAST ベースのアノテーションを実行する

選択したデータベースを使ってアノテーションを実行します。linear フラグは、配列を環状（プラスミドのデフォルト）として扱うか、線状（遺伝子ブロックや線状断片の場合）として扱うかを指定します。

from plannotate import annotate

# Annotate circular plasmid against the Addgene database (most comprehensive for common vectors)
results = annotate(
    seq,
    linear=False,       # False = circular plasmid (default)
    db="addgene",       # Database: "addgene", "fpbase", or "snapgene"
)

print(f"Total features detected: {len(results)}")
print(f"\nColumns: {list(results.columns)}")

# Preview feature table
cols = ["Feature", "Feature_type", "start", "end", "strand", "pct_identity", "pct_query_cov"]
print(results[cols].sort_values("start").to_string(index=False))

ステップ 3：品質しきい値で特徴をフィルタリングする

BLAST の一致率とクエリカバレッジスコアを使って、アノテーションの信頼度を確認します。信頼度の高いアノテーションは、一致率が 95% を超え、カバレッジが 90% を超えます。一部のみ一致するヒットは、特徴が切断されているか変異している可能性を示します。

import pandas as pd

# Inspect hit quality distribution
print("Identity percentile summary:")
print(results["pct_identity"].describe().round(1))
print("\nCoverage percentile summary:")
print(results["pct_query_cov"].describe().round(1))

# Separate high- and low-confidence hits
high_conf = results[
    (results["pct_identity"] >= 95) &
    (results["pct_query_cov"] >= 90)
].copy()

low_conf = results[
    (results["pct_identity"] < 95) |
    (results["pct_query_cov"] < 90)
].copy()

print(f"\nHigh-confidence features (identity>=95%, coverage>=90%): {len(high_conf)}")
print(f"Low-confidence / partial features:                       {len(low_conf)}")

if not low_conf.empty:
    print("\nLow-confidence features (review manually):")
    print(low_conf[["Feature", "Feature_type", "pct_identity", "pct_query_cov"]].to_string(index=False))

# Save filtered table
results.to_csv("all_features.csv", index=False)
high_conf.to_csv("high_confidence_features.csv", index=False)
print("\nSaved: all_features.csv, high_confidence_features.csv")

ステップ 4：アノテーション付き GenBank ファイルをエクスポートする

アノテーション付き配列を GenBank 形式で書き出し、プラスミドエディター（SnapGene、Benchling、Geneious、ApE）へのインポートや、BioPython ベースの後続解析に利用します。

from plannotate import write_genbank

# Write full annotation (all features)
write_genbank(seq, results, output_file="plasmid_annotated.gb")
print("Written: plasmid_annotated.gb")

# Write with high-confidence features only
write_genbank(seq, high_conf, output_file="plasmid_highconf.gb")
print("Written: plasmid_highconf.gb")

# Verify using BioPython
from Bio import SeqIO
record = next(SeqIO.parse("plasmid_annotated.gb", "genbank"))
print(f"\nGenBank verification:")
print(f"  Sequence length: {len(record.seq):,} bp")
print(f"  Features: {len(record.features)}")
for feat in record.features:
    label = feat.qualifiers.get("label", ["(unlabeled)"])[0]
    print(f"  [{feat.type:20s}] {label} @ {feat.location}")

ステップ 5：インタラクティブな HTML 可視化を生成する

Bokeh ベースのインタラクティブなプラスミドマップを作成します。HTML ファイルは自己完結型で、サーバー環境がなくても共有できます。

from plannotate import create_bokeh_chart

# Generate interactive circular plasmid map
create_bokeh_chart(
    seq,
    results,
    output_file="plasmid_map.html",
)
print("Interactive map saved: plasmid_map.html")
print("Open in any browser — no server required")

# Tip: open automatically in the default browser
import webbrowser, os
webbrowser.open(f"file://{os.path.abspath('plasmid_map.html')}")

ステップ 6：BioPython で GenBank 出力を解析する

制限酵素認識部位のマッピング、プライマー設計、コンストラクト検証レポートなどの後続解析に向けて、アノテーション済みの特徴をプログラムで抽出します。

from Bio import SeqIO
from Bio.SeqFeature import FeatureLocation
import pandas as pd

record = next(SeqIO.parse("plasmid_annotated.gb", "genbank"))

# Build a feature DataFrame from the GenBank record
rows = []
for feat in record.features:
    label = feat.qualifiers.get("label", [""])[0]
    note  = feat.qualifiers.get("note",  [""])[0]
    rows.append({
        "type":   feat.type,
        "label":  label,
        "note":   note,
        "start":  int(feat.location.start),
        "end":    int(feat.location.end),
        "strand": feat.location.strand,
        "length": len(feat.location),
    })

feat_df = pd.DataFrame(rows)
print(feat_df.to_string(index=False))

# Example: find antibiotic resistance genes
resistance = feat_df[feat_df["label"].str.contains(
    r"AmpR|KanR|CmR|TetR|SpecR|HygR|ZeoR|BlastR|GentR",
    case=False, na=False, regex=True
)]
print(f"\nAntibiotic resistance markers found: {len(resistance)}")
print(resistance[["label", "start", "end", "length"]].to_string(index=False))

ステップ 7：複数のプラスミドに一括でアノテーションを付与する

マルチ FASTA ファイルまたは個別の FASTA ファイルを格納したディレクトリ内のクローニングライブラリ全体にアノテーションを付与し、結果を単一のサマリーテーブルに集約します。

from plannotate import annotate, write_genbank, create_bokeh_chart
from Bio import SeqIO
import pandas as pd
import os

input_dir  = "plasmids/"          # directory of *.fasta files
output_dir = "annotated_results/"
os.makedirs(output_dir, exist_ok=True)

summary_rows = []

for fasta_file in sorted(f for f in os.listdir(input_dir) if f.endswith(".fasta")):
    plasmid_name = fasta_file.replace(".fasta", "")
    fasta_path   = os.path.join(input_dir, fasta_file)

    record = next(SeqIO.parse(fasta_path, "fasta"))
    seq    = str(record.seq).upper()

    print(f"Annotating {plasmid_name} ({len(seq):,} bp)...", end=" ")
    results = annotate(seq, linear=False, db="addgene")
    print(f"{len(results)} features")

    # Save per-plasmid outputs
    write_genbank(
        seq, results,
        output_file=os.path.join(output_dir, f"{plasmid_name}.gb")
    )
    create_bokeh_chart(
        seq, results,
        output_file=os.path.join(output_dir, f"{plasmid_name}.html")
    )
    results.to_csv(os.path.join(output_dir, f"{plasmid_name}_features.csv"), index=False)

    # Accumulate for summary
    results["plasmid"] = plasmid_name
    summary_rows.append(results)

# Consolidated summary table
summary = pd.concat(summary_rows, ignore_index=True)
summary.to_csv(os.path.join(output_dir, "all_plasmids_features.csv"), index=False)
print(f"\nBatch complete. {summary['plasmid'].nunique()} plasmids annotated.")
print(f"Summary table: {output_dir}all_plasmids_features.csv")

主なパラメーター

パラメーター	デフォルト	範囲／オプション	効果
linear	False	True、False	配列を直鎖状（True）または環状（False）として扱います。環状モードでは、開始点をまたぐ分割フィーチャーを正しく処理します
db	"addgene"	"addgene"、"fpbase"、"snapgene"	検索するフィーチャーデータベースです。addgene が最も幅広く（プロモーター、薬剤耐性遺伝子、複製起点、タグ）、fpbase では蛍光タンパク質のバリアントが追加され、snapgene には SnapGene がキュレーションしたフィーチャーが含まれます
min_len	0	0–500 bp	フィーチャーの最小長（bp）です。値を大きくすると、短い誤検出を抑制できます
blast_identity_threshold	95	70–100 %	ヒットとして報告する BLAST の最小一致率です。値を低くすると、より離れた相同配列を検出できますが、偽陽性も増えます
--html（CLI）	オフ	フラグ	GenBank 出力と合わせて、インタラクティブな HTML プラスミドマップを生成します
--csv（CLI）	オフ	フラグ	CSV フィーチャーテーブルを出力ディレクトリに書き込みます
--linear（CLI）	オフ	フラグ	入力を直鎖状配列として扱います（デフォルトは環状です）
--file / --input（CLI）	必須	FASTA パス	FASTA 形式の入力プラスミド配列です

よくあるレシピ

レシピ：インタラクティブに使うための Web アプリの起動

使用する場面：コードを書かずに単一のプラスミドをインタラクティブに調べる場合や、ブラウザーインターフェースを好むウェットラボの共同研究者と共有する場合です。

# Launch the pLannotate Streamlit web app (opens in browser at localhost:5000)
plannotate streamlit

# Or specify a custom port
plannotate streamlit --port 8501

レシピ：CLI による一括アノテーション

使用する場面：スクリプト化されたワークフローで複数のプラスミドにアノテーションを付ける場合や、Python のスクリプトを使わずにリモートサーバーで実行する場合です。

# Single plasmid
plannotate batch \
    --input plasmid.fasta \
    --output results/ \
    --html \
    --csv

# Multiple plasmids via shell glob
for f in plasmids/*.fasta; do
    name=$(basename "$f" .fasta)
    plannotate batch \
        --input "$f" \
        --output "annotated/${name}/" \
        --html --csv
done
echo "Done. Outputs in annotated/"

レシピ：変異導入前後のアノテーションの比較

使用する場面：部位特異的変異導入や挿入によって既存のフィーチャーが損なわれたり、意図しないフィーチャーが追加されたりしていないことを確認する場合です。

from plannotate import annotate
from Bio import SeqIO
import pandas as pd

def annotation_diff(seq_before, seq_after, db="addgene"):
    res_before = annotate(seq_before, linear=False, db=db)
    res_after  = annotate(seq_after,  linear=False, db=db)

    features_before = set(res_before["Feature"])
    features_after  = set(res_after["Feature"])

    gained = features_after  - features_before
    lost   = features_before - features_after
    shared = features_before & features_after

    print(f"Shared features: {len(shared)}")
    print(f"Gained features: {gained if gained else 'none'}")
    print(f"Lost features:   {lost   if lost   else 'none'}")
    return res_before, res_after

seq_wt  = str(next(SeqIO.parse("plasmid_wt.fasta",  "fasta")).seq)
seq_mut = str(next(SeqIO.parse("plasmid_mut.fasta", "fasta")).seq)
res_before, res_after = annotation_diff(seq_wt, seq_mut)

レシピ：条件付き書式を設定してフィーチャーテーブルを Excel にエクスポート

使用する場面：GenBank ファイルよりもスプレッドシートを好む共同研究者とアノテーション結果を共有する場合です。

from plannotate import annotate
from Bio import SeqIO
import pandas as pd

seq = str(next(SeqIO.parse("plasmid.fasta", "fasta")).seq)
results = annotate(seq, linear=False, db="addgene")

# Tidy column selection and renaming
export = results[[
    "Feature", "Feature_type", "start", "end", "strand",
    "pct_identity", "pct_query_cov", "database"
]].copy()
export.columns = [
    "Feature Name", "Type", "Start (bp)", "End (bp)", "Strand",
    "Identity (%)", "Coverage (%)", "Database"
]
export["Length (bp)"] = export["End (bp)"] - export["Start (bp)"]
export = export.sort_values("Start (bp)")

# Write to Excel with conditional formatting
with pd.ExcelWriter("plasmid_features.xlsx", engine="openpyxl") as writer:
    export.to_excel(writer, sheet_name="Features", index=False)

print(f"Exported {len(export)} features to plasmid_features.xlsx")

予想される出力

出力ファイル	形式	説明
plasmid_annotated.gb	GenBank	フィーチャーのアノテーションが付いた配列です。SnapGene、Benchling、Geneious、ApE、BioPython にインポートできます
plasmid_map.html	HTML	自己完結型のインタラクティブな環状プラスミドマップ（Bokeh）です。サーバーなしで共有できます
all_features.csv	CSV	Feature、Feature_type、start、end、strand、pct_identity、pct_query_cov、database の各列を含む表形式のフィーチャー一覧です
high_confidence_features.csv	CSV	一致率 >= 95% かつカバレッジ >= 90% のフィーチャーに絞り込んだ一覧です
all_plasmids_features.csv	CSV	一括処理モード：全プラスミドのフィーチャーを集約し、plasmid 列を含みます

トラブルシューティング

問題	原因	解決策
FileNotFoundError: blastn not found	BLAST+ が PATH に含まれていません	conda でインストールします：conda install -c bioconda blast。またはパッケージマネージャーでインストールします：brew install blast（macOS）／apt install ncbi-blast+（Linux）
No features detected	配列が短すぎる、データベースが間違っている、または非標準塩基が含まれています	配列長が 500 bp 以上であることを確認します。別の db（蛍光タンパク質ベクターの場合は "fpbase" など）を試します。validate_plasmid() で曖昧な塩基を確認します
注釈が位置 0 で正しく折り返されません	配列が環状ではなく線状として扱われています	linear=False を設定します（デフォルト）。これにより、配列の起点をまたぐ特徴を検出できるよう、環状 BLAST が有効になります
HTML マップが空白で表示されます	bokeh のバージョンが一致していません	アップグレードします：pip install --upgrade bokeh。pLannotate には Bokeh >=2.4 が必要です
既知の特徴の一致度が低くなります	特徴配列が変異しているか、コドン最適化されています	blast_identity_threshold を 85～90% に下げます。これらが分岐した相同配列であることを注記します
MemoryError が発生する、または注釈が非常に遅くなります	配列が 50 kb を超えているか、BLAST データベースのインデックスが作成されていません	大きな配列をサブ領域に分割します。pLannotate の内部データベースインデックスが存在することを確認します（必要に応じて再インストールしてください）
SnapGene で GenBank ファイルを解析できません	特徴タイプのラベルが標準形式ではありません	まず Geneious または BioPython で開きます。特徴修飾子に特殊文字が含まれていないか確認します

参考資料

• pLannotate GitHub：mmcguffi/pLannotate — ソースコード、課題トラッカー、インストール手順
• McGuffi M et al. (2021) Nucleic Acids Research 49(W1): W516–W522 — BLAST ベースの注釈パイプラインとキュレーション済み特徴データベースについて解説した、pLannotate の原著論文
• pLannotate PyPI：plannotate — パッケージのメタデータ、バージョン履歴、pip によるインストール情報
• Addgene プラスミドリポジトリ — pLannotate が使用するキュレーション済み特徴ライブラリの主な情報源
• BioPython SeqIO ドキュメント — GenBank 出力ファイルの解析と操作