.. _chemfp-api:

chemfp API
==============

This chapter contains the docstrings for the public portion of the
chemfp API. Chemfp also has internal modules and functions that should
not be imported or used directly. If you use parts of the undocumented
API then your code is more likely to break with newer chemfp releases.

See ":ref:`getting_started_api`" for some introductory examples.


.. toctree::
   :maxdepth: 2
   :titlesonly:

   chemfp top-level <chemfp_toplevel>
   chemfp.arena <chemfp_arena>
   chemfp.base_toolkit <chemfp_base_toolkit>
   chemfp.bitops <chemfp_bitops>
   chemfp.cdk_toolkit <chemfp_cdk_toolkit>
   chemfp.cdk_types <chemfp_cdk_types>
   chemfp.csv_readers <chemfp_csv_readers>
   chemfp.diversity <chemfp_diversity>
   chemfp.encodings <chemfp_encodings>
   chemfp.fpb_io <chemfp_fpb_io>
   chemfp.fps_io <chemfp_fps_io>
   chemfp.fps_search <chemfp_fps_search>
   chemfp.highlevel.clustering <chemfp_highlevel_clustering>
   chemfp.highlevel.conversion <chemfp_highlevel_conversion>
   chemfp.highlevel.diversity <chemfp_highlevel_diversity>
   chemfp.highlevel.similarity <chemfp_highlevel_similarity>
   chemfp.io <chemfp_io>
   chemfp.openbabel_toolkit <chemfp_openbabel_toolkit>
   chemfp.openbabel_types <chemfp_openbabel_types>
   chemfp.openeye_toolkit <chemfp_openeye_toolkit>
   chemfp.openeye_types <chemfp_openeye_types>
   chemfp.rdkit_toolkit <chemfp_rdkit_toolkit>
   chemfp.rdkit_types <chemfp_rdkit_types>
   chemfp.search <chemfp_search>
   chemfp.text_records <chemfp_text_records>
   chemfp.text_toolkit <chemfp_text_toolkit>
   chemfp.types <chemfp_types>

Overview
----------------------
   
The top-level chemfp module is the starting point for using chemfp. It
contains functions to read and write fingerprint files, "high-level"
commands for working with chemfp, and more.

The API for the FPS and FPS fingerprint readers and writers are
defined in :mod:`chemfp.fps_io` and :mod:`chemfp.fpb_io`, which may
refer to a :class:`.Location` object defined in :mod:`chemfp.io`.

The fingerprint arena class is defined in :mod:`chemfp.arena`.

The :mod:`chemfp.search` module contains similarity search functions
for searching fingerprint arenas, and the :class:`.SearchResult` and
:class:`.SearchResults` result class definitions. This is lower-level
API than using :func:`chemfp.simsearch`.

The :mod:`chemfp.fps_search` module contains similarity search
functions for searching FPS files, and the search result class
definitions. This is only needed when working in a streaming
environment where fingerprint arena creation overhead is too large.

The :mod:`chemfp.diversity` module contains chemfp's diversity
pickers, all of which require a fingerprint arena. This is a
lower-level API than using :func:`chemfp.maxmin`,
:func:`chemfp.heapsweep`, or :func:`chemfp.spherex`.
      
The :mod:`chemfp.clustering` module contains the
:class:`.ButinaClusters` result from Butina clustering using
:func:`chemfp.butina`.

The :mod:`chemfp.cdk_toolkit`, :mod:`chemfp.openbabel_toolkit`,
:mod:`chemfp.openeye_toolkit` and :mod:`chemfp.rdkit_toolkit` modules
contain the public-facing API for chemfp's cheminformatics toolkit
wrapper implementations. The :attr:`chemfp.cdk`,
:attr:`chemfp.openbabel`, :attr:`chemfp.openeye`, :attr:`chemfp.rdkit`
objects will automatically import the underlying toolkit and forward
to them.

Sometimes you need to work with SMILES or SD files as text records,
not molecules. For that, use the :mod:`chemfp.text_toolkit` module.

Sometimes you need to work with CVS files containing structure records
or fingerprint. For that, use the :mod:`chemfp.csv_readers` module or
the ``read_csv_ids_and_molecules`` function in the toolkit wrapper
module.

The :mod:`chemfp.bitops` module has functions to work with
fingerprints represented as byte strings or hex-encoded strings, as
well as configuration functions for configuring chemfp's bit
operations. Use the :mod:`chemfp.encodings` to decode from various
fingerprint string representations to a byte string.

Finally, the :mod:`chemfp.types` module contains a few public
exceptions which derived from ValueError but which don't yet also
derive from ChemFPError.