HTMoL

Next-generation Molecular Dynamics Web Visualization


Molecular Dynamics (MD) is used in many fields of science. The visualization on the right is not a movie, it is the interactive display of actual atomic space and time dependent data of a protein generated with MD. In the example, the N- and C- terminals are shown in magenta and yellow, respectively. All the residues of type TRP are highlighted using the VDW representation. By visualizing the MD trajectory, it is clear how the residue exposed to the solvent has a much higher movility than those residues buried in the hydrophobic core of the protein. More specific details of the system and simulation can be viewed by clicking the "MD" button on the lower right corner.

HTMoL is a light-weight full-stack plugin-free application to display the three-dimensional structure and dynamics of biomolecules. HTMoL can be used as a graphical interface to access MD data located at a high performance computing cluster where simulations are generated, or as supplementary documentation for scientific research publications as a way to readily share MD results. Developed by integrating state-of-the-art web technologies ( NodeJS + WebGL + JavaScript + HTML5 + CSS3 ), HTMoL is easy to install, configure and customize on any web-server. HTMoL can be embedded inside a web page or used full-size, and it does not require any other third-party package to be installed on the client-side. It works in all popular web browsers. Chrome or FireFox highly recommended.








When the trajectory is loaded, Play-Pause or move back and forth one frame at a time. Rotate the molecules with the mouse by click & drag, zoom in or out. Show/Hide the Main Menu by clicking on the top-left corner. If you do not see the molecule, maybe your browser does not support WebGL.

HTMoL Full-Window

HTMoL Features

Full-stack solution:

Easy to install on an internet server to deploy structural and molecular dynamics data

Easy to embed in any web page with only one line of code, the browser and the GPU will do the rest

Parses atomic coordinates in PDB format

Parses popular MD trajectory formats (Gromacs XTC, Charmm DCD)

Full and flexible control through a single configuration file

Molecular representation control through a command set

Use as a GUI to access MD data located at an HPC cluster

Works in WordPress



Developed with standards in mind:






HTMoL Installation

1 - Install Node.js

Follow directions at the Node.js site for installation on a web server.

It is easier to use a Package Manager.

2 - Install HTMoL

Clone source code from GitHub:
> git clone https://github.com/tripplab/HTMoL.git
or from npm Package Manager:
> npm i htmol
You can optionally download a copy of MD data expamples Download

3 - Configure HTMoL

HTMoL configuration is made by editing the local/config.js file. The following variables have to be set:

  • Network Variables
  • WebIP [127.0.0.1] is the servername or IP address of the web server. Use 'localhost' for testing.
    NodePort [3000] is the port number where the BinServer will be listening for requests. It can be any available port with a number greater than 1024 (lower values require root access, which is not advisable). Note, do not use port number 80 because it is usually reserved for Apache by default. Sometimes you might have to enable this port for TCP/UDP transport at the network switch/router if the server is behind a firewall.
  • Data location
  • PDBDIR [pdbfiles/] is where the atomic coordinates are located.
    TRJDIR [trjfiles/] is where the MD trajectories are located.
  • Data files
  • pdbInicial name of the file with the atomic coordinates in PDB format.
    trjInicial name of the MD trajectory file.
    trjFormat format of the MD trajectory file (Options: XTC, DCD, NC).
See an example here. Other variables can be optionally set for further configuration. See the Documentation section.

4 - Start the BinServer

At the HTMoL directory type:

> node BinServer.js
	
> HTMoL 3.5.4: BinServer started on port NodePort
If you get a mesage like "Error: listen EACCES" or "Error: listen EADDRINUSE", you might have to try a different port number (NodePort). Find one that is open and not in use by other service. A functional port depends on your server configuration, so you might have to try several numbers before finding one that works.

Now, verify that BinServer is active and listening:

> netstat -npl | grep node
	
> tcp6 0 0 :::NodePort :::* LISTEN JobID/nodejs

or

> nc -vz WebIP NodePort
	
