rosettacommons / pyrosetta_viewer3d

Display PackedPose objects, Pose objects, or PDB files within a Jupyter notebook and Google Colab

viewer3d

Display PackedPose objects, Pose objects, or .pdb files within a Jupyter notebook and Google Colab.

Description

The viewer3d macromolecular viewer quickly renders .pdb files, dynamically instantiating Pose objects if required for certain visualization modules (matching the name viewer3d.set*). So when adding visualization modules to the viewer or using presets, passing Pose or PackedPose objects to the viewer is suggested for quicker rendering. If a Pose object or list, tuple, or set of Pose objects are provided to the viewer, the Pose(s) pointer location(s) in memory remain fixed, and so the viewer can dynamically update upon Pose conformational changes by calling the following methods:

update_viewer(index=None, model=None, add_objects=True, remove_objects=True)

add_pose(pose, index=None, update_viewer=True)

add_pdbstring(pdbstring, index=None, update_viewer=True)

remove_pose(index=None, model=None, update_viewer=True)

remove_pdbstring(index=None, model=None, update_viewer=True)

update_pose(pose, index=None, model=None, update_viewer=True)

update_pdbstring(pdbstring, index=None, model=None, update_viewer=True)

update_poses(poses, index=None, update_viewer=True)

update_pdbstrings(pdbstrings, index=None, update_viewer=True)

For adding/removing visualization modules in the widget update function, either initialize the viewer with viewer3d.init(modules=[...]) or call the set_modules() method to overwrite the current list of modules. Otherwise, call the clear() method then add the new modules. After pose conformational changes and setting the viewer modules, call the update_viewer() method if the pose's pointer in memory remains the same, otherwise call the update_pose(pose) method to update the pose and viewer.

See docstrings for more information. The viewer applies visualization modules in the same order they are added (from left to right), so layering different styles (and ResidueSelectors) on top of one another becomes possible. The user must have already initialized PyRosetta providing .params files for any ligands and non-canonical residues in the input molecule(s), otherwise pyrosetta.distributed automatically initializes PyRosetta with default command line options.

Contributing

Please open a pull request with an updated unit test from a custom branch.

Unit Tests

python -m unittest

Installation

conda env create -f environment.yml

PyPI Releases

