.. include:: ../../toolkit-substitutions
.. include:: ../../common/cookbook/cookbook-hyperlinks

.. oe:namespace:: OEChem

.. _OEChem_OEMonomerSet:

.. oe:class:: OEMonomerSet

   .. attention::

      |PRELIMINARY-API|

   .. oe:api::

      class OEMonomerSet

   A container class that stores monomer definitions.

   There are two built in monomer set supported by OEChem
   
   - "Standard" - contains 20 standard amino acid in the code-set named `Standard` 
   - "OpenEye" - contains more than 200 diverse monomers in defined in four code-sets named: ``OpenEye``, ``Standard``, ``PDB`` and ``ChEMBL``

   A monomer has to be defined in at least one code-set. In a code-set each monomer has to have a unique name, 
   built different code set can a monomer cna be named differently.

   .. list-table:: **Example of monomer codes in the built-in OpenEye monomer-set**
      :header-rows: 1

      * - Monomer Name
        - Code in `OpenEye` [#f1]_
        - Code in `Standard`
        - Code in `PDB`
        - Code in `ChEMBL`

      * - Alanine
        - `A`
        - `A`
        - `ALA`
        - `A`

      * - Cysteine
        - `C`
        - `C`
        - `CYS`
        - `c`

      * - D-Alanine
        - `dAla`
        - 
        - `DAL`
        - `dA`


      * - (2S)-2-amino-3-(3-pyridyl)propanoic acid
        - `3Pal`
        - 
        - `1MH`
        - `3-Pal`

   .. [#f1] OpenEye code-set following naming-convention of [Ghiandoni-2026]_


   .. only:: oehtml

      .. admonition:: Download JSON file of built-in Standard and OpenEye monomer-set

         * :download:`monomers-standard.json <../../../../../sublibs/tklibs/oechem/peptide/data/monomers-standard.json>`
           and see :oe:func:`OEChem::OELoadStandardMonomerSet` function
          
         * :download:`monomers-openeye.json <../../../../../sublibs/tklibs/oechem/peptide/data/monomers-openeye.json>`
           and see :oe:func:`OEChem::OELoadOpenEyeMonomerSet` function

   The following example shows how to generate a custom monomer set:

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

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

   The generated :oe:cls:`OEChem::OEMonomerSet`  object can be saved into a JSON file using 
   :oe:func:`OEChem::OEWriteMonomerSet` and later loaded with thee :oe:func:`OEChem::OEReadMonomerSet` function.

   .. seealso::

      * :oe:func:`OEChem::OEPerceivePeptideMonomerConnections` function
      * :oe:func:`OEChem::OEGetPolymerType` and :oe:func:`OEChem::OEGetMonomerType` functions
      * :oe:cls:`OEChem::OEMonomerData` class and :oe:func:`OEChem::OEIsValidMonomerData` function

   .. admonition:: OpenEye Python Cookbook Code Example

      * `Generating Custom Monomer Set`_ **OpenEye Python Cookbook** recipe


   .. oe:method:: Constructors

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

         .. oe:api::

            OEMonomerSet()

      .. oe:language:: python

         .. oe:api:: python

            OEMonomerSet() -> OEMonomerSet

      Constructors an empty monomer set.

   .. oe:method: operator bool # IGNORE

      .. oe:api::

         operator bool() const

   .. oe:method:: AddCodeSet

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

         .. oe:api::

            bool AddCodeSet(const std::string& codeSet)

      .. oe:language:: python

         .. oe:api:: python

            AddCodeSet(codeSet: str) -> bool

      Adds a code-set name. 

   .. oe:method:: AddMonomer

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

         .. oe:api::

            bool AddMonomer(const OEMonomerData &)

      .. oe:language:: python

         .. oe:api:: python

            AddMonomer(arg2: OEMonomerData) -> bool

      Adds a monomer (defined by in a :oe:cls:`OEChem::OEMonomerData` object) to the monomer set.
      The monomer is validated with the :oe:func:`OEChem::OEIsValidMonomerData` function. 
      The method will returns if the monomer was valid and it was successfully added to the set, 
      otherwise it will return false.
      
      Adding a valid monomer (:oe:cls:`OEChem::OEMonomerData`) can fail if:
      
      - the monomer is already present in the set (using canonical isomeric smiles for equivalency check)
      - the monomer has a code that is already used in the specific code-set stored in the set

   .. oe:method:: GetCodeSets

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

         .. oe:api::

            std::vector<std::string> GetCodeSets() const

      .. oe:language:: python

         .. oe:api:: python

            GetCodeSets() -> OEStringVector

      Returns all the code-sets supported by the monomer set.

      .. seealso::

         * :oe:meth:`OEChem::OEMonomerSet::GetPrimaryCodeSet` method

   .. oe:method:: GetCodes

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

         .. oe:api::

            std::vector<std::string> GetCodes(const std::string& codeSet) const

      .. oe:language:: python

         .. oe:api:: python

            GetCodes(codeSet: str) -> OEStringVector

      Returns all the monomer codes stored in the monomer set for the given code-set.

   .. oe:method:: GetMonomer

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

         .. oe:api::

            const OEMonomer* GetMonomer(const std::string& codeSet,
                                        const std::string& code) const

      .. oe:language:: python

         .. oe:api:: python

            GetMonomer(codeSet: str, code: str) -> OEMonomer

      Returns a monomer pointer with the given code in the specified code-set. 
      NULL pointer will be return if no such monomer exists in the set.

   .. oe:method:: GetMonomers

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

         .. oe:api::

            OESystem::OEIterBase<const OEMonomer>* GetMonomers() const

      .. oe:language:: python

         .. oe:api:: python

            GetMonomers() -> Iterable[OEMonomer]

      Returns an iterator over all :oe:cls:`OEChem::OEMonomer` objects
      stored in monomer set.

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

         .. oe:api::

            OESystem::OEIterBase<const OEMonomer>* GetMonomers(const OESystem::OEUnaryPredicate<OEMonomer>& pred) const

      .. oe:language:: python

         .. oe:api:: python

            GetMonomers(pred: OEUnaryMonomerPred) -> Iterable[OEMonomer]

      Returns an iterator over all :oe:cls:`OEChem::OEMonomer` objects
      stored in monomer set that satisfies the given predicate.

   .. oe:method:: GetPrimaryCodeSet

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

         .. oe:api::

            std::string GetPrimaryCodeSet() const

      .. oe:language:: python

         .. oe:api:: python

            GetPrimaryCodeSet() -> str

      Returns the name of the primary code-set of the monomer set.
      The primary code-set is the set that has the largest number of monomers defined with a unique code.

      .. seealso::

         * :oe:meth:`OEChem::OEMonomerSet::GetCodeSets` method
         * :oe:meth:`OEChem::OEMonomerSet::NumMonomers` method

   .. oe:method:: GetVersion

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

         .. oe:api::

            std::string GetVersion() const

      .. oe:language:: python

         .. oe:api:: python

            GetVersion() -> str

      Returns the version of the monomer set.

      .. seealso::

         * :oe:meth:`OEChem::OEMonomerSet::SetVersion` method

   .. oe:method:: HasCodeInCodeSet

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

         .. oe:api::

            bool HasCodeInCodeSet(const std::string& codeSet,
                                  const std::string& code) const

      .. oe:language:: python

         .. oe:api:: python

            HasCodeInCodeSet(codeSet: str, code: str) -> bool

   Returns whether the monomer set contains a specific monomer with the given code and code-set.

   .. oe:method:: HasCodeSet

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

         .. oe:api::

            bool HasCodeSet(const std::string& codeSet) const

      .. oe:language:: python

         .. oe:api:: python

            HasCodeSet(codeSet: str) -> bool

   Returns whether the monomer set contains any monomer for the given code-set.


   .. oe:method:: HasMonomer

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

         .. oe:api::

            bool HasMonomer(const OEMonomerData &) const

      .. oe:language:: python

         .. oe:api:: python

            HasMonomer(arg2: OEMonomerData) -> bool

   Returns whether the monomer (:oe:cls:`OEChem::OEMonomerData`) already exists in the monomer set.
   Each monomer in the :oe:cls:`OEChem::OEMonomerSet` has to have a unique canonical smiles.

   .. oe:method:: IsValid

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

         .. oe:api::

            bool IsValid() const

      .. oe:language:: python

         .. oe:api:: python

            IsValid() -> bool

      Returns whether the monomer set stores at least one valid monomer object.

   .. oe:method:: NumCodeSets

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

         .. oe:api::

            unsigned NumCodeSets() const

      .. oe:language:: python

         .. oe:api:: python

            NumCodeSets() -> int

      Returns the number of unique code set the monomers are defined.

   .. oe:method:: NumMonomers

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

         .. oe:api::

            unsigned NumMonomers() const

      .. oe:language:: python

         .. oe:api:: python

            NumMonomers() -> int

      Returns the number of monomers in the container.

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

         .. oe:api::

            unsigned NumMonomers(const std::string& codeSet) const

      .. oe:language:: python

         .. oe:api:: python

            NumMonomers(codeSet: str) -> int

      Returns the number of monomers in the container that associated wit a code
      in the given code-set. 

      .. seealso::

         * :oe:meth:`OEChem::OEMonomerSet::GetPrimaryCodeSet` method

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

         .. oe:api::

            unsigned NumMonomers(const OESystem::OEUnaryPredicate<OEMonomer>& pred) const

      .. oe:language:: python

         .. oe:api:: python

            NumMonomers(pred: OEUnaryMonomerPred) -> int

      Returns the number of monomers that satisfy the given predicate.

      .. seealso::

         * :oe:cls:`OEChem::OEHasAminoAcidType` predicate
         * :oe:cls:`OEChem::OEHasMonomerType` predicate
         * :oe:cls:`OEChem::OEHasPolymerType` predicate
         * :oe:cls:`OEChem::OEIsInMonomerCodeSet` predicate


   .. oe:method:: SetVersion

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

         .. oe:api::

            void SetVersion(const std::string& version)

      .. oe:language:: python

         .. oe:api:: python

            SetVersion(version: str) -> None

      Sets the version of the monomer set. The function does not validate the format of the given string.
      However OpenEye's built-in monomer sets are using the following conventions:

      The version format is ``A.B.C`` (The first is version is "1.0.0")

      - A: incremented for **major** changes in monomer set that has effect of parsing already generated HELMS with the given code set.

        - monomer is removed
        - monomer smiles has been corrected (for example correcting stereo configuration)
        - monomer code is modified

      - B: incremented for **minor** changes in monomer set that has effect on generating new HELMs but will not effect paring of HELMs
        generated with previous versions (backwards-compatibility)

        - new monomer is added
        - new R-group is added to already existing monomer

      - C: incremented for **micro** changes hat does not effect either HELM parsing or generation
        (backwards-compatibility)

        - monomer name change
        - adding additional monomer properties (such as associating colors with monomers for depiction)
