An IPython/Jupyter widget to interactively view molecular structures and trajectories. Utilizes the embeddable NGL Viewer for rendering. Support for showing data from the file-system, RCSB PDB, simpletraj and from objects of analysis libraries mdtraj, pytraj, mdanalysis.

Work in progress but usable. Please contact us if you want to take part. Should work with Python 2 and 3. If you experience problems, please file an issue.

• Installation
• Usage
• [Interface classes](#Interface classes)
• Changelog
• License

From PyPI:

pip install nglview

Note: The above will try to install jupyter as a dependency. If that fails install it manually pip install jupyter.

From Conda

conda install -c omnia nglview

Open a notebook

ipython notebook

and issue

import nglview
show_pdbid("3pqr")  # load "3pqr" from RCSB PDB and display viewer widget

A number of convenience functions are available to quickly display data from the file-system, RCSB PDB, simpletraj and from objects of analysis libraries mdtraj, pytraj, mdanalysis.

The above convenience functions first create an adaptor that implements an [interface](#Interface classes) for communication with the IPython/Jupyter widget.

import nglview
struc = nglview.PdbIdStructure("3pqr")  # load file from RCSB PDB
w = nglview.NGLWidget(struc)            # create widget
w                                       # display widget

To enable trajectory access pass a second Trajectory argument to the widget constructor or supply a combined Structure/Trajectory object as the first argument.

Seperate Structure and Trajectory objects using FileStructure and SimpletrajStructure (requires the simpletraj package):

import nglview
struc = nglview.FileStructure(nglview.datafiles.GRO)
traj = nglview.SimpletrajStructure(nglview.datafiles.XTC)
nglview.NGLWidget(struc, traj)

Combined Structure/Trajectory object utilizing MDTrajTrajectory which wraps a trajectory loaded with MDTraj:

import nglview
import mdtraj
traj = mdtraj.load(nglview.datafiles.XTC, top=nglview.datafiles.GRO)
strucTraj = nglview.MDTrajTrajectory(traj)
nglview.NGLWidget(strucTraj)

The displayed frame can be changed by setting the frame property of the widget instance w:

w.frame = 100  # set to frame no 100

Representations can be changed by overwriting the representations property of the widget instance w. The available type and params are described in the NGL Viewer documentation.

w.representations = [
    {"type": "cartoon", "params": {
        "sele": "protein", "color": "residueindex"
    }},
    {"type": "ball+stick", "params": {
        "sele": "hetero"
    }}
]

The widget constructor also accepts a representation argument:

initial_repr = [
    {"type": "cartoon", "params": {
        "sele": "protein", "color": "sstruc"
    }}
]
nglview.NGLWidget(struc, representation=initial_repr)

Additionally representations can be added with the add_representation method:

w.add_representation(
    "cartoon", selection="protein", color="residueindex"
)

A number of adaptor classes are available to make structures and trajectories available to the widget. They can support either the Structure (S) or the Trajectory (T) interface as well as both combined.

You can have multiple widgets per notebook cell:

from ipywidgets.widgets import Box
w1 = NGLWidget(...)
w2 = NGLWidget(...)
Box(children=(w1,w2))

ngl_widget = NGLWidget(structure, trajectory=None, representations=None)

# set the frame number
ngl_widget.frame = 100

# list of representations
ngl_widget.representations = [{"type": "cartoon"}]

# parameters for the NGL stage object
ngl_widget.parameters = {
    # "percentages, "dist" is distance too camera in Angstrom
    "clipNear": 0, "clipFar": 100, "clipDist": 10,
    # percentages, start of fog and where on full effect
    "fogNear": 0, "fogFar": 100
}

ngl_widget.add_representation("cartoon", **kwds)

You can create your own adaptors simply by following the interfaces for Structure and Trajectory, which can also be combined into a single class.

class MyStructure(nglview.Structure):
    ext = "pdb"  # or gro, cif, mol2, sdf
    params = {}  # loading options passed to NGL
    def get_structure_string(self):
        return "structure in the self.ext format"

class MyTrajectory(nglview.Trajectory):
    def get_coordinates_list( self, index ):
        # return list of coordinates in Angstrom for the frame at the given index
        return [x1, y1, z1, x2, y2, z2]
    def get_frame_count(self):
        return 2  # return number of frames

class MyStructureTrajectory(nglview.Structure, nglview.Trajectory):
    ext = "pdb"  # or gro, cif, mol2, sdf
    params = {}  # loading options passed to NGL
    def get_structure_string(self):
        return "structure in the self.ext format"
    def get_coordinates_list( self, index ):
        # return list of coordinates in Angstrom for the frame at the given index
        return [x1, y1, z1, x2, y2, z2]
    def get_frame_count( self ):
        return 2  # return number of frames

• ADD: Convenience methods to show widget from various sources
• ADD: PyTrajTrajectory adaptor
• ADD: MDAnalysisTrajectory adaptor
• ADD: NGLWidget.add_representation() method
• ADD: append a "WebGL not supported message" to widget if so
• ADD: parameters widget property, passed to NGL stage object
• ADD: params property for Structure, dict passed to NGL
• CODE: be less noisy when importing nglview
• DOC: more usage examples, API description
• DOC: added CHANGELOG file
• BUILD: added example files in the package

• MIGRATION: Trajectory classes need get_frame_count method
• MIGRATION: removed set_frame method use new frame property
• ADD: simple trajectory player
• ADD: widget resizing support
• ADD: picking support (gui info; picked property)
• CODE: check for file existence in FileStructure and SimpletrajTrajectory

• MIGRATION: changed get_string to get_structure_string
• MIGRATION: changed get_coordinates to get_coordinates_list
• DOC: usage, interface classes
• ADD: MDTrajTrajectory adaptor
• CODE: added interface classes
• CODE: suggested packages; mdtraj, simpletraj

For changes in older versions please see the CHANGELOG file.

Generally MIT, see the LICENSE file for details.