> Connection to WebIP NodePort port [tcp/*] succeeded!

5 - Start sharing

The MD trajectory is now ready to be visualized at http://WebIP/HTMoL/HTMoL.html

6 - Optional: Embed HTMoL on a web page

For example, to embed HTMoL in http://URL_to/index.html:

Create an <iframe> element inside the body of the HTML file where you want HTMoL to be displayed. Specify the following elements:

  • URL or path to the HTMoL.html file
  • Attribute class with the value "HTMoL"
  • Attribute scrolling with the value "no"
  • Attribute dimensions of the frame
<iframe
 src="http://WebIP/HTMoL/HTMol.html"
 class="HTMoL"
 scrolling="no"
 width="600"
 height="500" ></iframe>

That's it. Also, HTMoL can be embeded in WordPress blog posts (and possibly in other blog platforms). An example can be found here.

HTMoL Documentation

Parameters and Variables

HTMoL can be further configured in the local/config.js file. The following variables can be set [default value]:

  • HPC Server
  • showOpen [false] When HTMoL is used as the interface to access MD data located at a high performance computing cluster where simulations are generated, this variable enables the option to open PDB and trajectory files from the main menu
    showDownload [true] Enable the option to download the PDB and trajectory files from the main menu

    Commands

    HTMoL has a set of commands implemented to control how the molecular system and trajectory are visualized ("select value; show value; color value; view value; zoom value;"). This structured language can be used in the commandsDefault parameter defined in the local/config.js file.

    MD Trajectory

    You may remove explicit solvent (e. g. water) and cut the trajectory file to the relevant part of the simulation where the specific events or process take place for visual clarity, decrease storage file size, and increase transfer speed.

    Also, some times it is helpful to remove high-frequency movements with a low-pass filter. However, the final trajectory file should not be used for analysis but for visualization purposes only.

    As a good practice, always provide the MD description and simulation details.

    Frequently Asked Questions

    Is HTMoL free?

    HTMoL is a free application for academic use. This includes research and teaching purposes. It is distributed with an Open Source License Agreement.

    Where do I get the source code?

    You can always find the latest version of HTMoL in GitHub.

    How does the GUI work?


    The main Menu gives access to several functionalities grouped in five categories: Files, Representations, Tools, and Views (A1). The principal info-bar indicates when the data files are being transferred, if there is a communication error, or the progress of the MD trajectory in frames, percentage, and time lapsed in pico-seconds when played (A2). The trajectory controls allow the user to play, pause, or move one frame forward or backward (A3). The secondary bar gives information on the loaded molecular structure (name and number of atoms) and trajectory data (name and number of frames), B1,2. Different molecules in the system are identified by a distinctive ChainID label, which are displayed (B3). These labels function as a switch to turn on (white label) or off (red label) the display of the corresponding molecule.

    The user can rotate the view at any time by click-and-drag with the mouse anywhere inside the application's viewport (C1). Clicking on an atom will show related information (atom's number, type, name, and X-Y-Z coordinates, and molecule's name and number) in the principal info-bar. If the simulation box is defined in the coordinates file, the computational cell can be displayed (yellow lines) along with the coordinates system (X in red, Y in green, and Z in blue lines), through the Menu-Tools-Axis\&SimBox function (C2,3). HTMoL uses a perspective camera to display the system (D1). The user can zoom the view in or out through the corresponding control buttons (D2).


    The back-end-user (server admin) can provide information on the molecular system and the MD simulation protocol details. These are defined in the back-end's configuration file. The front-end-user can access the information set without disrupting the display view by clicking on the MD-button. A modal-window will show all the information set in the configuration file under the MDTitle and MDdescription parameters (A1). A common action is to measure the distance between two atoms or the angle defined by three atoms. HTMoL provides this function through the Menu-Tools-Measures (A2). Once selected, the front-end-user can click on two atoms to display the distance, or three atoms to display the angle. The selected atoms will be highlighted in green (B1,2). The measured value will be displayed and updated on every MD frame as the trajectory is played.

    HTMoL implements a non-deterministic finite automaton to make atom selections by a set of commands parsed through a syntactic analyzer. The selection can then be modified by a variety of visualization options through the back-end's configuration file, the Console on the Tools menu (A3), or directly on the Representations menu. These include different geometries (e. g. line or Bond, ball+stick or CPK, spacefill or VDW, and back-bone trace) and different color schemes (name or RGB values). A command set is defined in HTMoL. Hence, the back-end-user can set-up a stage which accents or highlights an important region or molecule in the system for the front-end-user to appreciate by just opening the application and playing the MD trajectory. Likewise, the front-end-user can also modify and interact with the molecular system through the Console interface when the application is on Full-window mode (C1). The Console interface is disabled when the applications is embedded on a webpage because the viewport size restrictions would make it impractical to use.

    Can I contribute?

    Sure! we always welcome new contributors for developing additional functionalities. If you are interested in contributing to the HTMoL project in any way (e.g. improving or extending code/capabilities/features, documenting, etc.) please let us know.

    How do I properly cite HTMoL?

    Proper citation is essential to continued funding for HTMoL development, as it is the primary way in which we demonstrate the value of our software to the scientific community.

    Electronic documents shall include a direct link to the official HTMoL page. Printed documents shall include a reference to the published paper:

    M. Carrillo-Tripp*, L. Alvarez-Rivera, O. I. Lara-Ramírez, F. J. Becerra-Toledo, A. Vega-Ramírez, E. Quijas-Valades, E. González-Zavala, J. C. González-Vázquez, J. García-Vieyra, N. B. Santoyo-Rivera, A. Meneses-Viveros and S. V. Chapa-Vergara.
    HTMoL: full-stack solution for remote access, visualization, and analysis of Molecular Dynamics trajectory data.
    J Comput Aided Mol Des (2018). DOI 10.1007/s10822-018-0141-y

    Thank you for your attention to these details.

    I have read all the documentation and I still have a question

    Please let us know what's the problem you're having.

    Benchmarking

    This is the data set used to characterize and compare HTMoL with similar applications. Tools are installed side-by-side in the same server, streaming the same data files. Modern browsers can measure the display frame rate and show the FPS count. In Chrome (v65) go to View-Developer-Developer Tools-Rendering-FPS meter, and in Firefox (v59) go to Tools-Web Developer-Performance-Start Recording. A new tab will open by clicking on a link, loading a specific system. To estimate the tool performance, look at the FPS while the MD dynamics are playing after one full trajectory cycle. The higher the value, the greater the performance.


    System

    # Atoms

    HTMoL

    MDsrv+NGL

    AmB

    156

    open

    open

    Lysozyme

    1,960

    open

    open

    DPPC

    3,281

    open

    open

    Enzyme

    3,549

    open

    open

    Membrane with Cholesterol

    20,258

    open

    open


    HTMoL Examples

    Ordered by system size. Click images to open full-size HTMoL in a new tab.

    Amphotericin B (AmB) dimer, monomer 1 labeled as chain A, and monomer 2 labeled as chain B.
    VDW representation. Solvent not shown.
    Low-pass filtered XTC trajectory for smooth movement (visualization purposes only).

    commandsDefault="select 0:0:A;show VDW;
    select 0:0:B;show VDW;color atom;zoom 4;"


    Lysozyme with disulfide bridges shown.
    CPK representation. Solvent not shown. Unfiltered XTC trajectory.

    commandsDefault="show cpk;select S:0:0;
    show VDW;color atom;zoom 4;"


    Three anesthetic molecules interacting with a DPPC bilayer, monomers individually labeled as chanis 1, 2, and 3.
    Phospholipid molecules labeled as chain D. Ions Na and Cl labeled as chains E and F.
    VDW and line representations. Simulation Box shown. Solvent not shown. Low-pass filtered XTC trajectory. Custom view.

    commandsDefault="select 45-66;show VDW;
    color red;select 23-44;show VDW;color green;
    select 1-22;show VDW;color white;select 0:0:E;
    show VDW;color yellow; select 0:0:F;show VDW;
    color 0.6,0.4,0.0;zoom -10;view Custom;"


    Same protein shown in the intro but in backbone representation.
    Solvent not shown. Simulation Box shown. Low-pass filtered XTC trajectory.

    commandsDefault="show trace;view UpView;
    zoom -6;"


    NaCl in water (chains B,C, and A respectively).
    Low-pass filtered XTC trajectory.

    commandsDefault="show cpk;select 0:1:A;
    color yellow;select 0:0:B;show VDW;
    color 0.59,0.23,0.93;select 0:0:C;
    show VDW;color green;zoom 6;"


    DPPC bilayer with cholesterol (chain A). Phospholipid molecules labeled as chain B.
    VDW and line representations. Simulation Box shown. Solvent not shown. Low-pass filtered DCD trajectory.

    commandsDefault="select 0:0:A;show VDW;
    color atom;zoom 2;"