modify
========================

.. contents::
  :local:

This task is used to modify the residues of the input molecule.

Arguments
-------------

.. option:: -i, --in

  .. list-table::
    :stub-columns: 1
       
    * - Mandatory
      - Yes
    * - Argument
      - PDB filename or XYZ filename
    * - Default
      - None
  
  Give the input molecule.

.. option:: -t, --top

  .. list-table::
    :stub-columns: 1
       
    * - Mandatory
      - Yes
    * - Argument
      - PSF filename
    * - Default
      - None
  
  Give the input topology.

.. option:: -o, --out

  .. list-table::
    :stub-columns: 1
       
    * - Mandatory
      - No
    * - Argument
      - A filename prefix
    * - Default
      - None
  
  Give the output filename prefix. If not given, the molecule and topology will be written to ``x-modify.pdb`` and ``x-modify.psf``, respectively.

.. option:: --add-rtfs

  .. list-table::
    :stub-columns: 1
       
    * - Mandatory
      - No
    * - Argument
      - Additional residue topology files.
    * - Default
      - None
  
  Give additional residue topology files (RTF), path can be included.

  By default, pdbtop will load RTF files in ``data/``. If you want to add your own ones, you can use this option.

  Example:

  .. code-block:: bash

    # Add 2 topology files: ``my-topology1.rtf`` and ``/usr/data/my-topology2.rtf``.
    $ pdbtop topol -i 3kab-protein.pdb -o 3kab-topol --add-rtfs "my-topology1.rtf /usr/data/my-topology2.rtf"

.. option:: Modifications

   In the following table, the modifications are listed.

   .. list-table::
      :stub-columns: 1
          
      * - ``--mml``
        - Mono-Methyl-Lysine
        - Lysine
      * - ``--dml``
        - Di-Methyl-Lysine
        - Lysine
      * - ``--tml``
        - Tri-Methyl-Lysine
        - Lysine
      * - ``--mma``
        - Mono-Methyl-Arginine
        - Arginine
      * - ``--adma``
        - Asymmetric Di-Methyl-Arginine
        - Arginine
      * - ``--sdma``
        - Symmetric Di-Methyl-Arginine
        - Arginine
      * - ``--pho``
        - Phosphorylation
        - Serine, Threonine, Tyrosine
      * - ``--my-mod``
        - User-defined modification
        - Any residue

   For ``--my-mod``, please refer to :doc:`tutorial-6`, which shows how to define your own modification.
   
.. option:: --mutate

   .. list-table::
      :stub-columns: 1

    * - Mandatory
      - No
    * - Argument
      - A set of mutations, like "17A SER 34A ALA"
    * - Default
      - None

  Mutate a residue to another one. 
   
  Example:

  .. code-block:: bash

    # Mutate residue 17 at chain A (which is an arginine) to serine.
    $ pdbtop modify -i 3kab.pdb -t 3kab.psf -o 3kab-R17S --mutate "17A SER" 
    # Do 2 mutations.
    $ pdbtop modify -i 3kab.pdb -t 3kab.psf -o 3kab-M2 --mutate "17A SER 34A ALA" 

.. option:: --add-bonds

  .. list-table::
    :stub-columns: 1

    * - Mandatory
      - No
    * - Argument
      - A set of bonds, like "12 45 409 230"
    * - Default
      - None

  Add additional bonds.
   
  Example:

  .. code-block:: bash

    # Add 2 bonds: 12-45, 409-230.
    $ pdbtop modify -i 3kab.pdb -t 3kab.psf --add-bonds "12 45 409 230" -o 3kab-cov

  .. hint::

    All atom indices starts from 1.

.. option:: --del-atom

  .. list-table::
    :stub-columns: 1

    * - Mandatory
      - No
    * - Argument
      - An atom, like 12
    * - Default
      - None

  Delete an atom.
   
  Example:

  .. code-block:: bash

    # Add the 23rd atom.
    $ pdbtop modify -i 3kab.pdb -t 3kab.psf --del-atom 23 -o 3kab-del

All modifictions are done in place and can be combined. For example:

.. code-block:: bash

  $ pdbtop modify -i 3kab.pdb -t 3kab.psf --del-atom 23 --add-bonds "12 45" --mutate "17A SER" -o 3kab-mod

However, if you do modifications for the same residue, the result may be unpredictable. **You must carefully examine if the result is right!**

.. code-block:: bash
  
  # The 154th atom is in residue 17 at chain A. So, doing them together may cause problems.
  $ pdbtop modify -i 3kab.pdb -t 3kab.psf --del-atom 154 --mutate "17A SER" -o 3kab-mod