1. Update version number in setup.py
2. pip install --user --upgrade setuptools wheel twine
3. rm -rf dist/*
4. python setup.py sdist bdist_wheel
5. python -m twine upload dist/*

Usage Examples:

import viewer3d

Example Jupyter notebook commands:

v = viewer3d.init("path/to/pdbfile.pdb")
v.show()

import logging
logging.basicConfig(level=logging.WARNING)
import pyrosetta
pyrosetta.init("-mute all")

pose = pyrosetta.toolbox.rcsb.pose_from_rcsb("5BVL")

view = viewer3d.init(pose, window_size=(800, 600), backend="nglview")
view() # Equivalent to view.show()

poses = [pyrosetta.toolbox.rcsb.pose_from_rcsb(pdbid) for pdbid in ["5BVL", "6MSR", "1QCQ"]]

view = viewer3d.init(poses) \
+ viewer3d.setStyle(colorscheme="lightgreyCarbon") \
+ viewer3d.setHydrogenBonds()
view()

import pyrosetta.distributed.io as io
packed_pose = io.to_packed(pyrosetta.toolbox.pose_from_rcsb("2FD7"))
polar_residue_selector = pyrosetta.rosetta.core.select.residue_selector.ResiduePropertySelector(
    pyrosetta.rosetta.core.chemical.ResidueProperty(52)
)

view = viewer3d.init(packed_pose)
view.add(viewer3d.setStyle(radius=0.1))
view.add(viewer3d.setStyle(residue_selector=polar_residue_selector, colorscheme="whiteCarbon", radius=0.25, label=False))
view.add(viewer3d.setHydrogens(color="white", polar_only=True, radius=0.1))
view.add(viewer3d.setHydrogenBonds(color="black"))
view.add(viewer3d.setDisulfides(radius=0.1))
view()

view = sum(
    [
        viewer3d.init(packed_pose),
        viewer3d.setStyle(cartoon=False, style="sphere", radius=1.5, colorscheme="darkgreyCarbon"),
        viewer3d.setZoom(factor=1.5)
    ]
)
view.show()

from pyrosetta.rosetta.core.select.residue_selector import ChainSelector
pose = pyrosetta.toolbox.rcsb.pose_from_rcsb("6MSR")
chA = ChainSelector("A")
chB = ChainSelector("B")

view = sum(
    [
        viewer3d.init(pose, backend=1, gui=True),
        viewer3d.setStyle(cartoon_color="lightgrey", radius=0.25),
        viewer3d.setSurface(residue_selector=chA, colorscheme="greenCarbon", opacity=0.65, surface_type="VDW"),
        viewer3d.setSurface(residue_selector=chB, color="blue", opacity=1.0, surface_type="SAS"),
        viewer3d.setDisulfides(radius=0.25),
        viewer3d.setZoom(factor=1.5)
    ]
)
view()

import pyrosetta.distributed.io as io
import viewer3d
from pyrosetta.rosetta.core.select.residue_selector import (
    LayerSelector,
    ChainSelector,
)

poses = [io.pose_from_sequence("TEST" * i) for i in range(1, 6)]
core_selector = LayerSelector()
core_selector.set_layers(True, False, False)
boundary_selector = LayerSelector()
boundary_selector.set_layers(False, True, False)
surface_selector = LayerSelector()
surface_selector.set_layers(False, False, True)
view = (
    viewer3d.init(poses, (1200, 800.01), delay=0, backend=1) \
    + viewer3d.setStyle()  #residue_selector=surface_selector, style="stick", colorscheme="element", label=False) #+ viewer3d.setSurface(opacity=0.5)
    + viewer3d.setDisulfides() \
    + viewer3d.setBackgroundColor(color="lightgray")
    + viewer3d.setHydrogenBonds()
    + viewer3d.setHydrogens(polar_only=True, color="white")
    + viewer3d.setZoomTo(ChainSelector("A")) \
    + viewer3d.setZoom(-1) \
)
view.show()

from pyrosetta.rosetta.core.select.residue_selector import SecondaryStructureSelector
helix_selector = SecondaryStructureSelector("H")
sheet_selector = SecondaryStructureSelector("E")
loop_selector = SecondaryStructureSelector("L")

modules = [
    viewer3d.setBackgroundColor(color="grey"),
    viewer3d.setStyle(residue_selector=helix_selector, cartoon_color="blue", label=False, radius=0),
    viewer3d.setStyle(residue_selector=sheet_selector, cartoon_color="red", label=False, radius=0),
    viewer3d.setStyle(residue_selector=loop_selector, cartoon_color="white", label=False, radius=0)
]

view = viewer3d.init(poses, window_size=(1200, 600), modules=modules, continuous_update=True)
view()

view.clear() # Subtract all visualization modules previously added to the Viewer
view()

View a live trajectory:

pose = pyrosetta.toolbox.pose_from_rcsb("2FD7")
v = viewer3d.init(pose, delay=0.1) + viewer3d.setStyle(radius=0.1) + viewer3d.setDisulfides(radius=0.1)
backrub = pyrosetta.rosetta.protocols.backrub.BackrubMover()
minimize = pyrosetta.rosetta.protocols.minimization_packing.MinMover()

for _ in range(100):
    backrub.apply(pose)
    minimize.apply(pose)
    v.update_pose(pose)

Display preset custom viewers for routine visualizations:

viewer3d.presets.coreBoundarySurface(poses, window_size=(800, 600), continuous_update=True)

view = viewer3d.presets.makeBundle(backend=1)
view.show()

Visualize the residue 1 psi-space of a 20-residue polyvaline extended peptide:

from bokeh.palettes import Viridis
n = 11 # 256
v = viewer3d.init(backend=1)
pose = pyrosetta.io.pose_from_sequence("V" * 20)
for i, hex_str in enumerate(Viridis[n]):
    v.set_modules(viewer3d.setStyle(cartoon_color=hex_str, radius=0))
    pose.set_psi(1, i * 360 / n)
    v.add_pose(pose)

Overlay multiple poses:

pose1 = pyrosetta.toolbox.rcsb.pose_from_rcsb("6V67")
pose2 = pyrosetta.toolbox.rcsb.pose_from_rcsb("1ATP")
v = viewer3d.init()
v += viewer3d.setStyle(colorscheme='redCarbon')
v += viewer3d.setSurface()
v.add_pose(pose1) # Automatically updates the viewer with the currently set modules
v.reset() # Subtract all modules
v += viewer3d.setStyle(colorscheme='blueCarbon')
v.add_pose(pose2)

View different sets of different overlaid poses:

pose = pyrosetta.toolbox.pose_from_rcsb("2FD7")
v = viewer3d.init(pose, delay=0, backend=1)
backrub = pyrosetta.rosetta.protocols.backrub.BackrubMover()
minimize = pyrosetta.rosetta.protocols.minimization_packing.MinMover()
v.set_modules([viewer3d.setStyle(), viewer3d.setDisulfides()])

for h in range(5):
    for i in range(5):
        for j in range(5):
            backrub.apply(pose)
            minimize.apply(pose)
        v.add_pose(pose.clone(), index=h, update_viewer=False)
v.show()

Overlay all poses or PDB strings:

v.overlay()

Color residues by PerResidueRealMetrics:

scorefxn = pyrosetta.create_score_function("ref2015")
minimize = pyrosetta.rosetta.protocols.minimization_packing.MinMover()
e = (
    pyrosetta.rosetta.core.simple_metrics.per_residue_metrics.PerResidueEnergyMetric()
)
e.set_scorefunction(scorefxn)
v = viewer3d.init(backend=backend, gui=True)
palette = list(bokeh.palettes.Greens256) + list(
    reversed(bokeh.palettes.Reds256)
)
v += viewer3d.setStyle(radius=0)
v += viewer3d.setPerResidueRealMetric(
    scoretype="res_energy", vmin=-10, vmax=10, radius=0.2, log=10, palette=palette
)
v += viewer3d.setHydrogens(polar_only=True, color="lightgray")
v += viewer3d.setHydrogenBonds()
v += viewer3d.setDisulfides()
for h in range(10):
    _pose = pose.clone()
    _pose.scores.clear()
    for i in range(20):
        minimize.apply(_pose)
    e.apply(_pose)
    v.add_pose(_pose, index=h, update_viewer=False)
v.show()

Color residues by per-residue total score:

v = viewer3d.presets.perResidueEnergyMetric(pose)
v.show()

Color residues by per-residue clash score:

v = viewer3d.presets.perResidueClashMetric(poses, backend=0)
v.show()

Color residues by per-residue SASA score:

v = viewer3d.presets.perResidueSasaMetric(pose, backend=1)
v.show()

Color residues by per-residue satisfied backbone hydrogen bonds:

v = viewer3d.presets.unsatSelector(pose)
v.show()

Visualize multiple Rosetta analyses:

v = viewer3d.presets.rosettaViewer(poses, backend=1)
v.show()

pyrosetta_viewer3d's Issues

Simple display of pose does not seem to work in master

Notebook here:

https://colab.research.google.com/drive/1KcecP88_NpNGw2o2wv4LCLhPGGC9YZtz?usp=sharing

import pyrosetta; pyrosetta.init()
pose = pyrosetta.pose_from_sequence('TESTTHISEPICLIFE')

import viewer3d
v = viewer3d.init(pose,backend="py3Dmol", window_size=(600,600)) + viewer3d.setStyle(cartoon=True, colorscheme="lightgreyCarbon")
v.show()

Enable commit squashing

@klimaj Could you enable commit squashing?
https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests

Make repo public

Could we make this repo public?
It would make it much easier to install into google colab and for other people to collaborate.

Error when installing

When I try to install python setup.py develop I get the error

running develop
running egg_info
creating viewer3d.egg-info
writing viewer3d.egg-info/PKG-INFO
writing dependency_links to viewer3d.egg-info/dependency_links.txt
writing top-level names to viewer3d.egg-info/top_level.txt
writing manifest file 'viewer3d.egg-info/SOURCES.txt'
error: package directory 'ipywidgets>=7/5/1' does not exist

Not sure where this is coming from

Color pose by per-residue SASA

nglview (and probably py3Dmol) permit creating custom color palettes. It would be cool to have a preset that colors a pose by various biophysical metrics such as per-residue SASA, per-residue energy, per-residue clashes, etc.

Built-in color schemes are here: https://nglviewer.org/ngl/api/manual/coloring.html
Example use of ColormakerRegistry: https://projects.volkamerlab.org/teachopencadd/talktorials/T017_advanced_nglview_usage.html#Custom-coloring-schemes-and-representations
https://github.com/volkamerlab/kissim_app/blob/f63327e/notebooks/fingerprints/feature_distribution_per_residue.ipynb#Side-chain-orientation
For example, the pdb_prot_align module implements similar: https://jbloomlab.github.io/pdb_prot_align/nglview_example.html

Update docstrings, typing, and documentation

Expand bundle mover preset with z_offset

Z_offset is not currently implemented

How to show two poses overlapped?

I'd like to show to poses at the same time (i.e. before and after relax).

What would be the best way to do that?

Where to put rosetta output when showing widgets

Rosetta is pretty verbose. For example in the bundle preset when sliders are moved output get's printed and moves everything around.

One way is to use -mute all. Another is to use output widget
Not sure if that should be built into the preset directly or used by the end user.

Make Jupyter notebook with usage examples

The README.md file contains some use-case examples, but these should be expanded in an interactive Jupyter notebook.

Viewer does not accept PDB file string

Example code:

v = viewer3d.init("/mnt/net/shared/scaffolds/pre_scaffold_DB/tj_DHRs_filtered/X12_3_13_4_ct1_fe.pdb")
v.show()

Make the multiple pose viewer a preset as well

The multiple pose viewer should probably be a preset (and the slider should be in the widget class).

Logically it fits much cleaner and would remove extra code that is now in the base viewer.

Make presets for additional PerResidueRealMetrics

pyrosetta.rosetta.core.simple_metrics.per_residue_metrics.HbondMetric

pyrosetta.rosetta.core.simple_metrics.per_residue_metrics.PerResidueGlycanLayerMetric

pyrosetta.rosetta.core.simple_metrics.per_residue_metrics.PerResidueRMSDMetric

pyrosetta.rosetta.core.simple_metrics.per_residue_metrics.SidechainNeighborCountMetric

pyrosetta.rosetta.core.simple_metrics.per_residue_metrics.WaterMediatedHbondMetric

Set BuriedUnsatHBond preset

It would be great to have a preset that automatically shows buried unsatisfied hydrogen bonds using the UnsatSelector residue selector, or wrapping the BuriedUnsatHbonds filter to produce a residue selector that can be visualized.

demo notebook in PyRosetta.notebooks

Hi Jason! I just noticed that py3Dmol can now used in Colab notebook (example code below) and it works! Would it be possible to add add recommended workflow into (new?) PyRosetta.notebooks notebook?
Thanks,

import pyrosetta;
import pyrosetta.distributed.io as io
import py3Dmol

pyrosetta.init()
pose = pyrosetta.pose_from_sequence('TESTTHISEPICLIFE')

view = py3Dmol.view(width=500, height=500)
view.addModel(io.to_pdbstring(pose),'pdb')
view.setStyle({'model': 0}, {"cartoon": {'color': 'red'}})
view.addStyle({'model': 0}, {"stick": True})
view.zoomTo()
view.show()