.. include:: substitutions
.. _examples:

*********************
Examples
*********************

|product| ships with a large collection of example data as well as example
scripts. The examples are contained in the "examples" directory in the 
|product| installation. This directory can be directly accessed from within
|product| by selecting the "Open Examples Directory" option in the "Help" 
menu.

A fast way to get started exploring the example data and scripts is to open
the ``add_menu_updating.vpy`` script (see :ref:`Opening Files<opening_files>`) which will add 
an "Examples" menu to the main menu bar. This new menu will contain an entry
for each example data file and script provided. Selecting any one of these
options will open the associated file in the current instance of |product|.

Data
====

|product| ships with a directory of example data for the user to experiment with 
in the event that other input files are not immediately available. Included in 
this directory are:

* ``cox2_good.sdf.gz`` - This is a large set of Cox-2 inhibitors which 
  contains associated molecular data which makes this an excellent example file
  for use in the spreadsheet.

* ``MMFF94.mol2.gz`` - This is another large set of small molecules but 
  it contains a significantly greater amount of diversity among the molecules than
  the previous file. This file is an excellent example file for browsing 
  through a large data set as well as for exploring the many different ways that
  shape and chemistry may be visualized with |product|.

* ``1ll5.grd`` - This is a grid file containing electron density data 
  corresponding to crystallography data of the ligand structure found in the
  following file. It provides an excellent example of |product's| grid visualization 
  capabilities and also works well to provide a context for the associated
  ligand file.

* ``1ll5.lig.pdb.gz`` - This small molecule is a beta-lactamase 
  inhibitor positioned in its crystallographically determined binding location. 
  This file combined with the actual beta-lactamase protein found in the 
  following file provide an excellent example of how |product| can be used to 
  visualize small molecule-protein interactions. When visualizing this molecule, 
  be sure to observe the three excellent hydrogen bonds it makes with the protein.

* ``1ll5.nolig.pdb.gz`` - This file contains the crystallographically 
  determined structure of a beta-lactamase protein. Its bound inhibitor can be
  found in the previous file. This file is an excellent example of the many
  ways that proteins can be visualized in |product|. Be sure to observe its many
  internal hydrogen bonds, particularly in the active site.

* ``1ll5.omega.oeb.gz`` - This file contains a large number of 
  conformations of the beta-lactamase ligand (``1ll5.lig.pdb.gz``) generated 
  with OpenEye's conformer generation program *OMEGA*. This file is an 
  excellent example of |product's| ability to handle multi-conformer molecules as well 
  as its ability to view *OMEGA* output. It is important to note that this 
  file is not in the same coordinate space as the three previous files and as 
  such should not be expected to appear in the same location on screen with the 
  above files.

Scripts
=======

|product| ships with a large directory of example scripts to both highlight 
the many different aspects of |product's| scripting capability and to help 
guide the user to begin developing their own scripts. Each one of the 
example scripts provided will be discussed in detail in the following 
sections.  Note that not all of the example scripts will actually do anything
interesting when you load them directly into VIDA.  Many of them illustrate
the creation of useful functions, but may not actually call these functions.

The location of the example scripts is platform-specific, but can be found
from within |product| by selecting the "Open Examples Directory" option in the "Help" 
menu.


.. _add_menu.vpy:

add_menu.vpy
------------

This example shows how to add a new menu to the top level main menu (if it
does not already exist). Note that the call to ``MenuAddSubmenu`` returns
the menu name to be used to reference that menu in subsequent functions.
It is important to use the returned name to avoid potential naming clashes
when accessing the menu.

.. oe:source:: add_menu.vpy
   :frag:     ADD_MENU
   
Once the top level menu has been created, this example shows how to add 
submenus to the newly created menu.

.. oe:source:: add_menu.vpy
   :frag:     ADD_SUBMENUS
   
Lastly, this example details how to populate the newly created submenus with
the relevant items and their associated Python commands. In this case, the
script looks for the *Examples* directory that ships with |product| and then
scans that directory for example data and scripts which are then referenced
in the appropriate submenus.

