Skip to main content

IPython widget to interactively view molecular structures and trajectories.

Project description


[![Binder](http://mybinder.org/images/logo.svg)](http://mybinder.org/repo/hainm/nglview-notebooks)
[![DOI](https://zenodo.org/badge/11846/arose/nglview.svg)](https://zenodo.org/badge/latestdoi/11846/arose/nglview)
[![Build Status](https://travis-ci.org/arose/nglview.svg?branch=master)](https://travis-ci.org/arose/nglview)
[![bioconda-badge](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat-square)](http://bioconda.github.io)
![membrane](examples/images/membrane.gif)

An [IPython/Jupyter](http://jupyter.org/) widget to interactively view molecular structures and trajectories. Utilizes the embeddable [NGL Viewer](https://github.com/arose/ngl) for rendering. Support for showing data from the file-system, [RCSB PDB](http:www.rcsb.org), [simpletraj](https://github.com/arose/simpletraj) and from objects of analysis libraries [mdtraj](http://mdtraj.org/), [pytraj](http://amber-md.github.io/pytraj/latest/index.html), [mdanalysis](http://www.mdanalysis.org/).

Should work with Python 2 and 3. If you experience problems, please file an [issue](https://github.com/arose/nglview/issues).

![nglview](nglview.gif)


Table of contents
=================

* [Installation](#installation)
* [Example](#example)
* [Usage](#usage)
* [Command line](#command-line)
* [Interface classes](doc/interface_classes.md)
* [Changelog](CHANGELOG.md)
* [FAQ](#faq)
* [License](#license)


Installation
============

Released version
----------------

- Available on `bioconda` channel

`conda install nglview -c bioconda`

- Available on [PyPI](https://pypi.python.org/pypi/nglview/)

`pip install nglview`

Development version
-------------------

The development version can be installed directly from github:

git clone https://github.com/arose/nglview
cd nglview
python -m pip install .

If for any reasons that the `widget` is not shown, try reinstall below packages

conda install traitlets=4.2.1 ipywidgets==4.1.1 notebook=4.1.0


Example
=======

Please see our [Jupyter notebook examples](./examples/README.md)

Usage
=====

Open a notebook

jupyter notebook

and issue

```Python
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](http:www.rcsb.org), [simpletraj](https://github.com/arose/simpletraj) and from objects of analysis libraries [mdtraj](http://mdtraj.org/), [pytraj](http://amber-md.github.io/pytraj/latest/index.html), [mdanalysis](http://www.mdanalysis.org/), [ParmEd](http://parmed.github.io/ParmEd/).

| 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` |


API
===

Representations
---------------

```python
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()
...
```

And many more, please check [Selection language](http://arose.github.io/ngl/doc/#User_manual/Usage/Selection_language)

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](http://arose.github.io/ngl/doc).

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

The widget constructor also accepts a `representation` argument:

```Python
initial_repr = [
{"type": "cartoon", "params": {
"sele": "protein", "color": "sstruc"
}}
]

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


Properties
----------

```Python
# set the frame number
view.frame = 100
```

```Python
# 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")
```

```python
# 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)
```

```python
# update camera type
view.camera = 'orthographic'
```

```python
# change background color
view.background = 'black'
```
Trajectory
----------

```python
# adding new one
view.add_trajectory(traj)

# traj could be `pytraj.Trajectory`, `mdtraj.Trajectory`, `MDAnalysis.Universe`, `parmed.Structure`
# change representation
view.trajectory_0.add_cartoon(...)
view.trajectory_1.add_licorice(...)
```

Add extra component
-------------------

```python
# Density volumes (MRC/MAP/CCP4, DX/DXBIN, CUBE)
view.add_component('my.ccp4')

# NOTE: Trajectory is a special case of component.
```
Multiple widgets
----------------

You can have multiple widgets per notebook cell:

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

API doc
-------
[Please check here](http://arose.github.io/nglview/latest/api.html)

Command line
============

```bash
# highly experimental code and very buggy, require installing pytraj.

# open notebook, load `my.pdb` to pytraj's trajectory then display `view`
nglview my.pdb

# 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
```

FAQ
===

[Q&A](https://github.com/arose/nglview/wiki/Q&A)

License
=======

Generally MIT, see the LICENSE file for details.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nglview-0.5.2a0.tar.gz (3.6 MB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page