.. include:: ../substitutions

.. oe:namespace:: OEDepict

.. meta::
   :keywords: OEWrite2DRingDictionaryReport

.. _OEDepict_OEWrite2DRingDictionaryReport:


.. oe:function:: OEWrite2DRingDictionaryReport


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

      .. oe:api::

         bool OEWrite2DRingDictionaryReport(const std::string& filename,
                                            const OEChem::OE2DRingDictionary& ringdict,
                                            const OEReportOptions& opts)
         bool OEWrite2DRingDictionaryReport(OEPlatform::oeostream& os,
                                            const std::string& extension,
                                            const OEChem::OE2DRingDictionary& ringdict,
                                            const OEReportOptions& opts)

   .. oe:language:: python

      .. oe:api:: python

         OEWrite2DRingDictionaryReport(filename: str, rtd: OE2DRingDictionary,
                                       opts: OEReportOptions) -> bool
         OEWrite2DRingDictionaryReport(os: oeostream, extension: str,
                                       rtd: OE2DRingDictionary,
                                       opts: OEReportOptions) -> bool

   Writes a report of the 2D ring layouts stored in the given
   ring dictionary.
   See example in :ref:`Table Example of ring dictionary report<table_OEWrite2DRingDictionaryReport>`.

   *filename*
      The filename into which the report is written.
      The file extension determines the type of the multi-page image.

   *os*
      The stream into which the report is written.

   *ext*
      The extension which determine the type of the multi-page report.

   **ringdict**
      The :ref:`OE2DRingDictionary <OEChem_OE2DRingDictionary>` object that stores ring
      2D layouts that can be used to plug into the 2D coordinate
      generation system.

   **opts**
      The :ref:`OEReportOptions <OEDepict_OEReportOptions>` object that determines the layout
      of the pages of the report.

   The report depicts each ring systems stored in the ring dictionary.

   * The string at the top is the :term:`canonical isomeric SMILES` that is used as the identifier for the given ring system.
   * The larger depiction on the left shows the user-defined layout of the ring system
   * The smaller depiction on the right illustrates the default layout of the ring system *i.e.* when
     the 2D coordinates are generated by **OEChem TK** without utilizing the given user-defined ring
     dictionary.

     - The blue box indicates that **OEChem TK** has already have a built-in layout for
       the given ring system.
     - The pink box indicates that the layout of that ring system would be generated on the fly by default
       without utilizing any built-in templates.

   * There are cases when cis/trans bonds are marked on the macro-cycles depicted inside the blue/pink boxes.
     These annotations indicate potential depiction problem in **OEChem TK**.

   .. _table_OEWrite2DRingDictionaryReport:

   .. list-table:: **Example of ring dictionary report** (The pages are reduced here for visualization convenience)

      * - cover page
        - page 1
        - page 2

      * -  .. image:: ../images/rtd-example-report-1.*
        -  .. image:: ../images/rtd-example-report-2.*
        -  .. image:: ../images/rtd-example-report-3.*

   .. seealso::

      * :ref:`OE2DRingDictionary <OEChem_OE2DRingDictionary>` class
      * :oe:func:`OEDepict::OEAnnotateDepictionProblems` function
      * :ref:`section_example_oechem_2D_coordinate_generation` section of
        the **OEChem TK** manual that shows examples about how to generate and
        utilize user-defined ring dictionaries.