.. oe:source:: add_menu.vpy
   :frag:     POPULATE_SUBMENUS

.. _add_menu_item.vpy:

add_menu_item.vpy
-----------------

This example shows how to add a new entry to an already existing menu. The
new entry when clicked on in the menu will execute the specified Python
command. 

.. oe:source:: add_menu_item.vpy
   :frag:     ADD_MENU_ITEM

.. _add_menu_updating.vpy:

add_menu_updating.vpy
---------------------

This example shows how to create a new menu which is populated by a specified
Python command each time the menu is shown. In this example, each time the
user clicks on the *Examples* menu, the specified ``UpdateExamplesMenu`` 
function will be called before the menu is actually shown.

.. oe:source:: add_menu_updating.vpy
   :frag:     ADD_MENU

The ``UpdateExamplesMenu`` function is defined below. The first thing this
function does is to clear the previous contents of the menu by calling the
``MenuRemoveAll`` function. It then searches for the *Examples* directory that
is provided by |product| and then scans that directory for example data and
scripts which are then referenced in the appropriate submenus.

.. oe:source:: add_menu_updating.vpy
   :frag:     POPULATE_MENUS

The process by which the menus are created and populated here is somewhat 
different from the :ref:`add_menu.vpy` example due to the dynamic nature of
the menu creation in this example.

.. _add_toolbar_button.vpy:

add_toolbar_button.vpy
----------------------

This example shows how to add a simple button to the main application toolbar
which when pressed will execute the specified Python command (in this case
`DeleteAll`).

.. oe:source:: add_toolbar_button.vpy
   :frag:     ADD_TOOLBAR_BUTTON

It is worth nothing that ``ToolbarRemove`` is called before 
``ToolbarAddViaNamedIcon`` in order to ensure that multiple buttons will not
be created and thus fill up the toolbar if the script is run multiple times.

.. _add_toolbar_toggle.vpy:

add_toolbar_toggle.vpy
----------------------

This example shows how to add a simple toggle button to the main application
toolbar. A *toggle* button is different from a standard *push* button in that 
it has two potential states and can display a different icon and execute 
different Python commands based on the current state.

.. oe:source:: add_toolbar_toggle.vpy
   :frag:     ADD_TOOLBAR_TOGGLE

As seen in the example above, a toggle button also supports specification of an
*update* command which may be executed to determine the current state of the 
button. The specified *update* code is normally executed when a call to 
``ToolbarUpdate`` or ``ToolbarItemUpdate`` is made.

.. oe:source:: add_toolbar_toggle.vpy
   :frag:     OVERRIDE_TO_ENABLE_UPDATES

To ensure that this particular toggle button is kept in sync with the state of
application, the ``AppMainWindowSet`` function is overridden to include a call 
to ``ToolbarItemUpdate``. This is particularly important as there are other 
common pathways within |product| which can have the same effect as toggling 
this button (such as changing the main window through the *Windows* main menu).

.. _calc_et.vpy:

calc_et.vpy
-----------

This example shows how to create a function using the **OEChem** and **Zap**
Python toolkits from OpenEye to calculate the electrostatic Tanimoto between
two molecules currently loaded in |product|.

.. oe:source:: calc_et.vpy
   :frag:     CALC_ET

The ``CalculateET`` function retrieves copies of the specified molecules from
|product|, prepares them for the calculation and then performs the actual
calculation. The resulting Tanimoto value is then returned by the function.

.. oe:source:: calc_et.vpy
   :frag:     CALC_ET_LIST

The ``CalculateETForList`` function expects a |product| list ID as a parameter. 
The function will then assign the first molecule in the list to be the 
reference structure against which the ET will be calculated for all the other
molecules in the list.

Instead of returning a list of ET values, the calculated ET is stored as a data
field in the application spreadsheet using the ``DataAdd`` function.

.. _calculate_clashes.vpy:

calculate_clashes.vpy
---------------------

This example shows how to use the **OEChem** toolkit within |product| to 
detect and then visualize intermolecular clashes.

.. oe:source:: calculate_clashes.vpy
   :frag:     CALCULATE_CLASHES

