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

.. _flynn_opt_params:

.. program:: flynn

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

Input Options
^^^^^^^^^^^^^

.. option:: -prot <filename>

   Optional protein used to mask density.  This model is used to mask away density where
   the ligand should not be placed.  While the protein is not required,
   it is highly recommended.

   ============   ===========================
   File type      Extension
   ============   ===========================
   OEBinary       .oeb .oeb.gz
   ------------   ---------------------------
   SDF            .sdf .mol .sdf.gz .mol.gz
   ------------   ---------------------------
   MOL2           .mol2 .mol2.gz
   ------------   ---------------------------
   PDB            .pdb .ent .pdb.gz .ent.gz
   ------------   ---------------------------
   MacroModel     .mmod .mmod.gz
   ============   ===========================

.. option:: -fragment

Fragments are fit taking the input fragment cocktail and, one at a
time, fitting each fragment against each region of detected density.
Once a fragment has been placed, it is further analyzed to ensure that
all possible orientations of the fragment have been sampled.  In poor
density, several orientations may fit equally well.  To break ties,
FLYNN scores each pose with the following scores:

 o RSCC (real space correlation coefficient)  This is a measure of fit to electron density. [Jones-1991]_

 o PLP Piecewise-linear potential.  [Verkhivker-2000]_

 o Chemscore [Eldridge-1997]_

The docking scores are not used to fit the molecule, they are only
used to rank the output.  Unless highly symmetric molecules are being
input, the real space correlation coefficient (RSCC) is the preferred
method of ranking results to density.

All scores are annotated to the output ligands using SD data when
appropriate (.SD and .OEB output) or using the PDB remark field:

::

 Example PDB output

 REMARK OpenEye Flynn MMFF/Shape v 2.1.0
 REMARK Stereo Variant:      1
 REMARK Blob:                1
 REMARK Conformer:           1
 REMARK Tanimoto Shape:        0.2004
 REMARK Tanimoto MMFF/Shape:   0.2034
 REMARK Local Strain:          4.9316
 REMARK RSCC: 0.529438
 REMARK PLP: -51.395416
 REMARK Chemscore: -16.288113

::

 Example SDF output

 > <Tanimoto MMFF/SHAPE>
  0.2034

 > <Tanimoto Shape>
  0.2004

 > <Overlap>
 364.767659122018

 > <Fit Overlap>
 781.301114117834

 > <Local Strain>
  4.9316

 > <Lambda>
 1.600000023842

 > <Ref Overlap>
 1371.829467773438

 > <Stereo>
 1

 > <Blob>
 1

 > <Conformer>
 1

 > <RSCC>
 0.529438

 > <PLP>
 -51.395416

 > <Chemscore>
 -16.288113

To use fragment mode, please add the "-fragment" option to the command
line.  In future versions of FLYNN, this will most likely become the
default setting.

The output of the fragment fitting process is a file for each density
region that includes the fragments fit to the region sorted from
best-fit to worst fit.  For example:

.. code-block:: console

   > flynn -in fragments.smi -out 2IKO_cocktail.sdf ...

would result in the files:

.. code-block:: console

  2IKO_cocktail_blob001.sdf
  2IKO_cocktail_blob002.sdf
  2IKO_cocktail_blob003.sdf

one for each blob found.  The first molecule in the file is the best
fit to the density.

To sort using another measure, for instance, PLP, use the sort flag:

.. code-block:: console

   > flynn -sortBy plp -in fragments.smi -out 2IKO_cocktail.sdf ...

When oeb format is used, the blob is also stored in the OEB file.
When using VIDA, simply expand the molecule to investigate the
blobs density.

.. option:: -param <parameter filename>

   A parameter file is a text file that lists parameter settings to be used
   during a run.   If a parameter is specified both on the command line and in
   the parameter file, the value specified on the command line is used.

   The format of the parameter file is as follows:

   * One parameter per line

   * For non-list parameters one key-value pair per line.

   * For list parameters a key followed by all the values.

   * Boolean parameters must be listed as a key followed by true or false.

   * The parameter file may not contain the :option:`-param` parameter.

   * Lines beginning with # are considered comments

   [Aliases=**-com**]

.. option:: -prefix <file prefix>

   Define the default prefix to use for loggging and report file generation.

   This -prefix is overridden when using the *-reporthtml* or *-reportfile*
   command line options.

   [Default=flynn]

.. option:: -manualSearch <filename>

   Use the input molecule to generate a box volume.  All density inside this
   box will be used to place the ligand.

   [Aliases=**-box**]

.. option:: -boxpad <number>

   Pad the box created with the *-manualSearch* flag by an amount in
   |Angstroms|.

   [Default=1.0]

.. option:: -autoThenManualSearch

   Automatically search for blobs first, if now suitable blobs are found, use the
   supplied box to bound density.

   [Default=false]

   [Aliases=**-blobsThenBox**]

