.. oe:namespace:: OEChem

.. meta::
   :keywords: OECIFData, CIFData


.. _OEChem_OECIFData:

.. oe:class:: OECIFData

   .. oe:api::

      struct OECIFData

   This class represents :ref:`OECIFData <OEChem_OECIFData>` that holds CIF header data and acts as an interface to
   interact with this header data. This object reflects what is contained in the CIF ``data_`` section.

   The goal for the OECIFData class is to allow a user to freely interact with CIF data and be confident the
   data will be written in proper format that can be easily be read again.
   This object allows structural data stored on the molecule to be synchronized and updated with its CIF header data
   to reflect changes in the molecule. No change in OECIFData will affect the molecule that stores it.

   The overall structure of OECIFData reflects CIF formatting. The OECIFData object stores all the data in a
   ``data_`` block. Values from each CIF category are stored on the OECIFCategory object. Thus, OECIFData is a
   collection of OECIFCategory objects mapped to the category name.

   Access to the data using OECIFData utilizes the CIF category and attribute names. These functions allow a user
   to get, set or add any value in the CIF header.

   .. note::

      Category names must begin with an underscore and end with a period. Example: ``"_entity."``


   The :ref:`section_moldata_CIF` section explains the CIF data structure in more detail.

   .. seealso::

      * :oe:func:`OEChem::OEUpdateMMCIFData` function
      * :oe:cls:`OEChem::OECIFCategory` class
      * :oe:cls:`OEChem::OECIFOptions` class
      * :ref:`section_moldata_cif`

   .. oe:method:: Constructors

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

         .. oe:api::

            OECIFData()
            OECIFData(const std::string& cifHeaderString)
            OECIFData(const OEMolBase& mol)

      .. oe:language:: python

         .. oe:api:: python

            OECIFData() -> OECIFData
            OECIFData(cifDataBlockAsString: str) -> OECIFData
            OECIFData(cifData: OECIFData) -> OECIFData
            OECIFData(mol: Union[OEGraphMol,OEMol,OEQMol]) -> OECIFData

      Create an :ref:`OECIFData <OEChem_OECIFData>` object from a header data string, or header data stored on a mol
      accessed using :ref:`OEGetMMCIFData <OEChem_OEGetMMCIFData>`.

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

      .. oe:api::

         OECIFData & operator=(const OECIFData & category)

      Assignment operator.


   .. oe:method:: AddCategory

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

         .. oe:api::

            bool AddCategory(const OECIFCategory& category)
            bool AddCategory(const std::string& categoryName,
                             const std::vector<std::string>& attributes,
                             const std::vector<std::string>& newValues)
            bool AddCategory(const std::string& categoryName,
                             const std::vector<std::string>& attributes)
            bool AddCategory(const std::string& categoryName,
                             const std::string& attribute,
                             const std::vector<std::string>& newValues)
            bool AddCategory(const std::string& categoryName,
                             const std::string& attribute,
                             const std::string& newValue)
            bool AddCategory(const std::string& categoryName)

      .. oe:language:: python

         .. oe:api:: python

            AddCategory(category: OECIFCategory) -> bool
            AddCategory(categoryName: str, attributes: OEStringVector,
                        newValues: OEStringVector) -> bool
            AddCategory(categoryName: str, attributes: OEStringVector) -> bool
            AddCategory(categoryName: str) -> bool

      Adds a new category to the OECIFData object.

   .. oe:method:: AddRow

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

         .. oe:api::

            bool AddRow(const std::string& categoryName,
                        const std::vector<std::string>& newValues)
            bool AddRow(const std::string& categoryName,
                        const std::string init = "?")

      .. oe:language:: python

         .. oe:api:: python

            AddRow(categoryName: str, newValues: OEStringVector) -> bool

      Adds a row of values to the indicated CIF item prefix.
      If no values are input, by default, it will add a question mark "?" to every attribute in the category.


   .. oe:method:: AddData

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

         .. oe:api::

            bool AddData(const std::string& categoryName,
                         const std::string& attribute,
                         const std::vector<std::string>& newValues)
            bool AddData(const std::string& categoryName,
                         const std::string& attribute,
                         const std::string& newValue = "?")

      .. oe:language:: python

         .. oe:api:: python

            AddData(categoryName: str, attribute: str,
                    newValuess: OEStringVector) -> bool

      Adds a new attribute and a column of its values to the indicated CIF item tag. The number of new data input
      must match the number of rows currently in the OECIFCategory it is being added to.

   .. oe:method:: ChemCompToMol

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

         .. oe:api::

            bool ChemCompToMol(OEMolBase& cifMol, const std::string resName) const

      .. oe:language:: python

         .. oe:api:: python

            ChemCompToMol(cifMol: Union[OEGraphMol,OEMol,OEQMol], resName: str) -> bool

      Creates a molecule from CIF _chem_comp data in the OECIFData object. The following CIF categories must be present
      for proper function:

      * _chem_comp_atom. defines the atom name and element
      * _chem_comp_bond. defines the bonding network

      The input cifMol molecule is cleared before parsing, so the resulting molecule object only contains atoms and bonds
      from the _chem_comp header data.

   .. oe:method:: DeleteCategory

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

         .. oe:api::

            bool DeleteCategory(const std::string& categoryName)

      .. oe:language:: python

         .. oe:api:: python

            DeleteCategory(categoryName: str) -> bool

      Deletes a category based on the category name.

   .. oe:method:: DeleteRow

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

         .. oe:api::

            bool DeleteRow(const std::string& categoryName, unsigned int row)

      .. oe:language:: python

         .. oe:api:: python

            DeleteRow(categoryName: str, row: int) -> bool

      Deletes a category's indicated row values based on the category name.

   .. oe:method:: DeleteAttribute

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

         .. oe:api::

            bool DeleteAttribute(const std::string& categoryName,
                                 const std::string& attribute)

      .. oe:language:: python

         .. oe:api:: python

            DeleteAttribute(categoryName: str, attribute: str) -> bool

      Deletes a category's attribute and associated values.

   .. oe:method:: GenerateHeader

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

         .. oe:api::

            std::string GenerateHeader() const

      .. oe:language:: python

         .. oe:api:: python

            GenerateHeader() -> str

      Using all the categories saved on this object, this will output the CIF header.

   .. oe:method:: GeneratePolySeqScheme

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

         .. oe:api::

            bool GeneratePolySeqScheme(OEMolBase& mol,
                                       const unsigned int maxMismatch = 10)

      .. oe:language:: python

         .. oe:api:: python

            GeneratePolySeqScheme(mol: Union[OEGraphMol,OEMol,OEQMol],
                                  maxMismatch: int = 10) -> bool

      Will generate the _pdbx_poly_seq_scheme header section using header and molecule data.
      The following categories need to be present and properly populated for this function:

      * _struct_asym.
      * _entity.
      * _entity_poly_seq.

      The molecule object must contain at least one residue. Any existing _pdbx_poly_seq_scheme data will be
      cleared before generation.

   .. oe:method:: GetAttributes

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

         .. oe:api::

            std::vector<std::string>  GetAttributes(const std::string& categoryName) const

      .. oe:language:: python

         .. oe:api:: python

            GetAttributes(categoryName: str) -> OEStringVector

      Gets a list of all the attributes in this object.

   .. oe:method:: GetAttributeValue

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

         .. oe:api::

            std::string GetAttributeValue(const std::string& categoryName,
                                          const std::string& attribute,
                                          bool raw = false) const
            std::string GetAttributeValue(const std::string& categoryName,
                                          const std::string& attribute,
                                          unsigned int row, bool raw = false) const

      .. oe:language:: python

         .. oe:api:: python

            GetAttributeValue(categoryName: str, attribute: str,
                              raw: bool = False) -> str
            GetAttributeValue(categoryName: str, attribute: str, row: int,
                              raw: bool = False) -> str

      Gets the saved value on the indicated category's attribute.
      If multiple values exist for a given attribute, then a row number must be identified.

   .. oe:method:: GetAttributeValues

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

         .. oe:api::

            std::vector<std::string> GetAttributeValues(const std::string& categoryName,
                                                        const std::string& attribute,
                                                        bool raw = false) const

      .. oe:language:: python

         .. oe:api:: python

            GetAttributeValues(categoryName: str, attribute: str,
                               raw: bool = False) -> OEStringVector

      Gets all the saved values on the indicated category's attribute.

   .. oe:method:: GetAttributeIndex

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

         .. oe:api::

            int GetAttributeIndex(const std::string& categoryName,
                                  const std::string& attribute) const

      .. oe:language:: python

         .. oe:api:: python

            GetAttributeIndex(categoryName: str, attribute: str) -> int

      Returns the attribute's base-0 index. For any given row of data associated with the category, this index
      correlates with the attribute's value in that row.
      For example, if GetAttributeIndex("entity.", "type")=1, for every row generated by
      GetRows("_entity."), the _category.type data would be the [1] value in that row.

   .. oe:method:: GetCategory

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

         .. oe:api::

            OECIFCategory& GetCategory(const std::string& categoryName)

      .. oe:language:: python

         .. oe:api:: python

            GetCategory(categoryName: str) -> OECIFCategory

      Gets the :ref:`OECIFCategory <OEChem_OECIFCategory>` object by its category name.

   .. oe:method:: GetCategoryNames

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

         .. oe:api::

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

      .. oe:language:: python

         .. oe:api:: python

            GetCategoryNames() -> OEStringVector

      Returns all the CIF category names present in this object.

   .. oe:method:: GetDataItems

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

         .. oe:api::

            std::vector<std::string>  GetDataItems(const std::string& categoryName) const

      .. oe:language:: python

         .. oe:api:: python

            GetDataItems(categoryName: str) -> OEStringVector

      Returns a list of all the CIF data items in this object.

   .. oe:method:: GetName

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

         .. oe:api::

            const std::string& GetName() const

      .. oe:language:: python

         .. oe:api:: python

            GetName() -> str

      Returns the name of the header data. Value is defined using the molecule's title.

   .. oe:method:: GetNumCategories

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

         .. oe:api::

            unsigned int GetNumCategories() const

      .. oe:language:: python

         .. oe:api:: python

            GetNumCategories() -> int

      Number of CIF categories saved in this object.

   .. oe:method:: GetNumCategoryRows

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

         .. oe:api::

            unsigned int GetNumCategoryRows(const std::string& categoryName) const

      .. oe:language:: python

         .. oe:api:: python

            GetNumCategoryRows(categoryName: str) -> int

      Number of CIF rows in a category.

   .. oe:method:: GetNumCategoryAttributes

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

         .. oe:api::

            unsigned int GetNumCategoryAttributes(const std::string& categoryName) const

      .. oe:language:: python

         .. oe:api:: python

            GetNumCategoryAttributes(categoryName: str) -> int

      Number of CIF attributes in a category.

   .. oe:method:: GetNumericAttributeValue

      .. oe:language:: c++

         .. oe:api::

            bool GetNumericAttributeValue(const std::string& categoryName,
                                          const std::string& attribute,
                                          float& val) const
            bool GetNumericAttributeValue(const std::string& categoryName,
                                          const std::string& attribute,
                                          int& val) const
            bool GetNumericAttributeValue(const std::string& categoryName,
                                          const std::string& attribute,
                                          unsigned int row, float& val) const
            bool GetNumericAttributeValue(const std::string& categoryName,
                                          const std::string& attribute,
                                          unsigned int row, int& val) const

      .. oe:language:: java

         .. oe:api::

            GetFloatAttributeValue(String categoryName, String attribute,
                                   Float val)
            GetIntAttributeValue(String categoryName, String attribute,
                                 Integer val)
            GetFloatAttributeValue(String categoryName, String attribute,
                                   Integer row, Float val)
            GetIntAttributeValue(String categoryName, String attribute,
                                 Integer row, Integer val)

      Gets the saved value on the indicated category's attribute and converts to a numeric value.
      If multiple values exist for a given item attribute, then a row number must be identified.
      If a value cannot be easily converted to a numeric value, it will default to 0.

   .. oe:method:: GetNumericAttributeValues

      .. oe:language:: c++

         .. oe:api::

            bool GetNumericAttributeValues(const std::string& categoryName,
                                           const std::string& attribute,
                                           std::vector<float>& vals) const
            bool GetNumericAttributeValues(const std::string& categoryName,
                                           const std::string& attribute,
                                           std::vector<int>& vals) const

      .. oe:language:: java

         .. oe:api::

            GetFloatAttributeValues(String categoryName, String attribute,
                                    Vector<Float> vals)
            GetIntAttributeValues(String categoryName, String attribute,
                                  Vector<Integer> vals)

      .. oe:language:: python

         .. oe:api:: python

            GetNumericAttributeValues(categoryName: str, attribute: str,
                                      vals: OEFloatVector) -> bool
            GetNumericAttributeValues(categoryName: str, attribute: str,
                                      vals: OEIntVector) -> bool

      Gets all the saved values on the indicated category's attribute and converts to a numeric value.
      If a value cannot be easily converted to a numeric value, it will default to 0.

   .. oe:method:: GetRow

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

         .. oe:api::

            std::vector<std::string> GetRow(const std::string& categoryName,
                                            unsigned int row, bool raw = false) const

      .. oe:language:: python

         .. oe:api:: python

            GetRow(categoryName: str, row: int, raw: bool = False) -> OEStringVector

      Returns a specific row from the indicated category. Rows values are base-0.
      Raw values are formatted as they will appear in the header. This is most noticeable with values that contain
      space characters as CIF formatting requires single or double quotes around such a string value.

   .. oe:method:: GetRows

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

         .. oe:api::

            std::vector<std::vector<std::string>> GetRows(const std::string& categoryName,
                                                          int beginRow,
                                                          int endRow,
                                                          bool raw = false) const
            std::vector<std::vector<std::string>> GetRows(const std::string& categoryName,
                                                          bool raw = false) const

      .. oe:language:: python

         .. oe:api:: python

            GetRows(categoryName: str, beginRow: int, endRow: int,
                    raw: bool = False) -> OEStringVectorVector
            GetRows(categoryName: str, raw: bool = False) -> OEStringVectorVector

      Returns rows from the indicated category. Rows values are base-0.
      Raw values are formatted as they will appear in the header. This is most noticeable with values that contain
      space characters as CIF formatting requires single or double quotes around such a string value.

   .. oe:method:: GetRowIndices

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

         .. oe:api::

            std::vector<unsigned int> GetRowIndices(const std::string& categoryName,
                                                    const std::string& attribute,
                                                    const std::string& matchValue) const

      .. oe:language:: python

         .. oe:api:: python

            GetRowIndices(categoryName: str, attribute: str, matchValue: str) -> OEUIntVector

      Returns the base-0 row indices whose values string-match with input match value.

   .. oe:method:: HasAttribute

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

         .. oe:api::

            bool HasAttribute(const std::string& categoryName,
                              const std::string& attribute) const

      .. oe:language:: python

         .. oe:api:: python

            HasAttribute(categoryName: str, attribute: str) -> bool

      Returns if an attribute is present in this object.

   .. oe:method:: HasCategoryName

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

         .. oe:api::

            bool HasCategoryName(const std::string& categoryName) const

      .. oe:language:: python

         .. oe:api:: python

            HasCategoryName(categoryName: str) -> bool

      Returns if a category name is present in this object.

   .. oe:method:: SetCategory

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

         .. oe:api::

            bool SetCategory(const OECIFCategory& category)
            bool SetCategory(const std::string& categoryName,
                             const std::string& attribute,
                             const std::string& val)
            bool SetCategory(const std::string& categoryName,
                             const std::vector<std::string>& attributes,
                             const std::vector<std::string>& vals)

      .. oe:language:: python

         .. oe:api:: python

            SetCategory(category: OECIFCategory) -> bool
            SetCategory(categoryName: str, attributes: OEStringVector,
                        vals: OEStringVector) -> bool

      Sets OECIFCategory information in this object.

   .. oe:method:: SetData

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

         .. oe:api::

            bool SetData(const std::string& categoryName,
                         const std::string& attribute, const std::string& nval)
            bool SetData(const std::string& categoryName,
                         const std::string& attribute, unsigned int row,
                         const std::string& nval, const std::string init = "?")
            bool SetData(const std::string& categoryName,
                         const std::string& attribute,
                         const std::vector<std::string>& nvals)
            bool SetData(const std::string& categoryName, unsigned int row,
                         const std::vector<std::string>& nvals,
                         const std::string init = "?")

      .. oe:language:: python

         .. oe:api:: python

            SetData(categoryName: str, attribute: str,
                    newValues: OEStringVector) -> bool
            SetData(categoryName: str, attribute: str, row: int, newValue: str,
                    init: str = "?") -> bool
            SetData(categoryName: str, row: int, newValues: OEStringVector,
                    init: str = "?") -> bool

      Sets attribute and row data on the indicated category.

   .. oe:method:: SetMMCIFChemCompData

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

         .. oe:api::

            bool SetMMCIFChemCompData(const OEMolBase& mol,
                                      const OEMolBase& chemCompMol,
                                      const bool strict = false)

      .. oe:language:: python

         .. oe:api:: python

            SetMMCIFChemCompData(mol: Union[OEGraphMol,OEMol,OEQMol],
                                 chemCompMol: Union[OEGraphMol,OEMol,OEQMol],
                                 strict: bool = False) -> bool

      Updates _chem_comp sections in the mmCIF header metadata with information from the input chemCompMol molecule.
      First, a single-residue chemCompMol is checked to name match with a residue in the molecule.
      The chemCompMol atom and bond data is then used to replace the _chem_comp header data for a similarly named residue
      in the mol. If strict is used, an additional check for atom name matching is made between the matched residue in
      the molecule and the chemCompMol.

      The following categories need to be present and properly populated in the input molecules header for this
      function. If any attributes are missing, running OEUpdateMMCIFData with ChemComp perception should populate any
      missing attributes:

        * _chem_comp.
        * _chem_comp_atom.
        * _chem_comp_bond.

      If the molecule already exists, it will replace all chemical component reference of that molecule with the
      new molecule.
      By default, residue atom name matching is enforced. If strict is turned off, an :ref:`OESubSearch <OEChem_OESubSearch>`
      is used to identify structural similarity with the new molecule. If a match is found, the matching structure
      atom names will be used in the _chem_comp atom naming scheme.

   .. oe:method:: Update

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

         .. oe:api::

            bool Update(OEMolBase& mol, const OECIFOptions& opts)

      .. oe:language:: python

         .. oe:api:: python

            Update(mol: Union[OEGraphMol,OEMol,OEQMol], opts: OECIFOptions) -> bool

      Coordinates the molecule's structural and residue data with related information found in the header. Where
      there are disagreements, the molecule's data overrides the header data.
      Because updating can affect many parts of the header,
      to control what parts are and are not updated, the :ref:`OECIFOptions <OEChem_OECIFOptions>` class indicates which
      parts of the header will be perceived during the update.

      This function can be used to convert PDB header data into CIF header data. Create an OECIFData object using the
      PDB molecule and run Update(). Only perceivable fields in the molecule's structure data will be populated.

   .. oe:method:: ValidateMMCIFHeader

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

         .. oe:api::

            bool ValidateMMCIFHeader(bool allowErrors = false,
                                     bool strict = false)

      .. oe:language:: python

         .. oe:api:: python

            ValidateMMCIFHeader(allowErrors: bool = False, strict: bool = False) -> bool

      Validates self-consistency within a mmCIF header. Many items will reference each other and this function runs
      checks to see if some of these are consistent with each other. Item entries that are checked include:

        * _entity.
        * _entity_poly.
        * _entity_poly_seq.
        * _chem_comp.
        * _struct_asym.

      The strict flag will explore more parts of the header and enforce a wider range of requirements:

        * Any 'entry_id' value reference must match an already defined '_entry.id'
        * Any 'entity_id' value reference must match an already defined '_entity.id'
        * An expression system has been identified (_entity_src_gen., _entity_src_nat., _entity_src_syn.)
        * _chem_comp_atom.
        * _chem_comp_bond.
        * _struct_ref.
        * _struct_ref_seq.


   .. oe:method:: ValidateMMCIFMol

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

         .. oe:api::

            bool ValidateMMCIFMol(const OEMolBase& mol,
                                  bool allowErrors = false, bool strict = false)

      .. oe:language:: python

         .. oe:api:: python

            ValidateMMCIFMol(mol: Union[OEGraphMol,OEMol,OEQMol],
                             allowErrors: bool = False, strict: bool = False) -> bool

      Validates self-consistency between the header and mol reference. Item entries that are checked against the
      input molecule include:

        * _entity.
        * _chem_comp.
        * _struct_asym.

      The strict flag will explore more parts of the header and enforce a wider range of requirements against the
      input molecule:

        * strict _entity. header validation
        * _pdbx_poly_seq_scheme.
