.. _chapter_molreadwrite:

*****************************
Molecule Reading and Writing
*****************************

.. index::
   single: oemolistream
   single: oemolostream
   single: oemolstreambase

.. _section_molreadwrite_oemolstreams:

Molecule Streams
============================================================================

The :ref:`previous section <section_molctordtor_smilesfrommol>`
demonstrated reading and writing :ref:`SMILES <chapter_SMILES>`
strings from  standard input. This required the programmer to perform the file
I/O explicitly.  Whilst this may be reasonable for :ref:`SMILES
<chapter_SMILES>` strings that may be read via STD
`getline <http://www.cplusplus.com/reference/string/string/getline/>`_,
it isn't suitable for more
complex file formats.  To ease this task, **OEChem TK** provides the
:oe:cls:`oemolstream<OEChem::oemolstreambase>` abstraction.  The
classes :ref:`oemolistream <OEChem_oemolistream>` and
:ref:`oemolostream <OEChem_oemolostream>` allow input and output of molecules
using the :oe:func:`OEChem::OEReadMolecule` and
:oe:func:`OEChem::OEWriteMolecule` functions, respectively.

.. oe:language:: java

   .. warning::

      The :oe:meth:`OEChem::oemolstreambase::close` method must be
      explicitly called on all molecule streams in Java. Java does not
      guarantee that finalizers are ever called. There is also a delay
      before a finalizer is called, possibly causing the operating
      system to run out of resources, e.g., file handles.

.. oe:source:: oemolstream.cpp
   :language: c++
   :caption:  High-level Molecule I/O using molstreams
   :refnum:   1
   :frag:     SNIPPET

.. oe:source:: oemolstream.py
   :language: python
   :caption:  High-level Molecule I/O using molstreams
   :refnum:   1
   :frag:     SNIPPET

.. oe:source:: oemolstream.java
   :language: java
   :caption:  High-level Molecule I/O using molstreams
   :refnum:   1
   :frag:     SNIPPET

.. oe:source:: oemolstream.cs
   :language: csharp
   :caption:  High-level Molecule I/O using molstreams
   :refnum:   1
   :frag:     SNIPPET


:oe:src:`Listing 1<SNIPPET-oemolstream>` will read molecules from stdin in
:ref:`SMILES <chapter_SMILES>` format and write them to stdout in
:oe:func:`absolute SMILES<OEChem::OECreateAbsSmiString>` format.
Notice that in this example, the following is done automatically for you by
:oe:func:`OEChem::OEReadMolecule`:

- :oe:meth:`OEChem::OEMolBase::Clear` method to reset the molecule.
- :oe:func:`OEChem::OEAssignAromaticFlags` to normalize aromaticity.
- :oe:meth:`OEChem::OEMolBase::operator bool` to test the validity of the molecule.

.. note::

   :oe:func:`OEChem::OEReadMolecule` will skip any invalid molecules automatically.

.. oe:language:: python

   **OEChem TK** provides the following more *Python-like* generator methods to
   read molecules out of an :ref:`oemolistream <OEChem_oemolistream>` if the user
   prefers. It is important to realize that the same
   :ref:`OEGraphMol <OEChem_OEGraphMol>` instance is reused for every molecule
   being read from the :ref:`oemolistream <OEChem_oemolistream>`.

    .. oe:source:: GetOEGraphMols.py
       :language: python
       :caption:  Generator methods for reading molecules
       :frag:     SNIPPET


Since the same :ref:`OEGraphMol <OEChem_OEGraphMol>` instance is being reused
for every molecule in the stream, special precautions must be taken to
load up an entire file into memory. :oe:src:`Listing
2<SNIPPET-ReadMolIntoMemory>` will read molecules into memory by making sure
there is a copy made when inserting the molecule into the
container. This is useful if the molecules need to be repeatedly
accessed.

.. oe:source:: ReadMolIntoMemory.cpp
   :language: c++
   :caption:  Reading molecules into memory
   :refnum:   2
   :frag:     SNIPPET

.. oe:source:: ReadMolIntoMemory.py
   :language: python
   :caption:  Reading molecules into memory
   :refnum:   2
   :frag:     SNIPPET

.. oe:source:: ReadMolIntoMemory.java
   :language: java
   :caption:  Reading molecules into memory
   :refnum:   2
   :frag:     SNIPPET

.. oe:source:: ReadMolIntoMemory.cs
   :language: csharp
   :caption:  Reading molecules into memory
   :refnum:   2
   :frag:     SNIPPET

.. _section_molreadwrite_fileformats:

File Formats
============================================================================

.. index::
   single: SetFormat
   single: GetFormat

