Tutorial 6: Define My Own Modification
================================================

.. contents::
  :local:

In this tutorial, we will show you how to use pdbtop to define your own modification that are not yet supported by pdbtop.

Prepare a RTF File
--------------------------

Assume we want to define a modification called "ethylation" for lysine, we can prepare a file called ``my.rtf`` with following content:

.. code-block:: bash
  :caption: my.rtf
  :linenos:
  :emphasize-lines: 1,2,4,11,12,17
  
  PRES EL           0.33 !
  ATOM NZ   NH3    -0.30 !        HF1   HI2
  ATOM CF   CT2     0.06 !        |     |
  ATOM HF1  HA      0.09 !    HF2-CF--CF2--HI1   
  ATOM HF2  HA      0.09 !       /       \
  ATOM CF2  CT3    -0.18 !  CE--NZ--HZ2   HI3
  ATOM HI1  HA      0.09 !       \ 
  ATOM HI2  HA      0.09 !       HZ3
  ATOM HI3  HA      0.09 !
  GROUP                  !
  DELETE ATOM HZ1        !
  BOND NZ CF CF HF1 CF HF2 CF CF2
  BOND CF2 HI1 CF2 HI2 CF2 HI3
  IC  CD   CE  NZ   CF    1.5350 110.4600  179.9200 110.0200  1.4604
  IC  CE   NZ  CF  HF1    0.0000  0.0000  -173.6500 110.8500  1.1104
  IC  HF1  NZ  CF  HF2    0.0000  0.0000   119.5100 110.4100  1.1109
  IC  HF1  NZ  CF  CF2    0.0000  0.0000  -120.3900 111.1100  1.5300
  IC  NZ   CF  CF2 HI1    0.0000  0.0000  -179.5100 110.4100  1.1109
  IC  HI1  CF  CF2 HI2    0.0000  0.0000   119.5100 110.4100  1.1109
  IC  HI1  CF  CF2 HI3    0.0000  0.0000  -119.5100 110.4100  1.1109

The residue ``EL`` defines how to modify lysine to obtain an "ethylated" lysine. In ``my.rtf``, you can define arbitrary number of modifications.

Here we explain how this "ethylation" is realized:

- Everything after ``!`` is comment.
- ``PRES EL           0.33``: defines a patch called ``EL``. ``0.33`` is not used.
- ``ATOM NZ   NH3    -0.30``: ``NZ`` is already defined in ``LYS`` (defined in ``data/top_all36_prot.rtf``). This statement modifies atomic type (``NH3``) and charge (``-0.30``).
- ``ATOM HF1  HA      0.09``: ``HF1`` is a new atom. For new atoms, the name can be arbitrary, as long as it is unique within this residue.
- ``DELETE ATOM HZ1``: Delete atom ``HZ1`` in ``LYS``.
- ``BOND NZ CF CF HF1 CF HF2 CF CF2``: defines 3 bonds: ``NZ``-\ ``CF``, ``CF``-\ ``HF1``, ``CF``-\ ``HF2``, and ``CF``-\ ``HF3``.
- ``IC  HF1  NZ  CF  CF2    0.0000  0.0000  -120.3900 111.1100  1.5300``: defines the coordinate of the last atom in Z-matrix: bond ``CF2``-\ ``CF``: ``1.5300``; angle ``CF2``-\ ``CF``-\ ``NZ``: ``111.1100``; dihedral ``CF2``-\ ``CF``-\ ``NZ``-\ ``HF1``: ``-120.390000``.

Do Modification
-----------------------

Assume we have a protein structure ``5vbm-4.pdb`` and its topology ``5vbm-4.psf`` (see :doc:`tutorial-1`), and we want to perform this ethylation for the residue LYS5 at chain A, then we can use the following command:

.. code-block:: bash

  $ pdbtop modify -i 5vbm-4.pdb -t 5vbm-4.psf -o 5vbm-mod --add-rtfs my.rtf --my-mod "EL 5A"

Here, ``--add-rtfs`` lets pdbtop read ``my.rtf`` to load user-defined residues or patches, and ``--my-mod`` means apply ``EL`` to residue 5 at chain A. The result is shown below:

.. image:: _static/figs/p17.png