{% from "macros.txt" import pyfunc, pyclass, pymethod, tkfunc, pyproperty, pycfunc, reader_pyclass %}

.. py:module:: chemfp 

.. _chemfp-api:

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

This chapter contains the docstrings for the public portion of the
chemfp API.

=======================
chemfp top-level module
=======================

The following functions and classes are in the top-level chemfp module.

{{ pyfunc("chemfp.open") }}

{{ pyfunc("chemfp.load_fingerprints") }}

{{ pyfunc("chemfp.read_structure_fingerprints") }}
{{ pyfunc("chemfp.read_molecule_fingerprints") }}

{{ pyfunc("chemfp.open_fingerprint_writer") }}

{{ pyclass("chemfp.ChemFPError") }}

{{ pyclass("chemfp.ParseError") }}

{{ pyclass("chemfp.Metadata") }}
{{ pymethod("chemfp.Metadata.__repr__") }}
{{ pymethod("chemfp.Metadata.__str__") }}
{{ pymethod("chemfp.Metadata.copy") }}

{{ pyclass("chemfp.FingerprintReader") }}
{{ pymethod("chemfp.FingerprintReader.__iter__") }}
{{ pymethod("chemfp.FingerprintReader.iter_arenas") }}
{{ pymethod("chemfp.FingerprintReader.save") }}
{{ pymethod("chemfp.FingerprintReader.get_fingerprint_type") }}

{{ pyclass("chemfp.FingerprintIterator") }}
{{ pymethod("chemfp.FingerprintIterator.__init__") }}
{{ pymethod("chemfp.FingerprintIterator.__iter__") }}
{{ pymethod("chemfp.FingerprintIterator.close") }}

{{ pyclass("chemfp.Fingerprints") }}
{{ pymethod("chemfp.Fingerprints.__init__") }}

{{ pyclass("chemfp.FingerprintWriter") }}
{{ pymethod("chemfp.FingerprintWriter.write_fingerprint") }}
{{ pymethod("chemfp.FingerprintWriter.write_fingerprints") }}
{{ pymethod("chemfp.FingerprintWriter.close") }}

{{ pyclass("chemfp.ChemFPProblem") }}
{{ pyfunc("chemfp.check_fingerprint_problems") }}
{{ pyfunc("chemfp.check_metadata_problems") }}

{{ pyfunc("chemfp.count_tanimoto_hits") }}
{{ pyfunc("chemfp.count_tanimoto_hits_symmetric") }}
{{ pyfunc("chemfp.threshold_tanimoto_search") }}
{{ pyfunc("chemfp.threshold_tanimoto_search_symmetric") }}
{{ pyfunc("chemfp.knearest_tanimoto_search") }}
{{ pyfunc("chemfp.knearest_tanimoto_search_symmetric") }}


{{ pyfunc("chemfp.get_max_threads") }}
{{ pyfunc("chemfp.get_num_threads") }}
{{ pyfunc("chemfp.set_num_threads") }}


Open Babel fingerprints
=======================

Open Babel implements four fingerprints families and chemfp implements
two fingerprint families using the Open Babel toolkit. These are:

* OpenBabel-FP2 - Indexes linear fragments up to 7 atoms.
* OpenBabel-FP3 - SMARTS patterns specified in the file patterns.txt
* OpenBabel-FP4 - SMARTS patterns specified in the file SMARTS_InteLigand.txt
* OpenBabel-MACCS - SMARTS patterns specified in the file MACCS.txt, which
  implements nearly all of the 166 MACCS keys
* RDMACCS-OpenBabel - a chemfp implementation of nearly all of the
  MACCS keys
* ChemFP-Substruct-OpenBabel - an experimental chemfp implementation
  of the PubChem keys

Most people use FP2 and MACCS.

Note: chemfp, starting with version 1.3, implements both
RDMACCS-OpenBabel/1 and RDMACCS-OpenBabel/2. Version 1.1 did not have
a definition for key 44.


OpenEye fingerprints
====================

OpenEye's OEGraphSim library implements four bitstring-based
fingerprint families, and chemfp implements two fingerprint families
based on OEChem. These are:

* OpenEye-Path - exhaustive enumeration of all linear fragments
  up to a given size
* OpenEye-Circular - exhaustive enumeration of all circular
  fragments grown radially from each heavy atom up to a given radius