The ``CalculateClashes`` function takes the IDs of two molecules and a cutoff
distance used to determine the intermolecular clashes. The clashes are 
determined by calling the **OEChem** function ``OEGetNearestNbrs``. Any clashes
that are found are then visualized as distance monitors (colored red) between 
the clashing atoms.

.. _cluster_browsing.vpy:

cluster_browsing.vpy
--------------------

This example is one of the most complicated examples included in this set as
it incorporates many aspects of |product| scripting into a single example. This
example shows how one can create their own custom cluster browsing interface 
within |product| using clustering information stored in the SD data of the 
relevant molecules.

The first part of the example attempts to locate an associated '.ui' file which 
defines the layout of the widget used in this example. The '.ui' file is 
expected to be located in the same directory as the script. If the '.ui' file 
is not found, the script will throw an exception.

.. oe:source:: cluster_browsing.vpy
   :frag:     LOCATE_UI_FILE

A picture of the widget template defined by the '.ui' file can be seen in the 
figure :ref:`below<figure_cluster_browsing_ui>`. This widget was created using 
the *Qt Designer* application and 
will be loaded into an actual class using PySide2.

.. _figure_cluster_browsing_ui:

.. figure:: images/cluster_browsing_ui.png
   :scale:  75
   :align:  center
   
   **cluster_browsing Widget Template**

The actual widget class is created below using PySide2. The class constructor 
performs the required initializations, loads the ui file, and sets up the
necessary connections between the internal widgets and the classes methods.

.. oe:source:: cluster_browsing.vpy
   :frag:     DEFINE_WIDGET
   
Once the ``ClusterBrowser`` widget class has been defined, an actual instance 
of that class needs to be created. In order to ensure that the 
``ClusterBrowser`` can be embedded into frame around the main window, a 
``QDockWidget`` is created to contain the ``ClusterBrowser`` and then added
to the right-hand side of the main window.

In addition, a menu item is added to the *Tools* menu which will prompt the
user to specify an input file and then will show the ``ClusterBrowser``
widget.

.. oe:source:: cluster_browsing.vpy
   :frag:     CREATE_WIDGET

As described above, the molecules are expected to contain cluster information
in their associated SD data. This data can be viewed and processed in the 
spreadsheet. To help organize this information, a custom sorting function is
defined below.

.. oe:source:: cluster_browsing.vpy
   :frag:     SORT_FXN
   
The ``ViewClustersID`` function defined below takes as a parameter the ID of a 
list of molecules already loaded into |product| which contain the appropriate 
SD data. This function then creates a new filtered spreadsheet called "Ideas"
which only contains the cluster centroids (or "Ideas"). For each "Idea" there
is an associated "Idea Group" of other molecules. A new filtered spreadsheet
is also created for each individual "Idea Group", although it is hidden from 
the main spreadsheet tab by default.

This function also populates the drop-down menu in the ``ClusterBrowser`` 
widget defined above with an entry for each of the "Idea Groups".
   
.. oe:source:: cluster_browsing.vpy
   :frag:     VIEW_CLUSTERS
   
The ``ViewClusterFile`` function loads a specified molecule file and then 
passes the ID of the newly created list to the ``ViewClustersID`` function
to setup the view. Before calling this function, the spreadsheet window is
hidden to prevent flickering as many spreadsheet operations take place in
the ``ViewClustersID`` function.

.. oe:source:: cluster_browsing.vpy
   :frag:     VIEW_CLUSTER_FILE
   
The ``ViewIdeaGroup`` function takes the index of an "Idea Group" as a 
parameter. If the idea group exists, the associated spreadsheet will be shown.
In addition, the first 12 molecules in the "Idea Group" are displayed in tiled
mode in the main window (either 2D or 3D, depending on which option the user 
has selected).

.. oe:source:: cluster_browsing.vpy
   :frag:     VIEW_IDEA_GROUP

.. _docking_view.vpy:

docking_view.vpy
----------------

This example shows how to create a function which replicates the behavior of
the ``FRED View`` tool available under the *Tools* menu. The function takes a
protein ID, a ligand ID and an optional list of IDs corresponding to docking
results. 