In addition to :ref:`SMILES <chapter_SMILES>` strings, **OEChem TK** is able
to read numerous other molecular file formats, including :oe:func:`MDL
SD<OEChem::OEReadMDLFile>` files, Tripos :oe:func:`Tripos
MOL2<OEChem::OEReadMol2File>` files and :oe:func:`PDB<OEChem::OEReadPDBFile>`
files. The format of an input file or stream may be associated with an
:ref:`oemolistream <OEChem_oemolistream>` using the
:oe:meth:`SetFormat<OEChem::oemolistream::SetFormat>` method, and may
be retrieved with
:oe:meth:`GetFormat<OEChem::oemolstreambase::GetFormat>`. The file
format is represented by an unsigned integer, which should be one of
the constants defined in the :ref:`the OEFormat namespace <OEChem_OEFormat>`.
A value of :oe:const:`OEChem::OEFormat::UNDEFINED` means that there is
no file format associated with the
:oe:cls:`oemolstream<OEChem::oemolstreambase>`.

.. note::

   The default format associated with an
   :oe:cls:`oemolstream<OEChem::oemolstreambase>` is
   :oe:const:`OEChem::OEFormat::SMI`.

:oe:src:`Listing 3<SNIPPET-ReadWriteSettingFormats>` demonstrates how to use
:oe:cls:`oemolstreams<OEChem::oemolstreambase>` to convert :oe:func:`MDL
SD<OEChem::OEReadMDLFile>` files into :oe:func:`Tripos
MOL2<OEChem::OEReadMol2File>` files.

.. oe:source:: ReadWriteSettingFormats.cpp
   :language: c++
   :caption:  Explicitly setting file formats
   :refnum:   3
   :frag:     SNIPPET

.. oe:source:: ReadWriteSettingFormats.py
   :language: python
   :caption:  Explicitly setting file formats
   :refnum:   3
   :frag:     SNIPPET

.. oe:source:: ReadWriteSettingFormats.java
   :language: java
   :caption:  Explicitly setting file formats
   :refnum:   3
   :frag:     SNIPPET

.. oe:source:: ReadWriteSettingFormats.cs
   :language: csharp
   :caption:  Explicitly setting file formats
   :refnum:   3
   :frag:     SNIPPET

.. table::  **OEChem TK file format support**

   ====================================== ====================================================== ======= ======
   File Format                            Description                                            Read    Write
   ====================================== ====================================================== ======= ======
   :oe:const:`OEChem::OEFormat::CAN`      :term:`Canonical SMILES`                               Yes     Yes
   :oe:const:`OEChem::OEFormat::CDX`      ChemDraw CDX                                           Yes     Yes
   :oe:const:`OEChem::OEFormat::CIF`      Crystallographic Information File                      Yes     Yes
   :oe:const:`OEChem::OEFormat::CSV`      Comma separated values                                 Yes     Yes
   :oe:const:`OEChem::OEFormat::CXSMILES` Chemaxon Extended SMILES                               Yes     Yes
   :oe:const:`OEChem::OEFormat::FASTA`    FASTA protein sequence                                 Yes     Yes
   :oe:const:`OEChem::OEFormat::INCHI`    IUPAC InChI                                            No      Yes
   :oe:const:`OEChem::OEFormat::INCHIKEY` IUPAC InChI Key                                        No      Yes
   :oe:const:`OEChem::OEFormat::ISM`      :term:`Canonical isomeric SMILES`                      Yes     Yes
   :oe:const:`OEChem::OEFormat::MDL`      MDL Mol File                                           Yes     Yes
   :oe:const:`OEChem::OEFormat::MF`       Molecular Formula (Hill order)                         No      Yes
   :oe:const:`OEChem::OEFormat::MMCIF`    Macromolecular Crystallographic Information File       Yes     Yes
   :oe:const:`OEChem::OEFormat::MMOD`     Macromodel                                             Yes     Yes
   :oe:const:`OEChem::OEFormat::MOL2`     Tripos Sybyl mol2 file                                 Yes     Yes
   :oe:const:`OEChem::OEFormat::MOL2H`    Sybyl mol2 with explicit hydrogens                     Yes     Yes
   :oe:const:`OEChem::OEFormat::MOPAC`    MOPAC file format(s)                                   No      Yes
   :oe:const:`OEChem::OEFormat::OEB`      *OpenEye* OEBinary                                     Yes     Yes
   :oe:const:`OEChem::OEFormat::OEZ`      Zstd Compressed *OpenEye* OEBinary                     Yes     Yes
   :oe:const:`OEChem::OEFormat::PDB`      Protein Databank PDB file                              Yes     Yes
   :oe:const:`OEChem::OEFormat::RDF`      MDL RDF File                                           Yes     No
   :oe:const:`OEChem::OEFormat::SDF`      MDL SD File                                            Yes     Yes
   :oe:const:`OEChem::OEFormat::SKC`      MDL ISIS Sketch File                                   Yes     No
   :oe:const:`OEChem::OEFormat::SLN`      Tripos Sybyl Line Notation                             No      Yes
   :oe:const:`OEChem::OEFormat::SMI`      :term:`Canonical isomeric SMILES`                      Yes     Yes
   :oe:const:`OEChem::OEFormat::USM`      :term:`SMILES`                                         Yes     Yes
   :oe:const:`OEChem::OEFormat::XYZ`      XMol XYZ format                                        Yes     Yes
   ====================================== ====================================================== ======= ======

