PyPLogo

PyPLogo 是面向蛋白质二级结构与多序列比对的 Python 可视化工具，提供紧凑、现代、适合论文排版的结构符号，并保留对布局、颜色、图例和生物学标注的细粒度控制。

PyPLogo is a Python toolkit for publication-ready visualization of protein secondary structures and multiple-sequence alignments. It combines compact modern structure glyphs with fine control over layout, colors, legends, and biological annotations.

The public examples below use chain A of hen egg-white lysozyme from PDB 1LYZ. The variant rows and surface-patch markers are illustrative documentation data, not a user dataset or a biological claim.

核心能力 / Highlights

• 绘制单条蛋白序列及其 DSSP 二级结构。

• 在多序列比对中选择任意一条序列作为二级结构参考。

• 螺旋使用拼接菱形块，beta 折叠使用扁平箭头，转角使用 T、TT 或 TTT。

• 默认显示主要结构 H/G/I/E/T；可选完整模式显示 bend 和 coil。

• 支持二硫键、抗体结合表位、保守性底色、残基编号和多行换行。

• 可调字体、行距、结构间距、颜色、图例、标记、注释轨道和画布尺寸。

• 通过 Matplotlib 导出高分辨率 PNG、矢量 SVG 或 PDF。

• Visualize a single protein sequence with DSSP secondary-structure assignments.

• Select any aligned sequence as the secondary-structure reference.

• Show faceted helix glyphs, flat beta-strand arrows, and compact turn labels.

• Annotate disulfide bonds, antibody epitopes, conservation, and residue numbers.

• Export publication-ready raster or vector figures through Matplotlib.

安装 / Installation

pip install -U pyplogo

PyPI 包要求 Python 3.10 或更高版本。使用 PDB/mmCIF 的 DSSP 自动提取功能时，系统还需要可用的 mkdssp/DSSP 可执行程序。

The PyPI package requires Python 3.10 or later. Structure extraction from PDB/mmCIF files additionally requires an available mkdssp/DSSP executable.

单序列快速开始 / Single Sequence

from pyplogo import SecondaryStructureVisualizer

sequence = "KVFGRCELAAAMKRHGLDNYRGYSLGNWVCAAKFESNFNTQATNRNTDGSTDYGILQINSRWWCNDGRTPGSRNLCNIPCSALLSSDITASVNCAKKIVSDGNGMNAWVAWRNRCKGTDVQAWIRGCRL"
secondary_structure = "CECCHHHHHHHHHHTTCTTETTECTHHHHHHHHHHHTTESSCEEECTTSCEEETTTTEETTTSCECSSCTTCCCTTCSEGGGGGSSCCHHHHHHHHHHTTSSSGGGGSHHHHHHTTTSCGGGGSTTCCC"

visualizer = SecondaryStructureVisualizer(row_length=50)
figure = visualizer.create_figure(
    sequence=sequence,
    secondary_structure=secondary_structure,
    title="Hen egg-white lysozyme (PDB 1LYZ)",
    show_residue_numbers=True,
)
figure.savefig("secondary_structure.svg", bbox_inches="tight")

sequence 与 secondary_structure 必须等长。PyPLogo 使用 DSSP 字母：H、G、I、E、T、S，coil 使用 C。

sequence and secondary_structure must have the same length. PyPLogo accepts the DSSP codes H, G, I, E, T, and S, with C for coil.

多序列比对 / Multiple-Sequence Alignment

PyPLogo 接收已经对齐且长度相同的序列；它负责绘图，不负责执行序列比对。gap 可以写作 - 或 .。

PyPLogo draws an existing equal-length alignment; it does not run the alignment algorithm. Gaps may be written as - or ..

from pyplogo import SecondaryStructureVisualizer

alignment = {
    "Lysozyme_1LYZ": "KVFGRCELAAAMKRHGLDNYRGYSLGNWVCAAKFESNFNTQATNRNTDGSTDYGILQINSRWWCNDGRTPGSRNLCNIPCSALLSSDITASVNCAKKIVSDGNGMNAWVAWRNRCKGTDVQAWIRGCRL",
    "Lysozyme_variant_A": "KVFGRCELAVAMKRHGLDNYRGYSLGNWVCAAKFESNSNTQATNRNTDGSTDYGILQINSRWWCNDGRTPGSRNLCNIPCSALLSSDITASVNCAKKIVSDGNGMNAWVAWRNRCKGTDVQAWIRGCRL",
    "Lysozyme_variant_B": "KVFGRCELAAAMKRHGQDNYRGYSLGNWVCAAKFESNFNTQATNRNTDGSTDYGILQINSRWWCNDGRTPGSRNLCNIPCSALLSSDITASVNCAKKIVSDGNGMNAWVAWRNRCKGTDVQAWIRGCRL",
}

