.. _chapter_mdlquery:

********************************************************************************
MDL Query Depiction
********************************************************************************

In order to depict an MDL query the query molecule has to be imported by
calling the :oe:func:`OEChem::OEReadMDLQueryFile` function.
The rest of the process is identical to depicting a molecule.
First the :oe:func:`OEDepict::OEPrepareDepiction` function has to be
called to generate the 2D atom coordinates, then the image can be
created by rendering the molecule (:oe:func:`OEDepict::OERenderMolecule`).

.. oe:source:: DepictMDLQuery.py
   :language: python
   :refnum:   1
   :caption:  Example of MDL query depiction
   :frag:     SNIPPET-DEPICTMDLQUERY

.. oe:source:: DepictMDLQuery.cpp
   :language: c++
   :refnum:   1
   :caption:  Example of MDL query depiction
   :frag:     SNIPPET-DEPICTMDLQUERY

.. oe:source:: DepictMDLQuery.java
   :language: java
   :refnum:   1
   :caption:  Example of MDL query depiction
   :frag:     SNIPPET-DEPICTMDLQUERY

.. oe:source:: DepictMDLQuery.cs
   :language: csharp
   :refnum:   1
   :caption:  Example of MDL query depiction
   :frag:     SNIPPET-DEPICTMDLQUERY


.. seealso::

   * :oe:func:`OEChem::OEReadMDLQueryFile` function in the **OEChem TK** manual
   * :ref:`Table: Summary of supported MDL query features<table_mdlqueries_summary>`

Atom Query Features
================================================================================

The depiction of the following MDL atom query features is supported:

#.  The 8th column in the atom block in the V2K format
    file (or ``HCOUNT=`` in the V3K format file) is used to
    define the number of allowed hydrogens for an atom.
    (See examples in :ref:`Table: Example of depicting hydrogen count<table_molquery_hcount>`)

       - ``(H0)`` means no hydrogen atoms allowed unless explicitly drawn.
       - ``(Hn)`` means atom must have ``n`` or more implicit hydrogen(s)

    .. _table_molquery_hcount:

    .. list-table:: **Examples of depicting hydrogen count**
       :widths: 100 100 100
       :header-rows: 1

       * - query
         -
         -
       * - .. image:: images/MDLHCount-01-query.*
             :align:  center
         - .. image:: images/MDLHCount-01-match-0.*
             :align:  center
         - .. image:: images/MDLHCount-01-match-1.*
             :align:  center
       * - .. image:: images/MDLHCount-02-query.*
             :align:  center
         - .. image:: images/MDLHCount-02-match-0.*
             :align:  center
         - .. image:: images/MDLHCount-02-match-1.*
             :align:  center


#.  Query atom types:

    - ``A`` = any atom type except hydrogen
    - ``Q`` = any atom type except hydrogen and carbon
    - ``L`` = atom list

    The ``M  ALS`` line in the property block in the V2K
    format file ( or ``[aaa,bbb,..]`` in the V3K format)
    is used to list alternative atom types for an atom.
    (See examples in :ref:`Table: Examples of depicting query atom types<table_molquery_queryatom>`)

    .. _table_molquery_queryatom:

    .. list-table:: **Examples of depicting query atom types**
        :widths: 100 100 100 100
        :header-rows: 1

        * - query
          - target
          - target
          - target
        * - .. image:: images/MDLGenericAtom-01-query.*
               :align:  center
          - .. image:: images/MDLGenericAtom-01-match-0.*
               :align:  center
          - .. image:: images/MDLGenericAtom-01-match-1.*
               :align:  center
          - .. image:: images/MDLGenericAtom-01-match-2.*
               :align:  center
        * - .. image:: images/MDLGenericAtom-02-query.*
               :align:  center
          - .. image:: images/MDLGenericAtom-02-match-0.*
               :align:  center
          - .. image:: images/MDLGenericAtom-02-match-1.*
               :align:  center
          - .. image:: images/MDLGenericAtom-02-match-2.*
               :align:  center
        * - .. image:: images/MDLGenericAtom-03-query.*
               :align:  center
          - .. image:: images/MDLGenericAtom-03-match-0.*
               :align:  center
          - .. image:: images/MDLGenericAtom-03-match-1.*
               :align:  center
          - .. image:: images/MDLGenericAtom-03-match-2.*
               :align:  center
        * - .. image:: images/MDLGenericAtom-04-query.*
               :align:  center
          - .. image:: images/MDLGenericAtom-04-match-0.*
               :align:  center
          - .. image:: images/MDLGenericAtom-04-match-1.*
               :align:  center
          - .. image:: images/MDLGenericAtom-04-match-2.*
               :align:  center