.. _section_molreadwrite_fileinputandoutput:

File Input and Output
============================================================================

In addition to standard in and standard out, **OEChem TK**'s
:oe:cls:`oemolstreams<OEChem::oemolstreambase>` also support reading
from files.  To open a file, use the
:oe:meth:`open<OEChem::oemolstreambase::open>` method with the required
filename.  For input :oe:cls:`oemolistreams<OEChem::oemolistream>`, if
the file does not exist the
:oe:meth:`open<OEChem::oemolstreambase::open>` fails and returns false,
for output :oe:cls:`oemolostreams<OEChem::oemolostream>`, the output
file is created if it did not previously exist and overwritten if it
did.  If a filename is passed to the :oe:meth:`open<OEChem::oemolstreambase::open>`
method, the format and gz compression flags are set based on the file extension of the filename for the
:ref:`oemolistream <OEChem_oemolistream>` or :ref:`oemolostream <OEChem_oemolostream>` instance.
If *no* arguments are passed to
:oe:meth:`open<OEChem::oemolstreambase::open>`, an
:ref:`oemolistream <OEChem_oemolistream>` will use standard in, and an
:ref:`oemolostream <OEChem_oemolostream>` will use standard out, the format
will be set to :oe:const:`OEChem::OEFormat::Default` and gz compression will be disabled.
Much like regular file I/O, :oe:cls:`oemolstreams<OEChem::oemolstreambase>` can be closed after use, using the
:oe:meth:`close<OEChem::oemolstreambase::close>` method.
:oe:cls:`oemolstreams<OEChem::oemolstreambase>` are automatically
closed by their destructors.

.. oe:source:: ReadWriteToFiles.cpp
   :language: c++
   :caption:  Reading and writing molecule files
   :refnum:   4
   :frag:     SNIPPET

.. oe:source:: ReadWriteToFiles.py
   :language: python
   :caption:  Reading and writing molecule files
   :refnum:   4
   :frag:     SNIPPET

.. oe:source:: ReadWriteToFiles.java
   :language: java
   :caption:  Reading and writing molecule files
   :refnum:   4
   :frag:     SNIPPET

.. oe:source:: ReadWriteToFiles.cs
   :language: csharp
   :caption:  Reading and writing molecule files
   :refnum:   4
   :frag:     SNIPPET


One convenient feature of the
:oe:meth:`open<OEChem::oemolstreambase::open>` method of
:oe:cls:`oemolstreams<OEChem::oemolstreambase>` is that it sets the
file format and gz compression associated with the stream from the file extension of the
filename used as an argument. :oe:src:`Listing 4<SNIPPET-ReadWriteToFiles>`
converts the file 'input.sdf' in MDL file format into the file
'output.mol2' in Tripos MOL2 file format.  This behavior can be
overridden by calling
:oe:meth:`SetFormat<OEChem::oemolistream::SetFormat>` after the
:oe:meth:`open<OEChem::oemolstreambase::open>` but before the first
molecule is read or written to a stream.

.. _section_molreadwrite_stringinputandoutput:

String Input and Output
============================================================================

The :ref:`oemolistream <OEChem_oemolistream>` and :ref:`oemolostream <OEChem_oemolostream>`
provide the ability to read and write memory buffers instead of
files.

.. oe:language:: java

   This is accomplished through the methods,
   :oe:meth:`OEChem::oemolistream::openByteArray` and
   :oe:meth:`OEChem::oemolostream::getByteArray`.

.. oe:language:: csharp

   This is accomplished through the methods,
   :oe:meth:`OEChem::oemolistream::OpenByteArray` and
   :oe:meth:`OEChem::oemolostream::GetByteArray`.

.. oe:language:: c++ python

   This is accomplished through the methods,
   :oe:meth:`OEChem::oemolistream::openstring` and
   :oe:meth:`OEChem::oemolostream::GetString`.

