﻿.. _tutorial1:
.. include:: ../substitutions
.. include:: ../../apps-substitutions

========================================
Build/edit a query using the Wizard
========================================


Background information
^^^^^^^^^^^^^^^^^^^^^^
This tutorial teaches the user to create a new query to either save or to use
in ROCS.  The wizard creates a query through one of a few predesigned paths.  

You have recently been assigned to a trypsin inhibitor project.  You are 
interested in building a query from known ligands in their binding modes, 
suitable for use in **ROCS** for vHTS.  A set of 19 trypsin inhibitors are 
available as co-crystal structures from the PDB (see the IDs for trypsin inhibitors in the [PDB-IDs]_\  citation).
The dataset has been prepared by aligning the 19 protein crystal 
structures.  The ligands were 
then extracted to give a set of 19 ligands, aligned in 
the protein binding pocket frame of reference.  The query building wizard 
will be used to construct a **ROCS** query to employ only the ligands
that are most representative of the set as a whole.

The tutorial will require approximately 10 minutes to complete.

Build models using the wizard
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Open a new **ROCS** session.  At the Welcome screen select the option to 
``Create a query with a wizard``.  This will open up the ``Create a query`` dialog.

In the top tab, Create Query, select the radio button for Ligand Model Builder 
and then click Next.

In the Load Aligned Ligands tab click on the Filename area and browse to the 
file containing the 19 aligned trypsin ligands.  This file is located in the 
``OPENEYE_DIR/data/vrocs/wizard`` directory and is called 
``pdbmodel_ligands.oeb.gz``.  Click OK in the file browser to accept the 
choice of file.  The file will be loaded and the first ligand is displayed 
in the preview.  Examine the ligand by rotating (left mouse button) or 
zooming (mouse wheel) the structure image.  Scroll through the list 
of ligands using the green arrows.  When satisfied click Next to continue.

It is not required to change any of the options in the Adjust Parameters 
tab, as indicated by the green check mark next to the tab name.  However, for the 
purposes of this tutorial we will keep the 
Max Molecules Per Model as 3 (consider only models containing 1,2 or 3 molecules) 
but increase the Models to Keep to 3 (keep the best 3 models for further 
review).  Enter Trypsin in the ``Prefix`` field and check the box to ``Merge Color Atoms``.  

Click Next to begin building the models.  A progress dialog will provide information 
on the model building.  When all the 1159 models containing 1, 2 or 3 molecules 
from the dataset of 19 trypsin inhibitors have been built and compared the top 
3 models are listed in the Pick Queries dialog.

Visualize the results
^^^^^^^^^^^^^^^^^^^^^

The first model in the list, ‘Trypsin 1’, is displayed in the preview window and 
is made from three of the ligands: 1G3E.pdb, 1GHZ.pdb and 1QB6.pdb.  This is 
the model that is most representative of the dataset of 19 inhibitors as a whole.  

Note that the three ligands align at one end of the model whilst the other end is 
described by only the single, larger molecule.  Where the three ligands align 
closely the donor/cation/donor triad of color atoms have been merged to a single 
representation, instead of close color atoms from each ligand (e.g. three partially 
overlaid cation color atoms).  Retaining multiple instances of the color atoms 
would serve to stress the importance of these features in the model over the 
other features.

Click on the second model, 'Trypsin 2'.  Its name will be highlighted in blue 
and it will be displayed in the preview window.  This is the second most 
preferred model and is also made of three ligands: 1H4W.pdb, 1K1I.pdb and 1QB9.pdb.  
Note that this is a different set of three ligands than Trypsin 1 
(although it is possible for some ligands to be used in multiple high ranking models).  

The third model, 'Trypsin 3' is made of 1C5T.pdb, 1GJ6.pdb and 1QBO.pdb.  
All three models contain one of the larger, hinged ligands and at least 
one of the set of smaller ligands.

Save the results
^^^^^^^^^^^^^^^^

Place a check mark next to the name of each model to select it for export 
to the main vROCS interface.  In this tutorial we will export all three 
models and save them so they can be used in further validation experiments.
However, in your own work you may choose only some of the 
models for export.

Having checked all three models click ``Finish`` to close the ``Build a new query`` 
dialog.  Model 'Trypsin 1' will be displayed in the main vROCS 3D window 
and the Welcome panel is to the left of the screen.  In the Welcome panel 
click on ``Perform a simple ROCS run``.  The three models are listed as 
potential queries in the Inputs dialog, with 'Trypsin 1' as the active 
query.  To save 'Trypsin 1' as a ROCS saved query (\*.sq) file select 
``File > Save Query As…`` from the main File menu.  Navigate to your preferred 
working directory and enter ``Trypisn_1.sq`` as the file name.  Click ``OK`` to 
save the file.  In the query list select model 'Trypsin 2' and use 
``File > Save Query As…`` to save this query as ``Trypsin_2.sq``.  Repeat with
model 'Trypsin 3' to save a query with filename ``Trypsin_3.sq``.

Conclusions
^^^^^^^^^^^

This concludes the tutorial "Build/edit a query using the Query Wizard".  In this 
tutorial we used a set of 19 aligned known trypsin ligands and built three potential 
ROCS queries, using up to three of the ligands from the dataset.  These queries best 
describe the dataset as a whole, based on TanimotoCombo scores of all the potential 
models.  These models can be further validated before use, as described in 
the tutorial :ref:`Perform a **ROCS** validation run<tutorial3>`.

If you have time some suggestions for further study are: 

* Try changing some of the model building parameters.  (Note, it is recommended to keep the 
  maximum number of molecules in a model low (less than or equal to five), to avoid extended
  run times for model building and overly complex output models/ROCS queries.
* Modify the current force field in the Preferences dialog (Edit  > Preferences, vROCS tab) and see whether this changes the models
* Re-run the tutorial steps with your own set of aligned ligands 
