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

.. program:: writedict

.. _chapter_writedict:

******************
WriteDict
******************

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

**WriteDict** is a comprehensive refinement dictionary generator that properly handles covalent 
bond restraints between the ligand and the protein.

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

The basic usage of writedict is to take an input structure and
generate the corresponding .pdb and .cif files for input into COOT or
REFMAC5.

.. code-block:: console

   > writedict -in 1nhu.ism -out 1nhu_out

This creates the files *1nhu_out.cif* and *1nhu_out.pdb*.  The pdb is
always created since the atom names may be remapped from the input.
Since the input contains no residue information, the ligand is placed
in residue "UNL".

To add your own residue names for unmapped residues:

.. code-block:: console

   > writedict -in 1nhu.ism -out 1nhu_out -residues 153

Note that if the given residue name (153) does not map to the known
residue 153 the next residue name in the unmapped residue list will be
used.  Since none are specified it will go to the standard defaults:
"UNL,UN1,UN2..."

.. note::

 When doing whole complexes, renaming residues gets quite
 complicated since you may not know which residues will map before you
 run WRITEDICT.

.. code-block:: console

   > writedict -in 1nhu.ism -out 1nhu_out -residues LIG -nolookup

Force the residue to be named LIG.  (It will also indicate an invalid
dictionary)

.. code-block:: console

 Warning: LIG   1: Known Residue, but does not map to previous residue: LIG from: RCSB
 Warning: LIG   1: previous smiles c1ccc2c(c1)CC3=C(NN=C23)c4ccncc4
 Warning: LIG   1: current  smiles c1ccc(cc1)CC(C(=O)[O-])N(Cc2cccc(c2)C(F)(F)F)C(=O)c3ccc(cc3Cl)Cl
 Warning: LIG: Keeping residue name (dictionary may be invalid)
 Warning: LIG: Adding new residue dictionary
 Warning: LIG: already in dictionary from: RCSB but with different structure.
 Warning: LIG: c1ccc2c(c1)CC3=C(NN=C23)c4ccncc4
 Warning: LIG: c1ccc(cc1)CC(C(=O)[O-])N(Cc2cccc(c2)C(F)(F)F)C(=O)c3ccc(cc3Cl)Cl
 Warning: LIG: Overwriting existing residue (dictionary may be invalid)


To ensure planarAniline constraints consistent with the MMFF94s
forcefield, use the *-planarAniline* flag.

.. code-block:: console

   > writedict -in 1nhu.ism -out 1nhu_out -planarAniline

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

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

.. code-block:: console

   > writedict --help


will generate the following output:

::

  Help functions:
    writedict --help simple      : Get a list of simple parameters
    writedict --help all         : Get a complete list of parameters
    writedict --help <parameter> : Get detailed help on a parameter
    writedict --help html        : Create an html help file for this program

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

.. option:: -in <filename>

   File containing a molecule to be fit to density.

   [Aliases=**-prot**]

   ============   ===========================
   File type      Extension
   ============   ===========================
   SMILES         .smi .ism .smi.gz .ism.gz
   ------------   ---------------------------
   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:: -out <filename prefix>

  This specifies a prefix for outputting the
  refinement dictionary **.cif** or **.xplor** and the **pdb** file.
  The pdb file ( and pdb.oeb) is always
  output and should be used for purposes of refinement since
  WRITEDICT sometimes corrects faulty hydrogen atom names and
  will include LINK records in the pdb if covalent bonds are detected.

  The log file will also be written using this prefix as *<filename prefix>.log*.

.. option:: -prefix <filename prefix>

  Alias for *-out*

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

.. option:: -assignCCP4

  If true then CCP4 atom types will be
  assigned to the output pdb file.

  [Default=true]

.. option:: -includeRotors

  Set to true if the output should include
  rotor torsion terms.  If this is set to false, refinement programs
  will not be able to modify any rotors.

  [Default=true]

.. option:: -suppressH

  If true, no hydrogens are output.

  [Default=false]

.. option:: -dictionary_type

   Selects the output refinement dictionary format:

   ==========   =====================================
   Value        Meaning
   ==========   =====================================
   0 / refmac   REFMAC5 dictionary (default)
   1 / xplor    CNS/CNX (XPLOR) dictionary
   2 / phenix   PHENIX dictionary
   3 / buster   BUSTER dictionary
   ==========   =====================================

   [Default=refmac]

   [Aliases=**-type**]

.. _planarAniline:

.. option:: -planarAniline

   Use the MMFF94s variant of the MMFF94
   forcefield.  This forcefield emulates time-averages structures
   observed in crystallographic and other structure determination
   methods.

   The MMFF94s forcefield is a variant of MMFF94 that emulates
   time-averages structures typically observed during crystallographic
   structure determination, mainly planar geometries at unstrained
   delocalized trigonal nitrogen centers.  However, there are many theoretical studies
   that show puckering at nitrogen centers. (see MMFF VI. in JCICS)

   That being said, due to the prevalence of crystallographic studies,
   many chemist erroneously consider the time-averaged structure to be
   correct, hence this variant is available for use.

   [Default=true]

   [Aliases=**-mmff94s**]

.. option:: -strict

   Change the known residue matching mode.

   Options available for residue matching is as follows:

    =============   ==========================================================
    Option          Meaning
    =============   ==========================================================
    exact           Known residue and input residue graphs must match exactly.
    -------------   ----------------------------------------------------------
    substructure    Input residue may be a substructure of the known residue.

                    **Cannot be used with the exact flag.**
    -------------   ----------------------------------------------------------
    fuzzybonds      Bond orders do not need to match
    -------------   ----------------------------------------------------------
    atomname        Atom names must match
    =============   ==========================================================

   Options are separated by colons.  The default settings are set to
   limit the number of REFMAC5 issues.  -strict exact:substructure
   will find more matches, but increases the risk of REFMAC5 rejecting
   the dictionary.

   [Default=substructure:fuzzybonds]

.. option:: -lookup

  Attempts to lookup residues from the internal dictionary store
  using the current -strict status.  This is useful to find out
  if a residue has already been deposited in the RCSB.

  If -lookup is not set, mismatching residues will be given new
  names. [Default=false]

.. option:: -forceExistingResidueNames

   Force WRITEDICT to use the given residues, even if they do not match
   the deposited residues from the RCSB.

   [Default=false]

   [Aliases=**-nolookup**,**-force**]

.. option:: -writeFullDict

  If true then all refinement dictionaries
  are created for all residues.  If false only residues that are
  unknown or are in the set of replaceable residues
  or covalently bound to a ligand are output.  Setting this to
  true can confuse REFMAC5.

  {default=false]

.. option:: -residues

   Comma-separated list of default residue names to assign to unknown
   components.

   [Aliases=**-resnames**,**-res**]

.. option:: -split

   Split separate molecules (and bonded covalent structures) into
   different dictionaries. [Default=false]

.. option:: -fix_serial_numbers

   Fix serial numbers if there are duplicates in the input files.
   [Default=false]

.. option:: -fixResidueHydrogens

   If a residue has more hydrogens than the known dictionary entry,
   remove them. [Default=false]

.. option:: -fixups

   Set fixups for known bugs in refinement packages. Accepts a
   comma-separated list. Supported value: ``REFMAC560117_MODRES``
   (fixes LINK issues in CCP4 6.2.0 REFMAC5.6.0117; should be used
   with ``MAKE CONNECTIVITY YES``).

.. option:: -verbose

  Output copious information of how writedict operates. [Default=false]