The :oe:src:`Listing 5<SNIPPET-StringIO>` example below demonstrates how to read and write molecules from memory buffers.

.. oe:source:: StringIO.cpp
   :language: c++
   :caption:  Reading and writing molecule from memory buffers
   :refnum:   5
   :frag:     SNIPPET

.. oe:source:: StringIO.py
   :language: python
   :caption:  Reading and writing molecule from memory buffers
   :refnum:   5
   :frag:     SNIPPET

.. oe:source:: StringIO.java
   :language: java
   :caption:  Reading and writing molecule from memory buffers
   :refnum:   5
   :frag:     SNIPPET

.. oe:source:: StringIO.cs
   :language: csharp
   :caption:  Reading and writing molecule from memory buffers
   :refnum:   5
   :frag:     SNIPPET

.. _section_molreadwrite_compressed:

Compressed Input and Output
============================================================================

For any of the molecular file formats supported by **OEChem TK**, it is often
convenient to read and write compressed
:ref:`files<section_molreadwrite_fileinputandoutput>` or
:ref:`strings<section_molreadwrite_stringinputandoutput>`.
Molecule streams support gzipped input and output via the `zlib
<http://www.zlib.net/>`_ library.  The ``.gz`` suffix on any filename
used to open a stream is recognized and the stream is read or written
in compressed format.  This mechanism does not interfere with the
format perception.  For instance, ``foo.sdf.gz`` is recognized as a
gzipped file in MDL's SD format.

The :oe:src:`Listing 6<SNIPPET-ReadWriteCompressedFiles>` example below
converts all of the molecules in a gzipped SD format file into a gzipped OEBinary
file.

.. oe:source:: ReadWriteCompressedFiles.cpp
   :language: c++
   :caption:  Reading and writing compressed molecule files
   :refnum:   6
   :frag:     SNIPPET

.. oe:source:: ReadWriteCompressedFiles.py
   :language: python
   :caption:  Reading and writing compressed molecule files
   :refnum:   6
   :frag:     SNIPPET

.. oe:source:: ReadWriteCompressedFiles.java
   :language: java
   :caption:  Reading and writing compressed molecule files
   :refnum:   6
   :frag:     SNIPPET

.. oe:source:: ReadWriteCompressedFiles.cs
   :language: csharp
   :caption:  Reading and writing compressed molecule files
   :refnum:   6
   :frag:     SNIPPET


The **OEChem TK**'s binary file format :oe:const:`OEChem::OEFormat::OEB` is
well suited  (and our preferred way) to store multi-conformer molecules.
When working with multi-conformer molecules of +1M datasets, the generated files
can easily reach a size when transferring them between computers or networks can be
slow.
One way to handle this issue is to compress the files with gzip before transfer.
As the above example shows  **OEChem TK**  seamlessly handles gzipped molecule
files with ``gz`` extension.
Alternatively, **OEChem TK** also provides a native compressed file format,
called :oe:const:`OEChem::OEFormat::OEZ`, with the ``oez`` file extension.
This file format currently only supports multi-conformer molecules
derived from the :ref:`OEMCMolBase <OEChem_OEMCMolBase>` class.

One of the main differences between the gzipped :oe:const:`OEChem::OEFormat::OEB`
and the :oe:const:`OEChem::OEFormat::OEZ` files that while gzip compresses a
molecular file as a whole, in an :oe:const:`OEChem::OEFormat::OEZ` file,
each molecule is individually compressed using the
`Zstandard <https://facebook.github.io/zstd/>`_ compression algorithm.

This difference makes :oe:const:`OEChem::OEFormat::OEZ` suitable to work
really well with :ref:`OEMolDatabase <OEChem_OEMolDatabase>` that is designed to provide
fast read-only random access to molecular files.
When an :ref:`OEMolDatabase <OEChem_OEMolDatabase>` opens a gzipped molecule file,
uncompressing the whole file is necessary to access any molecule in the
dataset.
When working with a :oe:const:`OEChem::OEFormat::OEZ` file,  accessing a
specific molecule in the file only triggers the un-compression of the
associated data chunk.

The table below lists the file sizes of the same dataset of 1M molecules
in uncompressed and compressed formats with different numbers of conformations
per molecule.

====================================== ======= ======= =======
Dataset                                oeb     oeb.gz  oez
====================================== ======= ======= =======
1M molecules with 10 conformations     5.4GB   1.9GB   2.2GB
1M molecules with 50 conformations     22GB    5.7GB   5.5GB
1M molecules with 200 conformations    69GB    16GB    13GB
====================================== ======= ======= =======