* OpenEye-Tree - exhaustive enumeration of all trees up to
  a given size
* OpenEye-MACCS166 - an implementation of the 166 MACCS keys
* RDMACCS-OpenEye - a chemfp implementation of the 166 MACCS keys
* ChemFP-Substruct-OpenEye - an experimental chemfp implementation
  of the PubChem keys

Note: chemfp, starting with version 1.3, implements both
RDMACCS-OpenEye/1 and RDMACCS-OpenEye/2. Version 1.1 did not have a
definition for key 44.


RDKit fingerprints
==================

RDKit implements nine fingerprint families, and chemfp implements two
fingerprint families based on RDKit. These are:

* RDKit-Fingerprint - exhaustive enumeration of linear and branched trees
* RDKit-MACCS166 - The RDKit implementation of the MACCS keys
* RDKit-Morgan - EFCP-like circular fingerprints
* RDKit-AtomPair - atom pair fingerprints
* RDKit-Torsion - topological-torsion fingerprints
* RDKit-Pattern - substructure screen fingerprint 
* RDKit-Avalon - RDKit's interface to the Avalon toolkit fingerprints
* RDMACCS-RDKit - a chemfp implementation of the 166 MACCS keys
* ChemFP-Substruct-RDKit - an experimental chemfp implementation
  of the PubChem keys

Note: chemfp, starting with version 1.3, implements both
RDMACCS-OpenEye/1 and RDMACCS-OpenEye/2. Version 1.1 did not have a
definition for key 44.

===================
chemfp.arena module
===================

There should be no reason for you to import this module yourself. It
contains the :class:`.FingerprintArena`
implementation. FingerprintArena instances are returns part of the
public API but should not be constructed directly.

.. py:module:: chemfp.arena

{{ pyclass("chemfp.arena.FingerprintArena") }}
{{ pymethod("chemfp.arena.FingerprintArena.__len__") }}
{{ pymethod("chemfp.arena.FingerprintArena.__getitem__") }}
{{ pymethod("chemfp.arena.FingerprintArena.__iter__") }}
{{ pymethod("chemfp.FingerprintReader.get_fingerprint_type") }}
{{ pymethod("chemfp.arena.FingerprintArena.get_fingerprint") }}
{{ pymethod("chemfp.arena.FingerprintArena.get_by_id") }}
{{ pymethod("chemfp.arena.FingerprintArena.get_index_by_id") }}
{{ pymethod("chemfp.arena.FingerprintArena.get_fingerprint_by_id") }}
{{ pymethod("chemfp.arena.FingerprintArena.save") }}
{{ pymethod("chemfp.arena.FingerprintArena.iter_arenas") }}
{{ pymethod("chemfp.arena.FingerprintArena.copy") }}

{{ pymethod("chemfp.arena.FingerprintArena.count_tanimoto_hits_fp") }}
{{ pymethod("chemfp.arena.FingerprintArena.threshold_tanimoto_search_fp") }}
{{ pymethod("chemfp.arena.FingerprintArena.knearest_tanimoto_search_fp") }}


====================
chemfp.search module
====================

.. _chemfp_search:
.. py:module:: chemfp.search


The following functions and classes are in the chemfp.search module.

There are three main classes of functions. The ones ending with
``*_fp`` use a query fingerprint to search a target arena. The ones
ending with ``*_arena`` use a query arena to search a target
arena. The ones ending with ``*_symmetric`` use arena to search
itself, except that a fingerprint is not tested against itself.


These functions share the same name with very similar functions in the
top-level :mod:`chemfp` module. My apologies for any confusion. The
top-level functions are designed to work with both arenas and
iterators as the target. They give a simple search API, and
automatically process in blocks, to give a balanced trade-off between
performance and response time for the first results.

The functions in this module only work with arena as the target. By
default it searches the entire arena before returning. If you want to
process portions of the arena then you need to specify the range
yourself.


{{ pyfunc("chemfp.search.count_tanimoto_hits_fp") }}
{{ pyfunc("chemfp.search.count_tanimoto_hits_arena") }}
{{ pyfunc("chemfp.search.count_tanimoto_hits_symmetric") }} 
{{ pyfunc("chemfp.search.partial_count_tanimoto_hits_symmetric") }}

