Skip to content

prot-struct-viz

Render one or more views of a protein structure as a self-contained static HTML file using Mol*, with residues colored, labeled, and styled from YAML and CSV configuration. See the examples for an illustration.

Install

pip install prot-struct-viz

Or, to develop the package, check out the latest code from GitHub and run:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,docs]"

Quick start

Write a CSV naming the residues you want to say something about:

chain,residue,color,label,show_label
A,118,#67000d,Arg118,True
A,119,#cb181d,Glu119,

Then write a spec file saying what to draw and where to put it:

# spec.yaml
structure: 1F8B
out: view.html
assembly: "1"
on_mismatch: report

views:
  - name: Active site
    csv: coloring.csv
    default_color: "#d9d9d9"
    default_representation: cartoon
    waters: hide
    ligands: show
    glycans: snfg
    ions: show

Then simply run:

prot-struct-viz spec.yaml

That writes view.html (the page) and view_report.txt (the progress log, and a report on any disagreement between the CSV and the structure). The output file can also be specified at the command line by omitting out from the spec and passing --out instead; see where the page is written.

See the spec reference for details on how to write the YAML and CSV files.

Several views of one structure

A spec may list more than one view, and the page then offers a selector:

views:
  - name: Antigenic sites
    csv: antigenic.csv
    default_representation: surface
    # ... the rest of the required keys
  - name: Receptor contacts
    csv: contacts.csv
    default_representation: cartoon
    glycans: hide
    # ... the rest of the required keys

Sharing the view

The output is a single HTML file with no server side, so committing it to a repository with GitHub Pages enabled is all that is needed to share it:

mkdir -p docs && cp view.html docs/
git add docs/view.html && git commit -m "Add structure view" && git push

Set Pages to serve from /docs on the default branch, and the view is at https://<org>.github.io/<repo>/view.html. Add #view=<slug> to point at one particular view of a multi-view page (see linking to a view).

Where to go next

  • Examples — rendered views, with the command and inputs that made them.
  • Spec reference — every key, plus assemblies, representation layers, heteroatoms, and checking the CSV against the structure.
  • CSV schema — every column, and what makes a CSV invalid.
  • The rendered page — what a reader of the output can click.
  • Python API — building a spec in Python instead of YAML.
  • How it works — the MolViewSpec pipeline, for anyone extending this.