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

.. oe:namespace:: OEModels

.. meta::
   :keywords: OEROCSQueryModelBuilder, ROCSQueryModelBuilder


.. _OEModels_OEROCSQueryModelBuilder:

.. oe:class:: OEROCSQueryModelBuilder

   .. attention::

      |PRELIMINARY-API|

   .. oe:api::

      class OEROCSQueryModelBuilder
      
   The :ref:`OEROCSQueryModelBuilder <OEModels_OEROCSQueryModelBuilder>` is used to build models of
   :ref:`OEShapeQuery <OEShape_OEShapeQuery>` that can be used as reference systems for
   **ROCS**, :ref:`OEROCS <OEShape_OEROCS>`, :ref:`OEOverlay <OEShape_OEOverlay>`,
   and other similar functions.

   The :ref:`OEROCSQueryModelBuilder <OEModels_OEROCSQueryModelBuilder>` can be used for building a query
   from known ligands in their binding modes. The input ligands should be prepared by 
   aligning the protein crystal structures. The prepared :ref:`OEDesignUnit <OEBio_OEDesignUnit>`
   structures can be used directly, or the ligands can be extracted and used, as input
   to the query model builder. The query model builder constructs a ROCS query employing 
   a few of the ligands that are most representative of the set as a whole.

   The :ref:`OEROCSQueryModelBuilder <OEModels_OEROCSQueryModelBuilder>` class defines the following public methods:
    * :oe:meth:`AddLigand<OEModels::OEROCSQueryModelBuilder::AddLigand>`
    * :oe:meth:`Build<OEModels::OEROCSQueryModelBuilder::Build>`
    * :oe:meth:`ClearLigands<OEModels::OEROCSQueryModelBuilder::ClearLigands>`
    * :oe:meth:`GetROCSQueryModelOptions<OEModels::OEROCSQueryModelBuilder::GetROCSQueryModelOptions>`
    * :oe:meth:`SetLigands<OEModels::OEROCSQueryModelBuilder::SetLigands>`


   .. oe:method:: Constructor

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEROCSQueryModelBuilder(const OEROCSQueryModelOptions& options = OEROCSQueryModelOptions())
            OEROCSQueryModelBuilder(const OEROCSQueryModelBuilder&)

      .. oe:language:: python

         .. oe:api:: python

            OEROCSQueryModelBuilder(options: OEROCSQueryModelOptions = OEROCSQueryModelOptions()) -> OEROCSQueryModelBuilder
            OEROCSQueryModelBuilder(arg2: OEROCSQueryModelBuilder) -> OEROCSQueryModelBuilder

      Constructors.

      *options*
         Options for the model builder. Default options are used if not provided.

   .. oe:method:: operator=
      :language: c++

      .. oe:api::

         OEROCSQueryModelBuilder &operator=(const OEROCSQueryModelBuilder &)

      Assignment operator.


   .. oe:method:: AddLigand

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool AddLigand(const OEBio::OEDesignUnit& du)
            bool AddLigand(const OEChem::OEMolBase& mol)

      .. oe:language:: python

         .. oe:api:: python

            AddLigand(du: OEDesignUnit) -> bool
            AddLigand(mol: Union[OEGraphMol,OEMol,OEQMol]) -> bool

      Adds the specified ligand to the set of ligands from which the query model(s) would be build.
      The first overload of the method adds the bound ligand from the design unit. Method returns ``True``
      if a ligand is added successfully.

   .. oe:method:: Build

      .. oe:language:: c++ java csharp

         .. oe:api::

            OESystem::OEIterBase<OEShape::OEShapeQuery>* Build(OESystem::OETracerBase* tracer = &OESystem::NullTracer)

      .. oe:language:: python

         .. oe:api:: python

            Build(tracer: OETracerBase = &NullTracer) -> Iterable[OEShapeQuery]

      Build the query model(s). Method returns an iterator over the generated :ref:`OEShapeQuery <OEShape_OEShapeQuery>`.

   .. oe:method:: ClearLigands

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool ClearLigands()

      .. oe:language:: python

         .. oe:api:: python

            ClearLigands() -> bool

      Clears set of ligands from which the query model(s) would be build. Method returns ``True``
      if all the ligands are removed successfully.

   .. oe:method:: GetROCSQueryModelOptions

      .. oe:language:: c++ java csharp

         .. oe:api::

            const OEROCSQueryModelOptions& GetROCSQueryModelOptions() const

      .. oe:language:: python

         .. oe:api:: python

            GetROCSQueryModelOptions() -> OEROCSQueryModelOptions

      Get the :ref:`OEROCSQueryModelOptions <OEModels_OEROCSQueryModelOptions>` associated with this builder.

   .. oe:method:: SetLigands

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool SetLigands(OEChem::oemolistream& ifs)
            bool SetLigands(OEPlatform::oeistream& ifs)

      .. oe:language:: python

         .. oe:api:: python

            SetLigands(ifs: oemolistream) -> bool
            SetLigands(ifs: oeistream) -> bool

      Sets the ligands from which the query model(s) would be build. Calling this method would
      clear any existing ligand that were previously added. The first overload adds all the 
      :ref:`OEMolBase <OEChem_OEMolBase>` from the specified :ref:`oemolistream <OEChem_oemolistream>`, and the
      second overload adds the bound ligands from all the :ref:`OEDesignUnit <OEBio_OEDesignUnit>` of the
      specified :ref:`oeistream <OEPlatform_oeistream>`. Method returns ``True``
      if ligands are added successfully.
