Citation | Installation | Example | Usage | Command line | API doc | Interface classes | Website | Acknowledgment
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, biopython, cctbx, pyrosetta, schrodinger's Structure
Should work with Python 3. If you experience problems, please file an issue.
Ask question about usage? Please post here
Available on conda-forge channel
conda install nglview -c conda-forge
Available on PyPI
pip install nglview
Jupyterlab: nglview works best with jupyterlab >= 3.0 and no further steps needed.
Known to work versions
| nglview | lab | notebook | ipywidgets | Known issue(s) | VSCode |
|---|---|---|---|---|---|
| 3.1.0 | 4.0.10 | 7.0.6 | 8.1.1 | HTML embed doesn't work | No |
| 3.0.8 | 4.0.10 | 7.0.6 | 8.1.1 | show_pdbid doesn't work | Yes |
If you are using notebook v5.0, you need to increase the iopub_data_rate_limit
to visualize big structure (e.g: solvated system)
jupyter notebook --NotebookApp.iopub_data_rate_limit=10000000
Requirement: ipywidgets >= 7.0, notebook >= 4.2
The development version can be installed directly from github:
git clone https://github.com/arose/nglview
cd nglview
python setup.py install
# if you edit files in ./js folder, make sure to rebuild the code
cd js
npm install
# probably need to activate widgetsnbextension
# python -m ipykernel install --sys-prefix
# jupyter nbextension enable --py --sys-prefix widgetsnbextension
# jupyter nbextension enable --py --sys-prefix nglview
# tested with ipywidgets 5.2.2, notebook 4.2.1
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, biopython.
| Function | Description |
|---|---|
show_file(path) | Shows any NGL supported file formats (pdb, gro, mol2, sdf, dx, ..) 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_asetraj(traj) | Shows ase trajectory traj |
show_pymatgen(struct) | Shows pymatgen Structure |
show_htmd(mol) | Shows HTMD Molecules |
show_biopython(mol) | Shows Biopython structural entities |
show_iotbx(mol) | Shows cctbx's iotbx structure |
show_rosetta(pose) | Shows pyrosetta's Pose |
show_iodata(obj) | Shows iodata's IOData |
show_psi4(obj) | Shows psi4's Molecule |
show_qcelemental | Shows QCelementary's Molecule |
show_openbabel | Shows openbabel's OMol |
show_prody | Shows prody's Ensemble or AtomGroup |
view.add_representation('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)
# Not using default representation
view = nv.show_file('your.pdb', default=False)
view.center()
view.add_rope()
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
# set the frame number
view.frame = 100
# parameters for the NGL stage object
view.stage.set_parameters(**{
# "percentages, "dist" is distance to 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'
# 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[0].add_cartoon(...) # equal to view.add_cartoon(component=0)
view[1].add_licorice(...) # equal to view.add_licorice(component=1)
# 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.
# coot mouse style (https://en.wikipedia.org/wiki/Coot_(software))
view.stage.set_parameters(mouse_preset='coot')
Require: moviepy (pip install moviepy)
from nglview.contrib.movie import MovieMaker
movie = MovieMaker(view, output='my.gif', in_memory=True)
movie.make()
# 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`
nglview myscript.py
# 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
# specify web browser
nglview my.pdb --browser=google-chrome
(Feel free to make a PR to add/remove your project here. Thanks.)
nglview contributorsoceans16 themeIf you would like to acknowledge our work, feel free to cite:
Hai Nguyen, David A Case, Alexander S Rose; NGLview - Interactive molecular graphics for Jupyter notebooks, Bioinformatics, , btx789, https://doi.org/10.1093/bioinformatics/btx789
Generally MIT, see the LICENSE file for details.
FAQs
IPython widget to interactively view molecular structures and trajectories.
We found that nglview demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.