IPython widget to interactively view molecular structures and trajectories
Jupyter Notebook JavaScript Other
Latest commit 0f6b69d Jan 21, 2017 @hainm hainm committed on GitHub Doc test: nglview.show module (#568)
* add test_docs.py

* doctest: nglview.show

* only do doctest for PY3
Permalink
Failed to load latest commit information.
.github Update ISSUE_TEMPLATE.md Dec 6, 2016
devtools try to build conda recipe after finish all the tests (#548) Dec 6, 2016
doc Update interface_classes.md Aug 23, 2016
examples ASE user example (#560) Jan 10, 2017
js delay setting parameters (#555) Jan 8, 2017
nglview Doc test: nglview.show module (#568) Jan 22, 2017
.coveragerc [WIP] using base64 to encode numpy array to send to JS (#67) Apr 29, 2016
.gitattributes [setup|package] added versioneer to extract version numbers from git … Feb 23, 2016
.gitignore WIP: Fixes & tweaks (#264) Jun 13, 2016
.travis.yml try to build conda recipe after finish all the tests (#548) Dec 6, 2016
CHANGELOG.md Update CHANGELOG.md Jul 30, 2016
DEVELOPMENT.md Update DEVELOPMENT.md Oct 7, 2016
Dockerfile docker (#553) Dec 29, 2016
LICENSE initial commit Nov 9, 2015
MANIFEST.in include lab Nov 27, 2016
README.md setup (update author (add Hai Nguyen)) + link to contributors (#558) Jan 9, 2017
circle.yml Circle - docker build (#528) Nov 22, 2016
nglview.gif improve gif quality for README (#242) Jun 4, 2016
nglview.png Update readme: png file (#129) May 8, 2016
nightwatch.json update selenium version to work with both firefox and chrome (#234) Jun 3, 2016
setup.cfg [versioning] fix updating of _version.py for sdist/build_py commands;… Jan 9, 2017
setup.py setup (update author (add Hai Nguyen)) + link to contributors (#558) Jan 9, 2017
versioneer.py [versioning] fix updating of _version.py for sdist/build_py commands;… Jan 9, 2017

README.md

Installation | Example | Usage | Command line | API doc | Interface classes | Website | GUI | Acknowledgment

Binder DOI Build Status bioconda-badge Coverage Status

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, ParmEd, rdkit, ase, HTMD

Should work with Python 2 and 3. If you experience problems, please file an issue.

membrane

Table of contents

Installation

Released version

Note: The released version only works with ipywidgets >= 5.2.2. This version will not work with JupyterLab.

  • Available on bioconda channel

    conda config --add channels conda-forge
    conda install nglview -c bioconda
    # might need: jupyter-nbextension enable nglview --py --user
    
    # if you already installed nglview, you can `upgrade`
    conda upgrade nglview --force
    # might need: jupyter-nbextension enable nglview --py --user
  • Available on PyPI

    pip install nglview

Development version

Requirement: ipywidgets >= 5.2.2, notebook >= 4.2

The development version can be installed directly from github:

notebook user

    git clone https://github.com/arose/nglview
    cd nglview
    python setup.py install

    # if you edit files in ./js folder, make sure to add --npm flag (require npm)
    python setup.py install --npm

    # probably need to activate widgetsnbextension
    # python -m ipykernel install --user
    # jupyter nbextension enable --py --user widgetsnbextension
    # jupyter nbextension enable --py --user nglview

    # tested with ipywidgets 5.2.2, notebook 4.2.1

jupyterlab user

Note: jupyterlab is in its alpha version, so the instruction below might or might now work. Make sure to install development versions of ipywidgets, jupyterlab. Please see their corresponding websites for further information.

Next, install nglview

sh devtools/install-dev.sh

Docker user

  • First, run
docker run -it -p 8888:8888 hainm/nglview
  • Then open web browser, paste
localhost:8888

How does nglview look like in jupyterlab?

Example

Showcase from users

Please check user examples. Feel free to contribute.

Usage

Open a notebook

jupyter notebook

and issue

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

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, ParmEd, rdkit, HTMD.

Function Description
show_structure_file(path) Shows structure (pdb, gro, mol2, sdf) in path
show_pdbid(pdbid) Shows pdbid fetched from RCSB PDB
show_simpletraj(struc_path, traj_path) Shows structure & trajectory loaded with simpletraj
show_mdtraj(traj) Shows MDTraj trajectory traj
show_pytraj(traj) Shows PyTraj trajectory traj
show_parmed(structure) Shows ParmEd structure
show_mdanalysis(univ) Shows MDAnalysis Universe or AtomGroup univ
show_rdkit(mol) Shows rdkit rdkit.Chem.rdchem.Mol
show_ase(atoms) Shows ase Atoms
show_htmd(mol) Shows HTMD Molecules

API

Representations

view.add_representation(repr_type='cartoon', selection='protein')

# or shorter
view.add_cartoon(selection="protein")
view.add_surface(selection="protein", opacity=0.3)

# specify color
view.add_cartoon(selection="protein", color='blue')

# specify residue
view.add_licorice('ALA, GLU')

# clear representations
view.clear_representations()

# update parameters for ALL cartoons of component 0 (default)
view.update_cartoon(opacity=0.4, component=0)

# remove ALL cartoons of component 0 (default)
view.remove_cartoon(opacity=0.4, component=0)

And many more, please check NGL website

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

view.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"
    }}
]

view = nglview.NGLWidget(struc, representation=initial_repr)
view

Properties

# set the frame number
view.frame = 100
# parameters for the NGL stage object
view.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,
    # background color
    "backgroundColor": "black",
}

# note: NGLView accepts both origin camel NGL keywords (e.g. "clipNear")
# and snake keywords (e.g "clip_near")
# parameters to control the `delay` between snapshots
# change `step` to play forward (positive value) or backward (negative value)
# note: experimental code
view.player.parameters = dict(delay=0.04, step=-1)
# update camera type
view.camera = 'orthographic'
# change background color
view.background = 'black'

Trajectory

# adding new trajectory
view.add_trajectory(traj)
# traj could be a `pytraj.Trajectory`, `mdtraj.Trajectory`, `MDAnalysis.Universe`, 
# `parmed.Structure`, `htmd.Molecule` or derived class of `nglview.Trajectory`

# change representation
view.trajectory_0.add_cartoon(...) # equal to view.add_cartoon(component=0)
view.trajectory_1.add_licorice(...) # equal to view.add_licorice(component=1)

Add extra component

# Density volumes (MRC/MAP/CCP4, DX/DXBIN, CUBE)
# Or adding derived class of `nglview.Structure`
view.add_component('my.ccp4')

# add component from url
view.add_component('rcsb://1tsu.pdb')
# NOTE: Trajectory is a special case of component.

Display more than two widgets

# 1st cell
import ipywidgets
vbox = ipywidgets.VBox([view1, view2])
vbox # display

# 2nd cell
view1.sync_view()
view2.sync_view()

Show GUI

Notes: Unstable feature. See also

Movie making

Notes: Unstable feature.

from nglview.contrib.movie import MovieMaker
movie = MovieMaker(view, output='my.gif')
movie.make()

API doc

Command line

# open a notebook and import nglview
nglview 

# Require installing pytraj (PR for other backends is welcome)
# open notebook, load `my.pdb` to pytraj's trajectory then display `view`
nglview my.pdb

# load density data
nglview my.ccp4

# open notebook, create trajectory with given topology `my.parm7` and trajecotry file `traj.nc`,
# then display `view`
nglview my.parm7 -c traj.nc

# load all trajectories with filename ending with 'nc'
# make sure to use quote " "
nglview my.parm7 -c "*.nc"

# open notebook, copy content from `myscript.py` then execute it
nglview myscript.py

# open notebook and execute 1st cell
nglview mynotebook.ipynb

# create a remote notebook
# just follow its instruction
nglview my.pdb --remote
nglview my.parm7 -c traj.nc --remote
nglview mynotebook.ipynb --remote

# demo (don't need pytraj)
nglview demo

# disable autorun the 1st cell of the notebook
nglview my.pdb --disable-autorun

# specify web browser
nglview my.pdb --browser=google-chrome

FAQ

Q&A

Website

Projects using NGLView

(Feel free to make a PR to add/remove your project here)

  • AMBER - A package of programs for molecular dynamics simulations of proteins and nucleic acids
  • mbuild - A hierarchical, component based molecule builder
  • deepchem - Deep-learning models for Drug Discovery and Quantum Chemistry
  • pychimera - Use UCSF Chimera Python API in a standard interpreter
  • htmd - High throughput molecular dynamics simulations
  • https://github.com/kbsezginel/Moleidoscope - Molecular kaleidoscope

Acknowledgment

  • Funding: Hai Nguyen is supported by NIH Grant GM103297, "The Center for HIV RNA Studies" (2015 to 02-2017).
  • Many thanks to nglview contributors
  • dunovank/jupyter-themes: for oceans16 theme

License

Generally MIT, see the LICENSE file for details.