.. include:: substitutions
.. include:: ../apps-substitutions

.. program:: flipper

.. _chapter_flipper:

*************
Flipper
*************

====================
Overview
====================

The **OMEGA** distribution includes **Flipper**, a utility program for
enumerating stereocenters in a molecule.  We have taken the philosophy that
conformer generation and stereochemistry enumeration are related but distinct
problems.  Thus we provide **Flipper** as part of the **OMEGA** product, but not as
part of the same executable.

The current version of **Flipper** can handle enumeration of R/S
stereochemistry (including N and S stereochemistry) as well as
cis/trans stereochemistry. **Flipper** uses graph algorithms to determine
which atoms are stereocenters.  If a stereocenter has a designated
stereochemistry, by default **Flipper** does not change the stereochemistry.
However, if a stereocenter does not have a specified stereochemistry,
**Flipper** will enumerate both stereochemistry states of the stereocenter.

Many common file formats are limited in their ability to fully express
stereochemistry without resorting to Cartesian coordinates.  This can
lead to ambiguity in whether a particular conformer is supposed to
represent a racemic mixture or an isolated stereoisomer. SD file format performs
better than most, as it allows the designation of R, S, or racemic on
each tetrahedral stereocenter independent of the particular conformation.
However, SD format is not as robust for cis/trans stereochemistry.  Isomeric SMILES
is the only common file format which allows complete specification of R/S
and cis/trans stereochemistry.  In fact, although **Flipper** does not
support higher orders of stereochemistry, the isomeric SMILES format is
capable of handling them.  For this reason, **Flipper** output is limited to SD
format (.sdf or .mol) and isomeric SMILES format (.ism). **OpenEye** OEBinary
format, like isomeric SMILES, is capable of fully specifying
stereochemistry; however, isomeric SMILES is more efficient for compounds
without any data beyond the title and connection table.

The **Flipper** process can
also be done with **OMEGA** using the `-flipper` flag.

Input Dimensionality
------------------------------------

**Flipper** is designed for use prior to 3D coordinate generation.  So 2D
or 1D (SMILES) input is normally expected.  Input files containing 3D
coordinates are handled, but the 3D coordinates are ignored and not
transferred to the output.

.. _section_flipper_usage:

======================
Example Commands
======================

Below are three example *flipper* executions.  Each example is followed by a
brief description of the parameter's effects.
Sample data files can be found in the data directory.

.. code-block:: bash

   flipper -in drugs.smi -out enumerated.ism

This execution will examine each stereocenter in *drugs.smi*.  If the
stereocenter does not have a specified stereochemistry, **Flipper** will
generate molecules with each of the stereochemistry states at each
stereocenter.

.. code-block:: bash

   flipper -in drugs.smi -out enumerated_forceflip.ism -forceflip true

This execution will differ from the first in that **all** stereocenters
will be enumerated, regardless of whether the stereochemistry is specified
in the input file.

.. code-block:: bash

   flipper -in drugs.smi -out enumerated_maxcenters6.ism -maxcenters 6

In this execution, **Flipper** will exhaustively enumerate all unspecified
stereocenters in molecules with up to six stereocenters.  For molecules with
more than six stereocenters, a random set of 64 isomers will be generated
from the larger set of potential stereoisomers.

====================
Command Line Help
====================

A description of the command line interface can be obtained by executing **Flipper**
with the `--help` option.

.. code-block:: console

   flipper --help

will generate the following output:

::

   Help functions:
     flipper --help simple      : Get a list of simple parameters
     flipper --help all         : Get a complete list of parameters
     flipper --help defaults    : List the defaults for all parameters
     flipper --help <parameter> : Get detailed help on a parameter
     flipper --help html        : Create an HTML help file for this program
     flipper --help versions    : List the toolkits and versions used in the application


====================
Required Parameters
====================

.. option:: -in

   File containing one or more molecules for which stereoisomers will be generated.

====================
Optional Parameters
====================

.. option:: -out

   Output molecule file name. The output file format is limited to OEB, isomeric SMILES
   (*.ism* and *.smi*), or SD formats since these are the only formats which fully specify
   stereocenters without the need for three-dimensional coordinates.

.. option:: -enhstereo

   The `-enhstereo` string flag controls
   the behavior of **Flipper** with respect to enumeration of stereocenters
   in the presence of enhanced stereogroups.  When true, stereocenters in enhanced stereogroups are enumerated to
   retain relative stereo relationships between centers within a given stereogroup.
   [Default=false]

.. option:: -enumAtoms

   Enumerate atom stereocenters in a molecule according to the atom qualifier flags.
   [Default=true]

.. option:: -enumAtomSpecifiedStereo

   Modify atom stereocenters in a molecule. If *false*, only atoms which
   do not already have a specified stereochemistry would be enumerated.
   [Default=false]

.. option:: -enumBonds

   Enumerate bond stereocenters in a molecule according to the bond qualifier flags.
   [Default=true]

.. option:: -enumBondSpecifiedStereo

   Modify cis/trans bonds in a molecule. If *false*, only bonds which do
   not already have a specified parity would be enumerated.
   [Default=false]

.. option:: -enumBridgehead

   Enumerate bridgehead stereocenters.
   [Default=false]

.. option:: -enumEZ

   Enumerate E/Z stereocenters only.
   [Default=false]

.. option:: -enumNitrogen

   The `-enumNitrogen` string flag controls
   the behavior of **Flipper** with respect to enumeration of nonterminal
   nitrogens.  Any nitrogen with pyramidal geometry in the initial
   model of the input molecule, and having no more than two ring bonds
   is considered by **OMEGA** to be *invertible*.  **Flipper** will enumerate all
   possible puckers if the `-enumNitrogen` flag is set to *True*. [Default = False]
   [Aliases: -en]

.. option:: -enumRS

   Enumerate R/S stereocenters only.
   [Default=false]

.. option:: -enumRelativeAtomStereo

   Enumerate relative atom stereocenters in a molecule.
   [Default=false]

.. option:: -enumSpecifiedStereo

   This parameter forces **Flipper** to modify all of the
   stereocenters in a molecule.  If `-enumSpecifiedStereo` is false (the default),
   
   **FLIPPER**  only enumerates stereocenters which do not already have a specified
   stereochemistry.
   [Default=false]
   [Aliases=-forceflip]

.. option:: -maxCenters

   Obviously, the number of molecules generated by
   enumerating the stereocenters is :math:`2^N`, where `N` is the number of
   stereocenters.  In some instances, this may be larger than is desired.  The
   `-maxCenters` parameter indicates the maximum number of stereocenters
   which will be fully enumerated.  If a molecule has more than
   `-maxCenters` stereocenters, **Flipper** will randomly enumerate
   `2^(maxCenters)` instances from the full set of potential isomers.
   [Default=12]
   [Aliases=-maxcenters]

.. option:: -molNames

   Molecule names file corresponding to the input file.

.. option:: -prefix

   Prefix to use to name output files.

.. option:: -progress

   Type of progress to show on screen during run.

.. option:: -warts

   Add wart to title of each stereoisomer.
   [Default=false]

