IPython widget to interactively view molecular structures and trajectories.
Project description
![nglview](nglview.png)
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/).
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](https://github.com/arose/nglview/issues).
Table of contents
=================
* [Installation](#installation)
* [Usage](#Usage)
* [Interface classes](#Interface classes)
* [Changelog](#changelog)
* [License](#license)
Installation
============
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
Usage
=====
Open a notebook
ipython notebook
and issue
```Python
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](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/).
| 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_mdanalysis(univ)` | Shows `MDAnalysis` Universe or AtomGroup `univ` |
Structures
----------
The above convenience functions first create an `adaptor` that implements an [interface](#Interface classes) for communication with the IPython/Jupyter widget.
```Python
import nglview
struc = nglview.PdbIdStructure("3pqr") # load file from RCSB PDB
w = nglview.NGLWidget(struc) # create widget
w # display widget
```
Trajectories
------------
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`](https://github.com/arose/simpletraj)
package):
```Python
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](http://mdtraj.org/):
```Python
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`:
```Python
w.frame = 100 # set to frame no 100
```
Representations
---------------
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](http://arose.github.io/ngl/doc).
```Python
w.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"
}}
]
nglview.NGLWidget(struc, representation=initial_repr)
```
Additionally representations can be added with the `add_representation` method:
```Python
w.add_representation(
"cartoon", selection="protein", color="residueindex"
)
```
Adaptors
--------
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.
| Class | Description | Interface |
|------------------------------|---------------------------------------------------|-----------|
| `FileStructure(path)` | Loads `path` from filesystem | S |
| `PdbIdStructure(pdbid)` | Fetches `pdbid` from RCSB PDB | S |
| `SimpletrajTrajectory(path)` | Uses `simpletraj` to access trajectory at `path` | T |
| `MDTrajTrajectory(traj)` | Wraps `MDTraj` trajectory `traj` | S and T |
| `PyTrajTrajectory(traj)` | Wraps `PyTraj` trajectory `traj` | S and T |
| `MDAnalysisTrajectory(univ)` | Wraps `MDAnalysis` Universe or AtomGroup `univ` | S and T |
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
===
NGLWidget
---------
### Constructor
```Python
ngl_widget = NGLWidget(structure, trajectory=None, representations=None)
```
### Properties
```Python
# set the frame number
ngl_widget.frame = 100
```
```Python
# list of representations
ngl_widget.representations = [{"type": "cartoon"}]
```
```Python
# 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
}
```
### Methods
```Python
ngl_widget.add_representation("cartoon", **kwds)
```
Interface classes
=================
You can create your own adaptors simply by following the interfaces for `Structure` and `Trajectory`, which can also be combined into a single class.
Structure
---------
```Python
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"
```
Trajectory
----------
```Python
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
```
Combined
--------
```Python
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
```
Changelog
=========
Version 0.4
-----------
* 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
Version 0.3
-----------
[![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.44700.svg)](http://dx.doi.org/10.5281/zenodo.44700)
* 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`
Version 0.2
-----------
[![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.44698.svg)](http://dx.doi.org/10.5281/zenodo.44698)
* 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
Older versions
--------------
For changes in older versions please see the [CHANGELOG](CHANGELOG.md) file.
License
=======
Generally MIT, see the LICENSE file for details.
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/).
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](https://github.com/arose/nglview/issues).
Table of contents
=================
* [Installation](#installation)
* [Usage](#Usage)
* [Interface classes](#Interface classes)
* [Changelog](#changelog)
* [License](#license)
Installation
============
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
Usage
=====
Open a notebook
ipython notebook
and issue
```Python
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](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/).
| 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_mdanalysis(univ)` | Shows `MDAnalysis` Universe or AtomGroup `univ` |
Structures
----------
The above convenience functions first create an `adaptor` that implements an [interface](#Interface classes) for communication with the IPython/Jupyter widget.
```Python
import nglview
struc = nglview.PdbIdStructure("3pqr") # load file from RCSB PDB
w = nglview.NGLWidget(struc) # create widget
w # display widget
```
Trajectories
------------
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`](https://github.com/arose/simpletraj)
package):
```Python
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](http://mdtraj.org/):
```Python
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`:
```Python
w.frame = 100 # set to frame no 100
```
Representations
---------------
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](http://arose.github.io/ngl/doc).
```Python
w.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"
}}
]
nglview.NGLWidget(struc, representation=initial_repr)
```
Additionally representations can be added with the `add_representation` method:
```Python
w.add_representation(
"cartoon", selection="protein", color="residueindex"
)
```
Adaptors
--------
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.
| Class | Description | Interface |
|------------------------------|---------------------------------------------------|-----------|
| `FileStructure(path)` | Loads `path` from filesystem | S |
| `PdbIdStructure(pdbid)` | Fetches `pdbid` from RCSB PDB | S |
| `SimpletrajTrajectory(path)` | Uses `simpletraj` to access trajectory at `path` | T |
| `MDTrajTrajectory(traj)` | Wraps `MDTraj` trajectory `traj` | S and T |
| `PyTrajTrajectory(traj)` | Wraps `PyTraj` trajectory `traj` | S and T |
| `MDAnalysisTrajectory(univ)` | Wraps `MDAnalysis` Universe or AtomGroup `univ` | S and T |
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
===
NGLWidget
---------
### Constructor
```Python
ngl_widget = NGLWidget(structure, trajectory=None, representations=None)
```
### Properties
```Python
# set the frame number
ngl_widget.frame = 100
```
```Python
# list of representations
ngl_widget.representations = [{"type": "cartoon"}]
```
```Python
# 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
}
```
### Methods
```Python
ngl_widget.add_representation("cartoon", **kwds)
```
Interface classes
=================
You can create your own adaptors simply by following the interfaces for `Structure` and `Trajectory`, which can also be combined into a single class.
Structure
---------
```Python
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"
```
Trajectory
----------
```Python
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
```
Combined
--------
```Python
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
```
Changelog
=========
Version 0.4
-----------
* 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
Version 0.3
-----------
[![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.44700.svg)](http://dx.doi.org/10.5281/zenodo.44700)
* 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`
Version 0.2
-----------
[![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.44698.svg)](http://dx.doi.org/10.5281/zenodo.44698)
* 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
Older versions
--------------
For changes in older versions please see the [CHANGELOG](CHANGELOG.md) file.
License
=======
Generally MIT, see the LICENSE file for details.
Project details
Release history Release notifications | RSS feed
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.4.tar.gz
(3.6 MB
view hashes)