.. note::

   The :oe:const:`OEChem::OEFormat::OEZ` file format was introduced in the
   ``2019.Apr`` toolkits.
   OpenEye applications or toolkits released before Apr/2019 will **not**
   be able to read or write this new file format.

.. _section_molreadwrite_commandlineformatcontrol:

Command Line Format Control
============================================================================

Using the methods outlined above, it is possible to allow the stream
format to be controlled from the command line.  **OEChem TK**'s
:oe:cls:`oemolstreams<OEChem::oemolstreambase>` control the format by
interpreting the input and output file names.

.. oe:source:: ReadWriteCommandLineArgs.cpp
   :language: c++
   :caption:  Controlling File Format from the Command Line
   :refnum:   7
   :frag:     SNIPPET

.. oe:source:: ReadWriteCommandLineArgs.py
   :language: python
   :caption:  Controlling File Format from the Command Line
   :refnum:   7
   :frag:     SNIPPET

.. oe:source:: ReadWriteCommandLineArgs.java
   :language: java
   :caption:  Controlling File Format from the Command Line
   :refnum:   7
   :frag:     SNIPPET

.. oe:source:: ReadWriteCommandLineArgs.cs
   :language: csharp
   :caption:  Controlling File Format from the Command Line
   :refnum:   7
   :frag:     SNIPPET

:oe:src:`Listing 7<SNIPPET-ReadWriteCommandLineArgs>` is an example of using
command-line arguments to allow **OEChem TK** programs to support many file
formats at run-time. For instance, if :oe:src:`Listing
7<SNIPPET-ReadWriteCommandLineArgs>` is a program called *convert*::

   prompt> convert file1.sdf file1.smi

This command will convert *file1.sdf* from SD format to SMILES format.
A first extension of this idea allows access to standard in and
standard out via the "-" filename. For instance::

   prompt> convert file2.mol2 -

This command will convert ``file2.mol2`` in MOL2 format and write the
molecules to standard out in SMILES, the default format.

Thus if you have another program, *GetFromDatabase*, which retrieves
molecules from a database and writes them in SMILES format, you can
chain it with any **OEChem TK** program.  Using your operating systems
redirection commands (*e.g.* - Unix pipe "|" or redirect
">") you can move molecules directly from *GetFromDatabase*
to *convert* without a temporary file::

   prompt> GetFromDatabase | convert - file3.sdf

This command will take the SMILES format output from *GetFromDatabase*
and generate an SD format file.

However, to make this concept of using standard in and standard out
for piping data really useful, one needs to be able to control the
format of standard in and standard out similarly to the way it would
be controlled for temporary files.  To facilitate this,
:oe:cls:`oemolstreams<OEChem::oemolstreambase>` interpret filenames
which are ONLY format extensions to indicate format control for
standard in and standard out.

.. oe:source:: ReadWriteStdinStdoutFormatC.cpp
   :language: c++
   :caption:  Controlling standard in and standard out File Format
   :refnum:   8
   :frag:     SNIPPET

.. oe:source:: ReadWriteStdinStdoutFormatC.py
   :language: python
   :caption:  Controlling standard in and standard out File Format
   :refnum:   8
   :frag:     SNIPPET

.. oe:source:: ReadWriteStdinStdoutFormatC.java
   :language: java
   :caption:  Controlling standard in and standard out File Format
   :refnum:   8
   :frag:     SNIPPET

.. oe:source:: ReadWriteStdinStdoutFormatC.cs
   :language: csharp
   :caption:  Controlling standard in and standard out File Format
   :refnum:   8
   :frag:     SNIPPET

:oe:src:`Listing 8<SNIPPET-ReadWriteStdinStdoutFormatC>` is an example of
opening an :ref:`oemolistream <OEChem_oemolistream>` to standard in with the
format set to SDF. The output :ref:`oemolostream <OEChem_oemolostream>` is opened
to standard out with the format set to MOL2.  This is exactly
equivalent to :oe:src:`Listing 3<SNIPPET-ReadWriteSettingFormats>`.  However,
it demonstrates the extensibility of controlling the format of standard
in and standard out from the command line.

.. note::

   This prevents you from naming files as pure extensions: ``.mol2``,
   ``.sdf``, etc.

Now, using our program *convert* from :oe:src:`Listing 7<SNIPPET-ReadWriteCommandLineArgs>`
 it is possible to do the following::

   prompt> convert .sdf .mol2

This command opens standard in with the SDF format and opens standard
out with the MOL2 format.

Now there is complete format control of standard in and standard out
from the command line.  If we have a program *GenerateStructures*,
which only writes the MOL2 format and another program *GenerateData*,
which only reads the SD format, we can use them from the command line
with any **OEChem TK** program which uses command-line arguments for file
specification::

   prompt> GenerateStructures | convert .mol2 .sdf | GenerateData