.. option:: -densityAsIs

   Use the supplied density as it is; do not try to find suitable
   blobs inside the density.  Note that
   the supplied density has to be pretty close to the actual ligand
   density for this to work

   [Default=false]

.. option:: -distance <value>

   Reject blobs whose average distance to the protein is greater than
   this value.

   [Default=4.0]

.. option:: -ligandAsIs

   Do not generate conformations for the ligand; use only the supplied
   conformations.

.. option:: -mmff94s

   Use the MMFF94s variant of the MMFF94 forcefield ( this uses
   planar aniline nitrogens ).

  [Default=true]

.. option:: -ff <forcefield>

   Select the forcefield to use for fitting the molecule into density.

   ===============================  ========
   Value                            Meaning
   ===============================  ========
   mmff94                           MMFF94
   mmff94s                          MMFF94s (default)
   am1                              AM1
   am1-sheffield                    AM1-Sheffield
   pm3                              PM3
   pm3-sheffield                    PM3-Sheffield
   mmff94-electrostatics            MMFF94 with electrostatics
   mmff94-electrostatics-sheffield  MMFF94 with Sheffield electrostatics
   ===============================  ========

   [Default=mmff94s]

.. option:: -reportfile <filename>

   File location for writing the report file.  This is a comma
   separated file containing specifics about the results.

  Smiles,Blob,Stereo Variant,Conformer,Tanimoto Shape,Tanimoto MMFF/SHAPE,Local Strain
  CC(=O)[C@H]1CC[C@@H]2[C@@]1(CC[C@H]3[C@H]2CCC4=CC(=O)CC[C@]34C)C,1,,,0.4110,0.4296,1.342
  CC(=O)[C@H]1CC[C@@H]2[C@@]1(CC[C@H]3[C@H]2CCC4=CC(=O)CC[C@]34C)C,1,,,0.313,0.3704,4.553
  CC(=O)[C@H]1CC[C@@H]2[C@@]1(CC[C@H]3[C@H]2CCC4=CC(=O)CC[C@]34C)C,1,,,0.3265,0.3628,5.223



.. option:: -resname <name>

   Set the output residue name to **<name>**.  **<name>** must be less
   than or equal to three characters in length.  This forces the
   output residue to be named <name> even if the residues structure
   does not match a known deposited residue.

.. option:: -chainid <chainid>

   Forces the ligand to be placed in the chain <chainid>

.. option:: -assignClosestChainId

   Assign the closest protein chain (within 7 Angstroms) to set the
   ligand's chain id.  Cannot be used with the explicit :option:`-chainid`
   setting.

   [Aliases=**-assignClosestChainID**,**-assignClosestChainid**]

.. option:: -sortAllChiral <true/false>

   If set to true, when multiple chiralities are enumerated, sort
   all chiralities from best to worst per blob, otherwise sort
   chiral structures independently.  For example, if two blobs are
   found, then the output will have all chiral structures sorted from
   best fit to worst fit for the first blob, and then all chiral
   structures sorted from best fit to worst fit for the second
   blobs, etc Note that the second blob may contain better fits than the
   first.   (Note: This
   may interleave chiral structures).

   [Default=true]

.. option:: -verbose

 This is a boolean flag that controls the level of
  detail written to the log file.  By default FLYNN will only write
  minimal information to the console.
  Verbose logging will cause more information to be written to the log
  file in order to follow behavior during program execution.

  [Default=false]

.. _mtzsettings:

MTZ File Options
^^^^^^^^^^^^^^^^

The allowed MTZ map types and the corresponding column conventions are
documented in :ref:`OESystem_OEReadMTZ` in the **OEChem TK** manual.


.. option:: -autoMTZ

   Automatically try to open the mtz file using the DELWT and
   FDELWT columns from REFMAC5 mtz files.

   See :ref:`OESystem::OEMTZMapType::Fdelwt <OESystem_OEMTZMapType_Fdelwt>` for the corresponding
   difference-map type in **OEChem TK**.

   [Default=true]

.. option:: -Fc <columnname>

   Column to use for Fc.  *Note, to load arbitrary columns, you can use the **-Fc**
   and **-Phic** columns and the **Fc** maptype.*

   [Default=FC]

.. option:: -Fdelwt <columnname>

   Column to use for Fdelwt or difference map amplitudes

   See :ref:`OESystem::OEMTZMapType::Fdelwt <OESystem_OEMTZMapType_Fdelwt>` in **OEChem TK** for map
   type details.

   [Default=DELFWT]

.. option:: -Fobs <columnname>

   Column to use for FObs.

   [Default=F]

   [Aliases=**-Fo**]

.. option:: -Phi <columnname>

   Column to use for Phi.

   [Default=PHI]

.. option:: -Fwt <columnname>

   Column to use for Fwt or regular map amplitudes.

   See :ref:`OESystem::OEMTZMapType::Fwt <OESystem_OEMTZMapType_Fwt>` in **OEChem TK** for map
   type details.

   [Default=FWT]

