plannotate-plasmid-annotation

pLannotate 质粒注释

概述

pLannotate 通过对一个精选库运行 BLAST 搜索来注释质粒序列，该库包含超过 5,000 个来自 Addgene、NCBI 和 fpbase 的元件。它能够识别启动子、终止子、抗生素抗性基因、复制起点、标签和荧光蛋白，同时正确处理环状质粒拓扑结构，避免朴素线性比对导致的元件拆分伪影。结果可导出为已注释的 GenBank 文件，供 SnapGene、Benchling 或 BioPython 后续使用；也可导出为交互式 HTML 质粒图，便于分享和审阅；还可导出为 CSV 表格，以便进行程序化筛选。它同时提供 Python API 和命令行界面；此外还打包了一个 Streamlit Web 应用，供探索性使用。

适用场景

• 为从合作者处收到或从 Addgene 下载、但没有附带图谱的质粒序列添加注释
• 在组装或诱变后，验证所有预期元件（启动子、插入片段、抗性标记、复制起点）是否存在
• 准备需要完整元件表的 GenBank 提交或 Addgene 存放文件
• 为组合克隆产生的合成构建文库批量添加注释
• 生成可分享的交互式质粒图（HTML），无需 SnapGene 或 Benchling 许可证
• 在克隆前检查从头合成的基因片段是否含有非预期的调控元件或隐性 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 等（2021）《Nucleic Acids Research》49(W1)：W516–W522 — 介绍基于 BLAST 的注释流程和精选特征数据库的 pLannotate 原始论文
• pLannotate PyPI：plannotate — 软件包元数据、版本历史和 pip 安装信息
• Addgene 质粒库 — pLannotate 使用的精选特征库的主要来源
• BioPython SeqIO 文档 — 解析和处理 GenBank 输出文件