This command demonstrates how any **OEChem TK** program with command-line
file specification can be used to pipe formatted input and output.

.. _section_molreadwrite_flavoredinputandoutput:

Flavored Input and Output
============================================================================

.. index::
   single: SetFlavor
   single: GetFlavor

The general goal of the :oe:cls:`oemolstream<OEChem::oemolstreambase>`
input and output classes in **OEChem TK** is to provide the user with
transparent access to the very complex task of reading and writing
molecules in a wide variety of formats.  However, occasionally, a
programmer may want to tweak the behavior of specific readers or
writers without abandoning the
:oe:cls:`oemolstreams<OEChem::oemolstreambase>` to use the low level
writers (such as :oe:func:`OEChem::OEWriteMDLFile`).  For these
instances, :oe:cls:`oemolstreams<OEChem::oemolstreambase>` provide the
:oe:meth:`OEChem::oemolstreambase::SetFlavor` and
:oe:meth:`OEChem::oemolstreambase::GetFlavor` methods.

The :oe:meth:`OEChem::oemolstreambase::SetFlavor` method takes two
unsigned integer arguments, the first is the format for which the
flavor is being specified and the second is the flavor itself.  The
formats are specified as discussed in
:ref:`section_molreadwrite_fileformats`.  The input flavors are
specified in the :oe:constns:`OEChem::OEIFlavor` namespace and the
output flavors are specified in the :oe:constns:`OEChem::OEOFlavor`
namespace.  Unlike the formats, the flavors are a bitmask and may be
binary OR'd together.  Under the :oe:constns:`OEChem::OEIFlavor` and
:oe:constns:`OEChem::OEOFlavor` namespaces, there is a namespace for
each format as well as a :oe:constns:`OEChem::OEIFlavor::Generic`
namespace.  The :oe:constns:`OEChem::OEOFlavor::Generic` namespace is
used to control aromaticity perception and other properties common to
all formats.  To completely specify a flavor, one would typically
binary-OR a :oe:constns:`OEChem::OEOFlavor::Generic` flag and a format
specific flag and pass the resultant value to
:oe:meth:`OEChem::oemolstreambase::SetFlavor`.

The default behavior for the :oe:func:`PDB
reader<OEChem::OEReadPDBFile>` is that
:oe:const:`TER<OEChem::OEIFlavor::PDB::TER>` specifies the termination
of a disconnected fragment within the same molecule while
:oe:const:`END<OEChem::OEIFlavor::PDB::END>` specifies the termination
of a connection table.  However, some users may want to have the
reader split :oe:func:`PDB<OEChem::OEReadPDBFile>` input files into
different molecules every time a
:oe:const:`TER<OEChem::OEIFlavor::PDB::TER>` appears.

The following code is an example of changing the
:oe:func:`PDB<OEChem::OEReadPDBFile>` reader flavor.

.. oe:source:: ReadWriteFlavors.cpp
   :language: c++
   :caption:  Changing oemolistream Reader Flavor
   :refnum:   9
   :frag:     SNIPPET

.. oe:source:: ReadWriteFlavors.py
   :language: python
   :caption:  Changing oemolistream Reader Flavor
   :refnum:   9
   :frag:     SNIPPET

.. oe:source:: ReadWriteFlavors.java
   :language: java
   :caption:  Changing oemolistream Reader Flavor
   :refnum:   9
   :frag:     SNIPPET

.. oe:source:: ReadWriteFlavors.cs
   :language: csharp
   :caption:  Changing oemolistream Reader Flavor
   :refnum:   9
   :frag:     SNIPPET

Similar low-level control can be exerted over both input and output
:oe:cls:`oemolstreams<OEChem::oemolstreambase>` using the powerful
:oe:meth:`OEChem::oemolstreambase::SetFlavor` method. See the API
documentation for the associated low-level routine and namespace for
details on the effects of specific flavor flags.