.. option:: -Phic <columnname>

   Column to use for Phic.

   [Default=PHIC]

.. option:: -Phidelwt <columnname>

   Column to use for Phdelwt or difference map phases.

   [Default=PHDELWT]


.. option:: -Phiwt <columnname>

   Column to use for Phwt or regular map phases.

   [Default=PHWT]

.. option:: -SigmaA <columnname>

   Column to use for SigmaA.

.. option:: -mtype

   The map type to use for fitting. Fo-Fc, Fc, 2Fo-Fc, 3Fo-Fc, Fwt,
               Fdelwt...

   See :ref:`OESystem_OEReadMTZ` for the full list of map types and
   their MTZ-column interpretation.

   [Default=Fdelwt]

.. _flynnadvanced:

Advanced Options
^^^^^^^^^^^^^^^^

.. option:: -ciftype

  Specify the format of the refinement dictionary.  Legal values for refinement dictionaries
  are 'refmac', 'phenix' and 'buster'.  Refinement dictionaries are always
  written out using the designation specified in the '-split' command.
  For best results, use -split when writing out cif files when using FLYNN.

.. option:: -flipper

  Force enumeration of all stereochemical
  centers.  Otherwise, only missing stereo chemistry will be
  enumerated.

  [Default=false]

.. option:: -overlays

  Set the number of initial rigidly fit overlays to optimize
  into density.

  [Default=10]

.. _precheck:

.. option:: -precheck

  Perform only a preliminary check of the data
  to see if fitting is possible.  (This flag is meaningless without
  the -reporthtml flag).

  [Default=false]

.. option:: -reporthtml

  Generate an html report of the fitting
  process.  This is a useful first step to verify the data.  It also
  includes a 2D image of the ligand that is being fit in order to
  verify bond orders.  All output of FLYNN will be captured in
  the specified html file.

.. option:: -residues

  Comma separated list of residues to use as
  distance constraints.  If residues are specified, the
  *-distance* flag will use the residues to reject blobs that are
  too far away.  Note that with a residue list, the distance computed
  is a minimum distance, not an average distance.  Residues must be
  specified as <residue number><chain id>.  For example: 120C,134C.
  On Windows, double quotes must be added to specify two or more
  residues, i.e. -residues "120C,134C".

.. option:: -rms

  If the input ligand has 3D coordinates, this
  calculates the RMS distance to the ligand and records it in the
  molecule.  If -split is on, it also records it in the
  file name.

  [Default=false]

.. option:: -split

  Split the result into different files.  Each
  filename is annotated with the resulting shape score so that when
  the output directory is listed alphabetically, the best scores will
  be displayed in order.  In the case where the output format is pdb
  the ligand fitting results are written in REMARK statements at the
  top of the file.

  The splits are labeled as follows outputname_n###_b###_s###_c###
  where n### is the number of the ordered results, b### is the blob
  for the result, s### is the stereovariant and c### is the number
  of the conformer fit as ordered by MMFF/Shape.

  [Default=false]


.. option:: -suppressH

  By default FLYNN outputs hydrogens of
  the resulting poses.  Setting this to true will not output
  hydrogens.  It is always recommended to output hydrogrens
  for ligands in order to keep their chemistry the same
  as flynn's internal optimizer.  Only suppress hydrogens
  if your refinement package doesn't handle hydrogen
  names correctly.

  [Default=false]

.. option:: -fix_serial_numbers

  Force serial numbers to be unique when writing out the resulting
  pdb file for use in the refinement package.  This is usually
  caused by adding hydrogens to the ligand outside of the context
  of the protein and then using it in conjunction with the original
  PDB structure.

  [Default=false]

Fragment Fitting Options
^^^^^^^^^^^^^^^^^^^^^^^^

.. _fragment:

.. option:: -blobTanimoto

      Density is searched for each input ligand.  This flag
      sets the minimum tanimoto overlap for which to consider two
      blobs the same.  When pruning similar blobs, the larger is
      taken.

      [Default=0.45]

      [Aliases=**-bt**]

.. option:: -sortBy

    Choose the fragment sorting function, tanimoto, rscc (real space
    correlation coefficient), plp (piecewise linear potential) or
    chemscore.

    The fragments are fit in the normal fashion (tanimoto), but then
    re-scored and sorted using the chosen metric.

    [Default=rscc]


3D Construction Options
^^^^^^^^^^^^^^^^^^^^^^^
These are advanced conformer generation parameters.  Normally, they do
not need to be adjusted.  Please consult the OMEGA_ manual for
assistance:

.. _OMEGA: http://www.eyesopen.com/docs/omega/current/html/index.html

.. option:: -ewindow

  Controls the MMFF energy window when generating initial conformations.
  Normally, this setting does not need to be adjusted, however in some
  cases large floppy molcules may require an adjustment.  This setting
  is in kcals/mol.

  [Default=15.0]