#.  ``M  CHG`` line in the property block in the V2K format file
    (or ``CHG=`` in the V3K format) is used to define atom formal
    charges.
    (See examples in :ref:`Table: Example of depicting formal charge<table_molquery_charge>`)

    .. _table_molquery_charge:

    .. list-table:: **Examples of depicting formal charge**
       :widths: 100 100 100
       :header-rows: 1

       * - query
         - target
         - target
       * - .. image:: images/MDLCharge-01-query.*
              :align:  center
         - .. image:: images/MDLCharge-01-match-0.*
              :align:  center
         - .. image:: images/MDLCharge-01-match-1.*
              :align:  center

#.  ``M  RBC`` line in the property block in the V2K format file
    (or ``RBCNT=`` in the V3K format) is used to limit the number
    of allowed ring bonds attached to an atom.
    (See examples in :ref:`Table: Example of depicting ring count<table_molquery_ringcount>`)

       - ``(r0)`` means no ring bond allowed
       - ``(r*)`` means as drawn
       - ``(rn)`` means ``n`` number of ring bonds allowed

    .. _table_molquery_ringcount:

    .. list-table:: **Examples of depicting ring count**
       :widths: 100 100 100
       :header-rows: 1

       * - query
         - target
         - target
       * - .. image:: images/MDLRingCount-01-query.*
              :align:  center
         - .. image:: images/MDLRingCount-01-match-0.*
              :align:  center
         - .. image:: images/MDLRingCount-01-match-1.*
              :align:  center
       * - .. image:: images/MDLRingCount-02-query.*
              :align:  center
         - .. image:: images/MDLRingCount-02-match-0.*
              :align:  center
         - .. image:: images/MDLRingCount-02-match-1.*
              :align:  center


#.  ``M  SUB`` line in the property block in the V2K format file
    (or ``SUBST=`` in the V3K format) is used to set the number
    of allowed substitutions of an atom.
    (See examples in :ref:`Table: Examples of depicting substitution count<table_molquery_subcount>`)

       - ``(s0)`` means no substitution allowed
       - ``(s*)`` means as drawn
       - ``(sn)`` means ``n`` number of substitution(s) allowed

    .. _table_molquery_subcount:

    .. list-table:: **Examples of depicting substitution count**
       :widths: 100 100 100
       :header-rows: 1

       * - query
         - target
         - target
       * - .. image:: images/MDLSubCount-01-query.*
              :align:  center
         - .. image:: images/MDLSubCount-01-match-0.*
              :align:  center
         - .. image:: images/MDLSubCount-01-match-1.*
              :align:  center
       * - .. image:: images/MDLSubCount-02-query.*
              :align:  center
         - .. image:: images/MDLSubCount-02-match-0.*
              :align:  center
         - .. image:: images/MDLSubCount-02-match-1.*
              :align:  center

#.  ``M  UNS`` line in the property block in the V2K format file
    (or ``UNSAT=`` in the V3K format) is used to specify whether
    or not an atom is unsaturated, *i.e.*, having at least one multiple bond.
    (See examples in :ref:`Table: Examples of depicting unsaturated property<table_molquery_unsaturated>`)

    .. _table_molquery_unsaturated:

    .. list-table:: **Examples of depicting unsaturated property**
       :widths: 100 100 100
       :header-rows: 1

       * - query
         - target
         - target
       * - .. image:: images/MDLUnsaturated-01-query.*
              :align:  center
         - .. image:: images/MDLUnsaturated-01-match-0.*
              :align:  center
         - .. image:: images/MDLUnsaturated-01-match-1.*
              :align:  center

Bond Query Features
================================================================================