.. oe:source:: docking_view.vpy
   :frag:     DOCKING_VIEW

As expected from the ``FRED View`` behavior, this function makes the 
protein-ligand complex visible and centers the view on the ligand in the 
active site. Furthermore, it adds a surface to the protein, colors and crops 
the surface to a certain distance from the ligand, and hides residues a 
certain distance from the ligand. The function also adds residue information
labels as well as turns on the display of hydrogen bonds.

.. _fix_file_omega.vpy:

fix_file_omega.vpy
------------------

This example incorporates widget creation using PySide2 and interaction with
the **OmegaTK** toolkit. The example shows how **OmegaTK** can be used to 
generate new conformations for a molecule within |product| and furthermore how
the user can fix certain portions of the molecule during the conformer 
generation process.

The first part of the example shows how the widget is created using PySide2
from an associated '.ui' file. The '.ui' file is expected to be located in the 
same directory as the script. If the '.ui' file is not found, the script will 
throw an exception. In addition, this part of the example also creates the 
OEOmega object which will be used later to generate the conformations.

.. oe:source:: fix_file_omega.vpy
   :frag:     CREATE_WIDGET
   
A picture of the widget template defined by the '.ui' file can be seen in the 
figure :ref:`below<figure_fix_file_omega>`. 

.. _figure_fix_file_omega:

.. figure:: images/fix_file_omega_ui.png
   :scale:  75
   :align:  center
   
   **fix_file_omega Widget Template**

The following example code details the actual function that will be called
to generate the new conformations. It shows how configuration information is
pulled from the widget as well as how the fixed portion of the molecule is
determined and specified to the Omega object.

.. oe:source:: fix_file_omega.vpy
   :frag:     GENERATE_CONFS

This final section of code connects up the function defined above to the
appropriate button and then creates a menu item in a 'Special' menu to open
the widget.
   
.. oe:source:: fix_file_omega.vpy
   :frag:     CONNECT_FUNCTIONS

.. _load_and_split_pdb.vpy:

load_and_split_pdb.vpy
----------------------

This example shows how to load a file directly from the PDB and then split
that file into its individual components. This first section details the
function which fetches the molecules corresponding to the specified PDB codes
and then loads them into |product|.

.. oe:source:: load_and_split_pdb.vpy
   :frag:     LOAD_FROM_PDB

The following section details the ``LoadAndSplitPDBs`` function which
calls the ``LoadMoleculesFromPDB`` function defined above and then
iterates over the newly loaded molecules, splits them into their individual
components, and then removes the original complex.

.. oe:source:: load_and_split_pdb.vpy
   :frag:     SPLIT_PDB

This final section shows how a new menu item is created to prompt the user for
the desired PDB codes and then to call the above function. This section also 
shows how to replace the command associated with a menu item in the event that
the menu item has already been created.

.. oe:source:: load_and_split_pdb.vpy
   :frag:     ADD_MENU_ITEM


.. _molecule_alignment.vpy:

molecule_alignment.vpy
----------------------

This example shows how to create a moderately complex widget using PySide2 to
perform molecule alignments using one of a variety of techniques including: 
shape & color, RMSD, or sequence. 

The following block of code shows the function which performs the shape and 
color alignment of two specified molecules using the **OEChem** and **OEShape** 
toolkits.

.. oe:source:: molecule_alignment.vpy
   :frag:     SHAPE_ALIGN

The following block of code shows the function which performs the RMSD 
alignment of two specified molecules using the **OEChem** toolkit. Note that 
before the alignment is done, the graphs of the two molecules are compared by
the generation of canonical SMILES.

.. oe:source:: molecule_alignment.vpy
   :frag:     RMSD_ALIGN

The following block of code shows the function which performs the sequence
alignment of two specified proteins using the **OEChem** toolkit. Note that a 
check for residue information is performed on both molecules to ensure that
a sequence alignment is even feasible.

After the alignment is performed in this function, the two molecules are both
made visible, uniquely colored and displayed in ribbon style.