{{ pyfunc("chemfp.search.threshold_tanimoto_search_fp") }}
{{ pyfunc("chemfp.search.threshold_tanimoto_search_arena") }}
{{ pyfunc("chemfp.search.threshold_tanimoto_search_symmetric") }} 
{{ pyfunc("chemfp.search.partial_threshold_tanimoto_search_symmetric") }}
{{ pyfunc("chemfp.search.fill_lower_triangle") }}

{{ pyfunc("chemfp.search.knearest_tanimoto_search_fp") }}
{{ pyfunc("chemfp.search.knearest_tanimoto_search_arena") }}
{{ pyfunc("chemfp.search.knearest_tanimoto_search_symmetric") }}

{{ pyfunc("chemfp.search.contains_fp") }}
{{ pyfunc("chemfp.search.contains_arena") }}


{{ pyclass("chemfp.search.SearchResults") }}
{{ pymethod("chemfp.search.SearchResults.__len__") }}
{{ pymethod("chemfp.search.SearchResults.__iter__") }}
{{ pymethod("chemfp.search.SearchResults.__getitem__") }}
{{ pyproperty("chemfp.search.SearchResults.shape") }}
{{ pymethod("chemfp.search.SearchResults.iter_indices") }}
{{ pymethod("chemfp.search.SearchResults.iter_ids") }}
{{ pymethod("chemfp.search.SearchResults.iter_scores") }}
{{ pymethod("chemfp.search.SearchResults.iter_indices_and_scores") }}
{{ pymethod("chemfp.search.SearchResults.iter_ids_and_scores") }}
{{ pymethod("chemfp.search.SearchResults.clear_all") }}
{{ pymethod("chemfp.search.SearchResults.count_all") }}
{{ pymethod("chemfp.search.SearchResults.cumulative_score_all") }}
{{ pymethod("chemfp.search.SearchResults.reorder_all") }}
{{ pymethod("chemfp.search.SearchResults.to_csr") }}

{{ pyclass("chemfp.search.SearchResult") }}
{{ pymethod("chemfp.search.SearchResult.__len__") }}
{{ pymethod("chemfp.search.SearchResult.__iter__") }}
{{ pymethod("chemfp.search.SearchResult.clear") }}
{{ pymethod("chemfp.search.SearchResult.get_indices") }}
{{ pymethod("chemfp.search.SearchResult.get_ids") }}
{{ pymethod("chemfp.search.SearchResult.iter_ids") }}
{{ pymethod("chemfp.search.SearchResult.get_scores") }}
{{ pymethod("chemfp.search.SearchResult.get_ids_and_scores") }}
{{ pymethod("chemfp.search.SearchResult.get_indices_and_scores") }}
{{ pymethod("chemfp.search.SearchResult.reorder") }}
{{ pymethod("chemfp.search.SearchResult.count") }}
{{ pymethod("chemfp.search.SearchResult.cumulative_score") }}

.. _chemfp.bitops:

=====================
chemfp.bitops module
=====================

.. py:module:: chemfp.bitops

The following functions from the chemfp.bitops module provide
low-level bit operations on byte and hex fingerprints.

{{ pycfunc("chemfp.bitops.byte_contains") }}
{{ pycfunc("chemfp.bitops.byte_contains_bit") }}
{{ pycfunc("chemfp.bitops.byte_difference") }}
{{ pycfunc("chemfp.bitops.byte_from_bitlist") }}
{{ pycfunc("chemfp.bitops.byte_hex_tanimoto") }}
{{ pycfunc("chemfp.bitops.byte_intersect") }}
{{ pycfunc("chemfp.bitops.byte_intersect_popcount") }}
{{ pycfunc("chemfp.bitops.byte_popcount") }}
{{ pycfunc("chemfp.bitops.byte_tanimoto") }}
{{ pycfunc("chemfp.bitops.byte_to_bitlist") }}
{{ pycfunc("chemfp.bitops.byte_union") }}
{{ pycfunc("chemfp.bitops.hex_contains") }}
{{ pycfunc("chemfp.bitops.hex_contains_bit") }}
{{ pycfunc("chemfp.bitops.hex_difference") }}
{{ pycfunc("chemfp.bitops.hex_from_bitlist") }}
{{ pycfunc("chemfp.bitops.hex_intersect") }}
{{ pycfunc("chemfp.bitops.hex_intersect_popcount") }}
{{ pycfunc("chemfp.bitops.hex_isvalid") }}
{{ pycfunc("chemfp.bitops.hex_popcount") }}
{{ pycfunc("chemfp.bitops.hex_tanimoto") }}
{{ pycfunc("chemfp.bitops.hex_to_bitlist") }}
{{ pycfunc("chemfp.bitops.hex_union") }}
{{ pycfunc("chemfp.bitops.hex_encode") }}
{{ pycfunc("chemfp.bitops.hex_encode_as_bytes") }}
{{ pycfunc("chemfp.bitops.hex_decode") }}

