.. include:: ../../toolkit-substitutions

.. oe:namespace:: OEChem

.. oe:constnamespace:: OESubSearchScreenType

   .. attention::

      |TWOLANGUAGE|

   The :ref:`OESubSearchScreen <OEChem_OESubSearchScreen>` objects are typed bit-vectors.
   The type of a screen determines what kind of queries in mind the screen was
   designed.

   In **OEChem TK**, a query molecule (:ref:`OEQMolBase <OEChem_OEQMolBase>`) can be
   constructed in three different ways.

   .. list-table::
      :widths: 50 100 100 150
      :header-rows: 1

      * - Screen Type
        - Description
        - Initialize
        - See Also

      * - :oe:const:`OEChem::OESubSearchScreenType::MDL`
        - query read from MDL query file
        - :oe:func:`OEChem::OEReadMDLQueryFile`
        - :ref:`chapter_mdlqueries`

      * - :oe:const:`OEChem::OESubSearchScreenType::Molecule`
        - query built from molecule
        - :oe:meth:`BuildExpressions<OEChem::OEQMolBase::BuildExpressions>`
        -

      * - :oe:const:`OEChem::OESubSearchScreenType::SMARTS`
        - query built from SMARTS pattern
        - :oe:func:`OEChem::OEParseSmarts`
        - :ref:`chapter_SMARTS`

   The expression trees of the queries that are initialized from different sources
   can be significantly different.
   For example, the "language" of :term:`SMARTS` is the most expressive one allowing
   complex logical operations and recursive patterns.
   A :term:`SMARTS` such as ``[NX3;H2,H1;!$(NC=O)]`` (primary or secondary amine that is not in amide)
   defines a substructure that can not be expressed using MDL query features.
   This also makes queries built from :term:`SMARTS` the most complex ones.
   The other major difference between :term:`SMARTS` and MDL queries is the way how they
   are expected to match aromaticity. For these reasons, **OEChem TK** provides three
   different screen types especially designed for the three different ways that are
   available to built query molecules using **OEChem TK**.

   .. note::

      For performance reason, **OEChem TK** does not support screening-based fast substructure
      search with explicit hydrogens.
      The :oe:func:`OEChem::OEMakeSubSearchTargetScreen` function automatically suppresses explicit
      hydrogens of the molecule prior to the screen generation.
      The :oe:func:`OEChem::OEMakeSubSearchQueryScreen` function will return ``false`` if the query
      molecule has any explicit hydrogen expression.

   .. oe:constant:: Default

      The default screen type is :oe:const:`OEChem::OESubSearchScreenType::MDL`.

   .. oe:constant:: MDL

      .. oe:language:: c++ python

         The following code snippet shows how to create
         :oe:const:`OEChem::OESubSearchScreenType::MDL` screens.

         .. oe:source:: MakeMDLScreen.cpp
            :language: c++
            :noindent:
            :frag:     SNIPPET

         .. oe:source:: MakeMDLScreen.py
            :language: python
            :noindent:
            :frag:     SNIPPET

   .. oe:constant:: Molecule

      .. oe:language:: c++ python

         The following code snippet shows how to create
         :oe:const:`OEChem::OESubSearchScreenType::Molecule` screens.
         The query molecule is created from a "real" molecule using
         the :oe:meth:`BuildExpressions<OEChem::OEQMolBase::BuildExpressions>`
         method.

         .. oe:source:: MakeMoleculeScreen.cpp
            :language: c++
            :noindent:
            :frag:     SNIPPET

         .. oe:source:: MakeMoleculeScreen.py
            :language: python
            :noindent:
            :frag:     SNIPPET

      .. note::

         * It is highly recommended to use the :oe:const:`OEChem::OEExprOpts::DefaultAtoms` and
           :oe:const:`OEChem::OEExprOpts::DefaultBonds` options when building the query molecule
           with the :oe:meth:`BuildExpressions<OEChem::OEQMolBase::BuildExpressions>`.
           When using other option combinations, the built query molecule  might not be suitable
           for the :oe:const:`OEChem::OESubSearchScreenType::Molecule` screen type.

         * If the input molecule has any explicit hydrogens, the
           :oe:func:`OEChem::OESuppressHydrogens` function should be called prior to calling
           :oe:meth:`BuildExpressions<OEChem::OEQMolBase::BuildExpressions>`.

   .. oe:constant:: SMARTS

      .. oe:language:: c++ python

         The following code snippet shows how to create
         :oe:const:`OEChem::OESubSearchScreenType::SMARTS` screens.

         .. oe:source:: MakeSMARTSScreen.cpp
            :language: c++
            :noindent:
            :frag:     SNIPPET

         .. oe:source:: MakeSMARTSScreen.py
            :language: python
            :noindent:
            :frag:     SNIPPET

   .. hint::

      In case of a query molecule of unknown source, the
      :oe:func:`OEChem::OEIsComplementaryScreenType` function can be used to check
      whether the query molecule is suited for a specific screen type.

   .. oe:constant: Unknown # IGNORING DOCUMENTATON

   .. seealso::

      * :oe:func:`OEChem::OEMakeSubSearchQueryScreen` and
        :oe:func:`OEChem::OEMakeSubSearchTargetScreen` functions

   .. admonition:: Code Example

      * :ref:`section_example_oechem_makefastss` example
      * :ref:`section_example_oechem_searchfastss` example