.. oe:source:: molecule_alignment.vpy
   :frag:     SEQUENCE_ALIGN

The following section shows how the main widget is hand-coded (as opposed to
using a '.ui' file from *Qt Designer*) using PySide2.

.. oe:source:: molecule_alignment.vpy
   :frag:     CREATE_WIDGET

This next section shows the definition of all the functions that provide the
interface between the widget and the desired actions.

.. oe:source:: molecule_alignment.vpy
   :frag:     CREATE_WIDGET_FUNCTIONS

This final section shows how the widget buttons are connected up to the support
functions defined in the section above.

.. oe:source:: molecule_alignment.vpy
   :frag:     CONNECT_FUNCTIONS

.. _open_from_pdb.vpy:

open_from_pdb.vpy
-----------------

This example shows how to load one or molecule molecules directly from the PDB.
The following section details the function which fetches the molecule(s) from
the PDB corresponding to the specified PDB code(s) and then loads them into 
|product|.

.. oe:source:: open_from_pdb.vpy
   :frag:     LOAD_FROM_PDB
   
This final section shows how a new menu item is created to prompt the user for
the desired PDB codes and then to call the above function. This section also 
shows how to replace the command associated with a menu item in the event that
the menu item has already been created.

.. oe:source:: open_from_pdb.vpy
   :frag:     ADD_MENU_ITEM

.. _override_open_1.vpy:

override_open_1.vpy
-------------------

This example shows how to override the ``Open`` function in |product| to 
customize the behavior when a file is opened. In this case, the original
function is cached so that it can be called later within the new function.
Once the file has been loaded, this function iterates over all the newly
loaded molecules looking for atoms with formal charges. If a formal charge
is found, a label corresponding to the charge is added to that atom.

.. oe:source:: override_open_1.vpy
   :frag:     OVERRIDE_OPEN

.. _override_open_2.vpy:

override_open_2.vpy
-------------------

This example shows how to override the ``Open`` function in |product| to
customize the behavior when a file is opened. In this case, the original
function is cached so that it can be called later within the new function.
Once the file has been loaded, this function iterates over all the newly
loaded molecules looking for molecules that do not have a dimension of 3.
In cases where the dimension is not 3, 3D coordinates are generated for the
molecule using Omega.

.. oe:source:: override_open_2.vpy
   :frag:     OVERRIDE_OPEN

.. _search_chemspider.vpy:

search_chemspider.vpy
---------------------

This example shows how to search `ChemSpider <http://www.chemspider.com/>`_ 
using the active molecule as a query. The active molecule is converted to a
SMILES string which is inserted into the ChemSpider search URL.

.. oe:source:: search_chemspider.vpy
   :frag:     SEARCH_CHEMSPIDER
   
The following section shows how the above function is bound to a button which
is placed in the main application toolbar.
   
.. oe:source:: search_chemspider.vpy
   :frag:     ADD_TO_TOOLBAR

.. _search_pubchem.vpy:

search_pubchem.vpy
------------------

This example shows how to search `PubChem <http://pubchem.ncbi.nlm.nih.gov/>`_
using the active molecule as a query. An IUPAC name is generated for the active
molecule using the OpenEye **Lexichem** toolkit. The generated name (if valid) is then
inserted into the PubChem search URL.

.. oe:source:: search_pubchem.vpy
   :frag:     SEARCH_PUBCHEM
   
The following section shows how the above function is bound to a button which
is placed in the main application toolbar.

.. oe:source:: search_pubchem.vpy
   :frag:     ADD_TO_TOOLBAR

.. _simple_pyside2.vpy:

simple_pyside2.vpy
-----------------------

This example shows how to create a very simple widget with a functioning button 
using PySide2 and how to display it within |product|.

.. oe:source:: simple_pyside2.vpy
   :frag:     SIMPLE_PYSIDE2

.. _void_volumes.vpy:

void_volumes.vpy
----------------

This example shows how to create a function which generates and then loads into
|product| the calculated void volume between a protein and a ligand. 

.. oe:source:: void_volumes.vpy
   :frag:     CALC_VOID_VOLUMES