visualizer = SecondaryStructureVisualizer(
    colors={
        "H": "#39A96B",
        "G": "#D982AA",
        "I": "#6878C9",
        "E": "#D7A354",
        "T": "#8F7CC3",
        "structure_label": "#9A642D",
        "background": "#FFFFFF",
    }
)

figure = visualizer.create_alignment_figure(
    alignment=alignment,
    structure_sequence="Lysozyme_1LYZ",
    # DSSP assignment for the public 1LYZ chain A sequence.
    secondary_structure="CECCHHHHHHHHHHTTCTTETTECTHHHHHHHHHHHTTESSCEEECTTSCEEETTTTEETTTSCECSSCTTCCCTTCSEGGGGGSSCCHHHHHHHHHHTTSSSGGGGSHHHHHHTTTSCGGGGSTTCCC",
    structure_label="1LYZ structure",
    amino_acids_per_line=65,
    structure_mode="major",
    sequence_colors={
        "Lysozyme_1LYZ": "#986B36",
        "Lysozyme_variant_A": "#5B6B7A",
        "Lysozyme_variant_B": "#6F68A8",
    },
    # Disulfides reported for the public 1LYZ chain A structure.
    disulfide_bonds=[(6, 127), (30, 115), (64, 80), (76, 94)],
    epitope_annotations={
        "Illustrative surface patch A": [22, 23, 24, 25],
        "Illustrative surface patch B": [52, 53, 54, 55],
        "Illustrative surface patch C": [101, 102, 103, 104],
    },
    epitope_colors={
        "Illustrative surface patch A": "#8CB9DC",
        "Illustrative surface patch B": "#D59A9A",
        "Illustrative surface patch C": "#A8C565",
    },
    show_legend=True,
    legend_position="bottom",
)
figure.savefig("alignment.svg", bbox_inches="tight")
figure.savefig("alignment.png", dpi=600, bbox_inches="tight")

secondary_structure 可以使用所选参考序列的无 gap 长度，也可以使用完整比对长度。二硫键和表位位置均使用所选参考序列的 1-based 无 gap 残基编号。

示例中的三个 surface patch 只是演示注释轨道的占位数据；实际项目中可以替换为实验或结构分析得到的残基位置。

secondary_structure may follow either the selected sequence's ungapped length or the full alignment length. Disulfide and epitope positions use 1-based ungapped residue coordinates from the selected reference sequence.

结构符号 / Structure Glyphs

T、TT 和 TTT 对应连续 1、2、3 个或更多 turn 残基。默认 structure_mode="major" 显示 H/G/I/E/T；设置 structure_mode="all" 后额外显示 S/C 和 gap 连接符。

T, TT, and TTT represent runs of one, two, or at least three turn residues. The default structure_mode="major" shows H/G/I/E/T; structure_mode="all" additionally shows bends, coils, and gap connectors.

自定义参数 / Customization

The defaults provide the base publication style; every group above can be overridden per figure without changing the renderer.

PDB/mmCIF 提取 / Structure Extraction

from pyplogo.extractors.structure_based import StructureExtractor
from pyplogo import SecondaryStructureVisualizer

data = StructureExtractor().from_pdb("1LYZ.pdb", chain_id="A")

visualizer = SecondaryStructureVisualizer()
figure = visualizer.create_figure(
    sequence=data.sequence,
    secondary_structure=data.secondary_structure,
    disulfide_bonds=data.disulfide_bonds,
    title="Hen egg-white lysozyme (PDB 1LYZ), chain A",
)
figure.savefig("chain_A.pdf", bbox_inches="tight")

from_cif("protein.cif", chain_id="A") 提供相同的 mmCIF 工作流。

Links

• GitHub: https://github.com/SLF1303/pyplogo-toolkit
• PyPI: https://pypi.org/project/pyplogo/
• Issues: https://github.com/SLF1303/pyplogo-toolkit/issues

PyPLogo is released under the MIT License.