The depiction of the following MDL bond query features is supported:

#.  Alternative bond types in the bond block (4 = aromatic, 5 = single or double,
    6 = single or aromatic, 7 = double or aromatic, 8 = any bond).
    (See examples in :ref:`Table: Examples of depicting query bond types<table_molquery_querybond>`)

    .. _table_molquery_querybond:

    .. list-table:: **Examples of depicting query bond types**
        :widths: 100 100 100 100
        :header-rows: 1

        * - query
          - target
          - target
          - target
        * - .. image:: images/MDLGenericBond-01-query.*
               :align:  center
          - .. image:: images/MDLGenericBond-01-match-0.*
               :align:  center
          - .. image:: images/MDLGenericBond-01-match-1.*
               :align:  center
          - .. image:: images/MDLGenericBond-01-match-2.*
               :align:  center
        * - .. image:: images/MDLGenericBond-02-query.*
               :align:  center
          - .. image:: images/MDLGenericBond-02-match-0.*
               :align:  center
          - .. image:: images/MDLGenericBond-02-match-1.*
               :align:  center
          - .. image:: images/MDLGenericBond-02-match-2.*
               :align:  center
        * - .. image:: images/MDLGenericBond-03-query.*
               :align:  center
          - .. image:: images/MDLGenericBond-03-match-0.*
               :align:  center
          - .. image:: images/MDLGenericBond-03-match-1.*
               :align:  center
          - .. image:: images/MDLGenericBond-03-match-2.*
               :align:  center

    .. seealso::

       * :oe:constns:`OEDepict::OEBondDisplayType` namespace

#.  The 6th column in the atom block in the V2K format file
    ( or ``TOPO=`` in the V3K format) describes bond topology.
    (See examples in :ref:`Table: Examples of depicting bond topology<table_molquery_topology>`)

       - ``(rn)`` means that it can only mapped to ring bond
       - ``(ch)`` means that it can only mapped to chain bond

    .. _table_molquery_topology:

    .. list-table:: **Examples of depicting bond topology**
       :widths: 100 100 100
       :header-rows: 1

       * - query
         - target
         - target
       * - .. image:: images/MDLTopology-01-query.*
              :align:  center
         - .. image:: images/MDLTopology-01-match-0.*
              :align:  center
         - .. image:: images/MDLTopology-01-match-1.*
              :align:  center
       * - .. image:: images/MDLTopology-02-query.*
              :align:  center
         - .. image:: images/MDLTopology-02-match-0.*
              :align:  center
         - .. image:: images/MDLTopology-02-match-1.*
              :align:  center

#.  Double bond stereochemistry is considered if both ends of
    the bond are marked with *stereo care* flags in the atom block
    in the V2K format file ( or ``STBOX=`` in the V3K format).
    (See examples in :ref:`Table: Examples of depicting bond stereo care<table_molquery_bondstereo>`)

    .. _table_molquery_bondstereo:

    .. list-table:: **Examples of depicting bond stereo care**
       :widths: 100 100 100
       :header-rows: 1

       * - query
         - target
         - target
       * - .. image:: images/MDLBondStereo-01-query.*
              :align:  center
         - .. image:: images/MDLBondStereo-01-match-0.*
              :align:  center
         - .. image:: images/MDLBondStereo-01-match-1.*
              :align:  center
       * - .. image:: images/MDLBondStereo-02-query.*
              :align:  center
         - .. image:: images/MDLBondStereo-02-match-0.*
              :align:  center
         - .. image:: images/MDLBondStereo-02-match-1.*
              :align:  center

.. seealso::

   * :ref:`section_examples_summary_mdlquery2img` example


R-group Depiction
================================================================================

**OEDepict TK** can also depict R-group information by interpreting the ``M  RGP``
line in the property block of an MDL file
(See examples in :ref:`Table: Examples of depicting R-groups <table_molquery_rgroup>`)

.. _table_molquery_rgroup:

.. list-table:: **Examples of depicting R-groups**
   :widths: 100 100
   :header-rows: 0

   * - .. image:: images/RGroup-01.*
          :align:  center
     - .. image:: images/RGroup-02.*
          :align:  center



