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

==========================================
Perform a ROCS run from the command line
==========================================

Background information
^^^^^^^^^^^^^^^^^^^^^^

A simple **ROCS** run allows you to choose a query and a 
database to search.  It will search the database for 
the closest matches to your query and load your results 
afterwards.  The majority of runs with **ROCS** are simple runs 
using a molecular shape-based query, with or without color 
atoms.  Other query types can also be used, in a similar 
fashion, as described in section 
:ref:`ROCS shape query sources<shape_query_sources>`.

You are working on a project for which the current lead series 
has a problem with CYP2C9 metabolism.  You are hoping to suggest
some synthesis candidates that have a low risk for CYP2C9 
metabolism.  You recently saw a paper by Sykes et. al (\ [Sykes-2008]_\ ) in 
which they use ROCS to validate a database of 70 known 
Cytochrome P450 2C9 substrates.  You plan to use ROCS 
similarity to compounds in this database to predict whether 
your ideas will be metabolized by CYP2C9.  One of your ideas 
is shown in the :ref:`OEDepict TK depiction below<tutorial5_2D_fig>`.  
You plan to use ROCS command line.

.. _tutorial5_2D_fig:

.. figure:: ../images/tutorials/tutorial5_2D.png
   :scale: 75
   :align: center
   :alt: OEDepict TK depiction of the synthesis candidate molecule and ROCS query
   
   **OEDepict TK depiction of the synthesis candidate molecule and ROCS query**


This tutorial will provide the user with the background required to 
set up a simple **ROCS** run in the command line ROCS interface from a 
saved query and analyze the results.  The tutorial will require 
approximately 10 minutes of personal time and 1 minute of
computer time to complete.  This is a repeat of the simple run the 
vROCS tutorial :ref:`Perform a simple ROCS run<tutorial4>`.

Setup ROCS run
^^^^^^^^^^^^^^

Open a command prompt and navigate to a working directory of your
choice.  At the very minimum **ROCS** requires an input query file and an 
input database file.  There are numerous additional parameters 
(e.g. specifying a custom color force field file) that can be added 
to the command, as well.

In the **vROCS** tutorial :ref:`Perform a simple ROCS run<tutorial4>`, 
the command line provided to **ROCS** (on Windows) is:

.. code-block:: bash

	rocs.bat \
	-query molecule_idea.sq \
	-dbase jmedchem_database.oeb.gz \
	-prefix rocs \
	-outputdir C:/Users/username \
	-besthits 500 \
	-rankby TanimotoCombo \
	-shapeonly false \
	-randomstarts 50 \
	-opt true \
	-scoreonly false \
	-optchem true \

This is found in the ``Command line…`` information field of the run 
set-up dialog.  Most of these parameters are default.  The only one 
that was changed was –randomstarts 50, instead of the default Inertial start. 

Run a simple ROCS run
^^^^^^^^^^^^^^^^^^^^^

At the command prompt type the following command to run ROCS.  

.. note::
  
  If the query and database files are in your current working 
  directory you do not need to specify a full directory path 
  to the files.  If not, specify the full path to the query and database files.


.. code-block:: bash

	rocs \
	–query \
	OPENEYE_DIR/data/vrocs/simple/molecule_idea.sq \
	–dbase \
	OPENEYE_DIR/data/vrocs/simple/jmedchem_database.oeb.gz \
	–prefix tutorial5 \
	–randomstarts 50

This run requires about 40 seconds.

Visualize and save results
^^^^^^^^^^^^^^^^^^^^^^^^^^

ROCS automatically saves the following files using the prefix given above 
in the naming convention.  If no prefix is given then the default prefix is 
rocs.

* prefix_parm
* prefix.log
* prefix_ref.sq
* prefix_1.rpt
* prefix_1.status
* prefix_hits_1.sdf

The .rpt file contains all the score data in a tab delimited format. 
The .sdf contains all the database hits in their aligned conformation, 
together with scores.  This sd file is suitable for opening in VIDA 
for further examination.

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

This concludes the tutorial "Perform a **ROCS** run from the command line"
which guides the user through the basics of running a simple **ROCS**
run through the command line interface and visualizing the results.