================
chemfp.encodings
================

.. py:module:: chemfp.encodings

Decode different fingerprint representations into chemfp
form. (Currently only decoders are available. Future released may
include encoders.)

{{ docstring_body("chemfp.encodings") }}

{{ pyfunc("chemfp.encodings.from_binary_lsb") }}
{{ pyfunc("chemfp.encodings.from_binary_msb") }}
{{ pyfunc("chemfp.encodings.from_base64") }}
{{ pyfunc("chemfp.encodings.from_hex") }}
{{ pyfunc("chemfp.encodings.from_hex_msb") }}
{{ pyfunc("chemfp.encodings.from_hex_lsb") }}
{{ pyfunc("chemfp.encodings.from_cactvs") }}
{{ pyfunc("chemfp.encodings.from_daylight") }}
{{ pyfunc("chemfp.encodings.from_on_bit_positions") }}


.. py:module:: chemfp.fps_io

==================== 
chemfp.fps_io module
====================

This module is part of the private API. Do not import it directly.

The function :func:`chemfp.open` returns an FPSReader if the source is
an FPS file. The function :func:`chemfp.open_fingerprint_writer`
returns an FPSWriter if the destination is an FPS file.

{{ pyclass("chemfp.fps_io.FPSReader") }}

{{ pymethod("chemfp.fps_io.FPSReader.__iter__") }}
{{ pymethod("chemfp.fps_io.FPSReader.iter_arenas") }}
{{ pymethod("chemfp.fps_io.FPSReader.save") }}
{{ pymethod("chemfp.fps_io.FPSReader.get_fingerprint_type") }}
{{ pymethod("chemfp.fps_io.FPSReader.close") }}

{{ pymethod("chemfp.fps_io.FPSReader.count_tanimoto_hits_fp") }}
{{ pymethod("chemfp.fps_io.FPSReader.count_tanimoto_hits_arena") }}
{{ pymethod("chemfp.fps_io.FPSReader.threshold_tanimoto_search_fp") }}
{{ pymethod("chemfp.fps_io.FPSReader.threshold_tanimoto_search_arena") }}
{{ pymethod("chemfp.fps_io.FPSReader.knearest_tanimoto_search_fp") }}
{{ pymethod("chemfp.fps_io.FPSReader.knearest_tanimoto_search_arena") }}


{{ pyclass("chemfp.fps_io.FPSWriter") }}
{{ pymethod("chemfp.fps_io.FPSWriter.write_fingerprint") }}
{{ pymethod("chemfp.fps_io.FPSWriter.write_fingerprints") }} 
{{ pymethod("chemfp.fps_io.FPSWriter.close") }} 


================
chemfp.io module
================

.. py:module:: chemfp.io

This module implements a single public class, :class:`Location`, which
tracks parser state information, including the location of the current
record in the file. The other functions and classes are undocumented,
should not be used, and may change in future releases.

{{ pyclass("chemfp.io.Location") }}
{{ pymethod("chemfp.io.Location.__init__") }}
{{ pymethod("chemfp.io.Location.from_source") }}
{{ pymethod("chemfp.io.Location.from_destination") }}
{{ pymethod("chemfp.io.Location.__repr__") }}
{{ pyproperty("chemfp.io.Location.first_line") }} 

  .. py:attribute:: Location.filename

     Read/write attribute.

     A string which describes the source or destination. This is usually
     the source or destination filename but can be a string like "<stdin>"
     or "<stdout>".

{{ pyproperty("chemfp.io.Location.mol") }} 
{{ pyproperty("chemfp.io.Location.offsets") }} 
{{ pyproperty("chemfp.io.Location.output_recno") }} 
{{ pyproperty("chemfp.io.Location.recno") }} 
{{ pyproperty("chemfp.io.Location.record") }} 
{{ pyproperty("chemfp.io.Location.record_format") }} 
{{ pymethod("chemfp.io.Location.where") }}
