WebChem Viewer Video Tutorial

Sharing lists of molecular structures with associated chemical properties is a common task in computer-aided drug design and medicinal chemistry. WebChem Viewer is a simple, free, open-source program that generates HTML-formatted output that can be viewed in any modern web browser, on any operating system (including mobile), without requiring the installation of additional software. The output can also be easily incorporated into existing web pages. WebChem Viewer is released under the FreeBSD license can be downloaded from SourceForge. It was created by Jacob Durrant, a post-doc in the lab of Rommie E. Amaro.

In addition to the video tutorial posted above, there are also written tutorials for both WebChem Viewer and the associated Smiley2png Opal service.

How to Run


WebChem Viewer should work on any operating system with Python/TKinter installed. Fortunately, Python comes installed by default on most Linux and Mac OSX systems. A version for Windows can be downloaded from the official Python website.

Users can launch the program by clicking on the WebChemViewer.LINUX executable script in Linux, the WebChemViewer.MacOSX Automator application in OSX, or the WebChemViewer.Windows.bat batch file in Windows. Advanced users can launch WebChem Viewer from the command line (i.e., "python").

Program Input


WebChem Viewer accepts two types of tabular input files: 1) comma separated values (CSV, e.g., the format used by Microsoft Excel), and 2) tab delimited. The first row of the input file must contain column labels, and subsequent rows must contain data in the same order. Each row represents a single molecule; row entries might include any molecule-associated data, such as the molecular name, weight, SMILES string, or a docking score.

Example of the CSV format:

ID Number,SMILES,Docking,Source,Synthesis Method
PLZKL-OMM-71287,c1ccccc1,-5.2,"Pilzukil, Pharmaceuticals",Click Chemistry
PLZKL-OMM-67790,CCOC,-9.3,Owen Moore Monet Pharma,Natural Product

Example of the tab-delimited format:

ID Number	SMILES	Docking	Source Company 	Synthesis Method
PLZKL-OMM-71287	c1cccc1	-5.2	Pilzukil Pharm	Click Chemistry
PLZKL-OMM-67790	CCOC	-9.3	OwenMonet Drug	Natural Product
The WebChem Viewer GUI Interface

Input Description

Next, the user must indicate which of the data columns contains SMILES strings, from which 2D representations of each molecule are ultimately generated, with stereochemistry indicated when appropriate. The user next indicates which column to use to initially sort the data, either in ascending or descending order. Finally, the user can specify which columns to initially hide.

Program Output

WebChem Viewer output is HTML formatted and so can be viewed in any modern web browser, on any computer operating system, including mobile. The user can choose to create a single HTML file with all the required dependencies embedded directly into the code (perfect for simple sharing), or the user can choose to save the HTML file and all dependencies as separate files in a directory.



Two-dimensional representations of the molecular structures are generated from the SMILES strings using the free programs Open Babel and the accompanying Cario 2D graphics library. Note that these programs are required dependencies for those using the WebChem-Viewer program, but not for those viewing the program’s HTML output. All the required HTML-output dependencies (JQuery and DataTables) are embedded in the output itself, so that the output can be viewed in any modern web browser without requiring additional plugins or programs.

Command-Line Parameters


For the user's convenience, WebChem Viewer provides a Tkinter-dependent graphical user interface. If Tkinter isn't installed or if the user wishes to run WebChem Viewer on a system without a graphical interface (e.g., a remote web server), the program can also be run using a command-line interface. The command-line parameters are:

WebChem Viewer 1.0
Copyright (c) 2013, Jacob D. Durrant. All rights reserved.

Running WebChem Viewer in command-line mode.
(Note that the viewer provides a GUI if Tkinter is installed.)

Use the --help parameter to learn about the available command-line options.

--csv_file: The location of the CSV containing your data, including
      SMILES-string data. The first line of this file must be a
      header. Example: --csv_file simple_data_example.tabbed.dat
--csv_type: Use 'tab' if your data is not quoted and is separated by
      tabs (e.g., the kind of output produced by the Linux paste
      command). Use 'comma' if your data is quoted and separated by
      commas (e.g., the kind of output Microsoft Excel produces).
      Example: --csv_type tab

Data Description
--smiles_column_index: The number of the column containing the SMILES
      strings, from which images of the molecular structures are
      generated. Note that the left most column is column 0, not
      column 1. Example: --smiles_column_index 1
--sort_column_index: The number of the column that will be initially
      sorted (e.g., a column containing a docking score). Note that
      the left most column is column 0, not column 1. Example:
      --sort_column_index 2
--sort_type: Use 'asc' to sort the initial column in ascending order.
      Use 'desc' to sort it in descending order. Example: --sort_type
--columns_to_hide_initially: The numbers of the columns that will be
      initially hidden, separated by spaces. Note that this list must
      be placed in quotes from the command line. Recall that the left
      most column is column 0, not column 1. Example:
      --columns_to_hide_initially "3 4 1"

Text or GUI Interface
--textmode: Incluse this command-line parameter to run the program in
      text mode, rather than with a GUI. If Tkinter is not installed
      on your system, WebChem Viewer defaults to a text interface.
      Example: --textmode

--images_and_javascript_embedded: Use 'TRUE' to embed all javascript
      files, css files, and images into a single html file. This
      option is ideal for sharing with colleagues. Use "FALSE" to save
      all dependent files separately in an output directory. This
      option is ideal for someone who wishes to post the output to the
      internet and would like to be able to easily edit the files.
      Example: --images_and_javascript_embedded TRUE
--output_destination: If --images_and_javascript_embedded is 'TRUE',
      this parameter specifies the location of the single output html
      file. If --images_and_javascript_embedded is 'FALSE', this
      parameter specifies the name of the (new) directory where multi-
      file output will be saved. Example:
      --images_and_javascript_embedded TRUE --output_destination

Open Babel
--babel_executable_location: WebChem Viewer uses Open Babel
      ( for conversions and image generation. This
      parameter specifies the location of the babel executable (e.g.,
      'babel' or 'babel.exe'). Example: --babel_executable_location
--obabel_executable_location: WebChem Viewer uses Open Babel
      ( for conversions and image generation. This
      parameter specifies the location of the obabel executable (e.g.,
      'obabel' or 'obabel.exe'). Example: --obabel_executable_location


python --csv_file simple_data_example.tabbed.dat
      --csv_type tab --smiles_column_index 1 --sort_column_index 2
      --sort_type asc --images_and_javascript_embedded TRUE
      --output_destination simple_data_example.tabbed.dat.html
      --babel_executable_location /usr/local/bin/babel
      --obabel_executable_location /usr/local/bin/obabel
      --columns_to_hide_initially "3 4 1" --textmode