.. list-table:: **OEChem TK low-level readers and input flavors**
   :widths: 30 50 30
   :header-rows: 1

   * - File Format
     - Low-Level Reader
     - Input Flavors

   * - :oe:const:`OEChem::OEFormat::CAN`
     - :oe:func:`OEChem::OEParseSmiles`
     - :oe:constns:`OEChem::OEIFlavor::CAN`

   * - :oe:const:`OEChem::OEFormat::CDX`
     - :oe:func:`OEChem::OEReadCDXFile`
     - :oe:constns:`OEChem::OEIFlavor::CDX`

   * - :oe:const:`OEChem::OEFormat::CIF`
     - :oe:func:`OEChem::OEReadCIFFile`
     - :oe:constns:`OEChem::OEIFlavor::CIF`

   * - :oe:const:`OEChem::OEFormat::CSV`
     - :oe:func:`OEChem::OEReadCSVFile`
     - :oe:constns:`OEChem::OEIFlavor::CSV`

   * - :oe:const:`OEChem::OEFormat::CXSMILES`
     - 
     - :oe:constns:`OEChem::OEIFlavor::CXSMILES`

   * - :oe:const:`OEChem::OEFormat::FASTA`
     - :oe:func:`OEChem::OEReadFASTAFile`
     - :oe:constns:`OEChem::OEIFlavor::FASTA`

   * - :oe:const:`OEChem::OEFormat::ISM`
     - :oe:func:`OEChem::OEParseSmiles`
     - :oe:constns:`OEChem::OEIFlavor::ISM`

   * - :oe:const:`OEChem::OEFormat::MDL`
     - :oe:func:`OEChem::OEReadMDLFile`
     - :oe:constns:`OEChem::OEIFlavor::MDL`

   * - :oe:const:`OEChem::OEFormat::MF`
     -
     -

   * - :oe:const:`OEChem::OEFormat::MMCIF`
     - :oe:func:`OEChem::OEReadCIFFile`
     - :oe:constns:`OEChem::OEIFlavor::MMCIF`

   * - :oe:const:`OEChem::OEFormat::MMOD`
     - :oe:func:`OEChem::OEReadMacroModelFile`
     - :oe:constns:`OEChem::OEIFlavor::MMOD`

   * - :oe:const:`OEChem::OEFormat::MOL2`
     - :oe:func:`OEChem::OEReadMol2File`
     - :oe:constns:`OEChem::OEIFlavor::MOL2`

   * - :oe:const:`OEChem::OEFormat::MOL2H`
     - :oe:func:`OEChem::OEReadMol2File`
     - :oe:constns:`OEChem::OEIFlavor::MOL2H`

   * - :oe:const:`OEChem::OEFormat::MOPAC`
     -
     -

   * - :oe:const:`OEChem::OEFormat::OEB`
     - :oe:func:`OEChem::OEReadOEBFile`
     -
   * - :oe:const:`OEChem::OEFormat::OEZ`
     - N/A (:oe:func:`OEChem::OEReadMolecule` works)
     -

   * - :oe:const:`OEChem::OEFormat::PDB`
     - :oe:func:`OEChem::OEReadPDBFile`
     - :oe:constns:`OEChem::OEIFlavor::PDB`

   * - :oe:const:`OEChem::OEFormat::SDF`
     - :oe:func:`OEChem::OEReadMDLFile`
     - :oe:constns:`OEChem::OEIFlavor::SDF`

   * - :oe:const:`OEChem::OEFormat::SKC`
     - :oe:func:`OEChem::OEReadSketchFile`
     - :oe:constns:`OEChem::OEIFlavor::SKC`

   * - :oe:const:`OEChem::OEFormat::SLN`
     -
     -

   * - :oe:const:`OEChem::OEFormat::SMI`
     - :oe:func:`OEChem::OEParseSmiles`
     - :oe:constns:`OEChem::OEIFlavor::SMI`

   * - :oe:const:`OEChem::OEFormat::XYZ`
     - :oe:func:`OEChem::OEReadXYZFile`
     - :oe:constns:`OEChem::OEIFlavor::XYZ`


.. list-table:: **OEChem TK low-level writers and output flavors**
   :widths: 30 50 30
   :header-rows: 1

   * - File Format
     - Low-Level Writer
     - Output Flavors

   * - :oe:const:`OEChem::OEFormat::CAN`
     - :oe:func:`OEChem::OECreateCanSmiString`
     - :oe:constns:`OEChem::OEOFlavor::CAN`

   * - :oe:const:`OEChem::OEFormat::CIF`
     - :oe:func:`OEChem::OEWriteCIFFile`
     - :oe:constns:`OEChem::OEOFlavor::CIF`

   * - :oe:const:`OEChem::OEFormat::CDX`
     - :oe:func:`OEChem::OEWriteCDXFile`
     - :oe:constns:`OEChem::OEOFlavor::CDX`

   * - :oe:const:`OEChem::OEFormat::CSV`
     - :oe:func:`OEChem::OEWriteCSVFile`
     - :oe:constns:`OEChem::OEOFlavor::CSV`

   * - :oe:const:`OEChem::OEFormat::CXSMILES`
     - 
     - :oe:constns:`OEChem::OEOFlavor::CXSMILES`

   * - :oe:const:`OEChem::OEFormat::FASTA`
     - :oe:func:`OEChem::OEWriteFASTAFile`
     - :oe:constns:`OEChem::OEOFlavor::FASTA`

   * - :oe:const:`OEChem::OEFormat::ISM`
     - :oe:func:`OEChem::OECreateIsoSmiString`
     - :oe:constns:`OEChem::OEOFlavor::ISM`

   * - :oe:const:`OEChem::OEFormat::MDL`
     - :oe:func:`OEChem::OEWriteMDLFile`
     - :oe:constns:`OEChem::OEOFlavor::MDL`

   * - :oe:const:`OEChem::OEFormat::MF`
     - :oe:func:`OEChem::OEMolecularFormula`
     - :oe:constns:`OEChem::OEOFlavor::MF`

   * - :oe:const:`OEChem::OEFormat::MMCIF`
     - :oe:func:`OEChem::OEWriteCIFFile`
     - :oe:constns:`OEChem::OEOFlavor::MMCIF`

   * - :oe:const:`OEChem::OEFormat::MMOD`
     - :oe:func:`OEChem::OEWriteMacroModelFile`
     - :oe:constns:`OEChem::OEOFlavor::MMOD`

   * - :oe:const:`OEChem::OEFormat::MOL2`
     - :oe:func:`OEChem::OEWriteMol2File`
     - :oe:constns:`OEChem::OEOFlavor::MOL2`

   * - :oe:const:`OEChem::OEFormat::MOL2H`
     - :oe:func:`OEChem::OEWriteMol2File`
     - :oe:constns:`OEChem::OEOFlavor::MOL2H`

   * - :oe:const:`OEChem::OEFormat::MOPAC`
     - :oe:func:`OEChem::OEWriteMOPACInputFile`
     - :oe:constns:`OEChem::OEOFlavor::MOPAC`

   * - :oe:const:`OEChem::OEFormat::OEB`
     - N/A (:oe:func:`OEChem::OEWriteMolecule` works)
     -

   * - :oe:const:`OEChem::OEFormat::OEZ`
     - N/A (:oe:func:`OEChem::OEWriteMolecule` works)
     -

   * - :oe:const:`OEChem::OEFormat::PDB`
     - :oe:func:`OEChem::OEWritePDBFile`
     - :oe:constns:`OEChem::OEOFlavor::PDB`

   * - :oe:const:`OEChem::OEFormat::SDF`
     - :oe:func:`OEChem::OEWriteMDLFile`
     - :oe:constns:`OEChem::OEOFlavor::SDF`

   * - :oe:const:`OEChem::OEFormat::SKC`
     -
     -

   * - :oe:const:`OEChem::OEFormat::SLN`
     - :oe:func:`OEChem::OECreateSlnString`
     - :oe:constns:`OEChem::OEOFlavor::SLN`

   * - :oe:const:`OEChem::OEFormat::SMI`
     - :oe:func:`OEChem::OECreateSmiString`
     - :oe:constns:`OEChem::OEOFlavor::SMI`

   * - :oe:const:`OEChem::OEFormat::XYZ`
     - :oe:func:`OEChem::OEWriteXYZFile`
     - :oe:constns:`OEChem::OEOFlavor::XYZ`

   * - :oe:const:`OEChem::OEFormat::INCHI`
     - :oe:func:`OEChem::OECreateInChI`
     - :oe:constns:`OEChem::OEOFlavor::INCHI`


   * - :oe:const:`OEChem::OEFormat::INCHIKEY`
     - :oe:func:`OEChem::OECreateInChIKey`
     - :oe:constns:`OEChem::OEOFlavor::INCHIKEY`

.. note::

   Low-level readers will not call
   :oe:meth:`Clear<OEChem::OEMolBase::Clear>` on the molecule before
   reading the molecule into it. This is useful for concatenating
   multiple molecules together.

.. _section_molreadwrite_proppreserv:

Molecular Property Preservation
============================================================================

.. warning::

   :oe:func:`OEChem::OEWriteMolecule` will change your molecule!

The high-level :oe:func:`OEChem::OEWriteMolecule` function
standardizes the molecule according to the output type for uniformity.
For writing molecules without changing them, there are two options.
If you would like the data to appear in the file exactly as it is in
the molecule (perhaps *Tripos* atom names in a .pdb format), then you
should use a low level writer.  On the other hand, if you would like
to write a standardized molecule (*e.g.* *Tripos* atom types in a MOL2
file), but don't want your molecule changed, you can use
:oe:func:`OEChem::OEWriteConstMolecule`.
The :oe:func:`OEChem::OEWriteConstMolecule` function makes a copy of the
input molecule before performing the necessary perceptions and standardizations.
