chemfp.types module

exception chemfp.types.FingerprintValueError

Bases: ValueError, chemfp.ChemFPError

exception chemfp.types.FingerprintUnavailableError(base_name, toolkit_name, version, reason)

Bases: chemfp.types.FingerprintValueError

Raised when the fingerprint family is registered, but not available.

This may be if the underlying toolkit isn’t installed or isn’t licensed.

copy()
exception chemfp.types.FingerprintTypeError(name, reason)

Bases: chemfp.types.FingerprintValueError

Raised when the fingerprint type string is invalid.

exception chemfp.types.FingerprintTypeParameterError(type, parsed, reason)

Bases: chemfp.types.FingerprintValueError

Raised when one of the fingerprint type parameters is invalid.

get_fingerprint_family()
exception chemfp.types.FingerprintTypeUnknownError(family_name, registry, toolkit_name=None)

Bases: chemfp.types.FingerprintValueError

Raised when the fingerprint family is unknown.

add_aliases(aliases)

Include aliases {alias name -> chemfp family name} in the help

get_all_names()

Return a list of available fingerprint names as 2-element tuples

“This is part of the internal API”

get_help()

Get a help message about likely or possible names

get_suggestions(cutoff=0.6)

Return a list of likely fingerprint names as 2-element tuples

“This is part of the internal API”

include_help()
set_toolkit_name(toolkit_name)

Set the toolkit name used to get the list of available fingerprint types

class chemfp.types.FingerprintFamily(fingerprint_class)

Bases: chemfp.types.BaseFingerprintFamily

A FingerprintFamily is used to create a FingerprintType or get information about its parameters

Two reasons to use a FingerprintFamily (instead of using chemfp.get_fingerprint_type() or chemfp.get_fingerprint_type_from_text_settings()) are:

  • figure out the default arguments;
  • given a text settings or parameter dictionary, use the keys from the default argument keys to remove other parameters before creating a FingerprintType (otherwise the creation function will raise an exception)

All fingerprint families have the following attributes:

  • name - the type name, including version
  • toolkit - the toolkit API for the underlying chemistry toolkit, or None
base_name

The base fingerprint name, without the version

from_kwargs(fingerprint_kwargs=None)

Create a fingerprint type; items in the fingerprint_kwargs dictionary can override the defaults

The dictionary values are native Python values, not string-encoded values:

>>> import chemfp
>>> family = chemfp.get_fingerprint_family("RDKit-Fingerprint")
>>> fptype = family()
>>> fptype.get_type()
'RDKit-Fingerprint/2 minPath=1 maxPath=7 fpSize=2048 nBitsPerHash=2 useHs=1'
>>> fptype = family.from_kwargs({"fpSize": 1024})
>>> fptype.get_type()
'RDKit-Fingerprint/2 minPath=1 maxPath=7 fpSize=1024 nBitsPerHash=2 useHs=1'

The function will raise an exception for unknown arguments.

Parameters:fingerprint_kwargs (a dictionary where the values are Python objects) – the fingerprint parameters
Returns:an object implementing the chemfp.types.FingerprintType API
from_text_settings(settings=None)

Create a fingerprint type; settings is a dictionary with string-encoded value that can override the defaults

The dictionary values are string-encoded values, not native Python values. This function exists to help handle command-line arguments and setting files.:

>>> import chemfp
>>> family = chemfp.get_fingerprint_family("RDKit-Fingerprint")
>>> fptype = family.from_text_settings()
>>> fptype.get_type()
'RDKit-Fingerprint/2 minPath=1 maxPath=7 fpSize=2048 nBitsPerHash=2 useHs=1'
>>> fptype = family.from_text_settings({"fpSize": "1024"})
>>> fptype.get_type()
'RDKit-Fingerprint/2 minPath=1 maxPath=7 fpSize=1024 nBitsPerHash=2 useHs=1'

The function will raise an exception for unknown arguments.

Parameters:settings (a dictionary where the values are string-encoded) – the fingerprint text settings
Returns:an object implementing the chemfp.types.FingerprintType API
get_defaults()

Return the default parameters as a dictionary

The dictionary values are native Python objects:

>>> import chemfp
>>> family = chemfp.get_fingerprint_family("RDKit-Fingerprint")
>>> family.get_defaults()
{'maxPath': 7, 'fpSize': 2048, 'nBitsPerHash': 2, 'minPath': 1, 'useHs': 1}
Returns:an dictionary of fingerprint parameters
get_kwargs_from_text_settings(settings=None)

Convert a dictionary of string-encoded fingerprint parameters into native Python values

String-encoded values (“text settings”) can come from the command-line, a configuration file, a web reqest, or other text sources. The fingerprint types need actual Python values. This method converts the first to the second:

>>> import chemfp
>>> family = chemfp.get_fingerprint_family("RDKit-Fingerprint")
>>> family.get_kwargs_from_text_settings()
{'maxPath': 7, 'fpSize': 2048, 'nBitsPerHash': 2, 'minPath': 1, 'useHs': 1}
>>> family.get_kwargs_from_text_settings({"fpSize": "128", "maxPath": "5"})
{'maxPath': 5, 'fpSize': 128, 'nBitsPerHash': 2, 'minPath': 1, 'useHs': 1}
Parameters:settings (a dictionary where the values are string-encoded) – the fingerprint text settings
Returns:an dictionary of (decoded) fingerprint parameters
name

The full fingerprint name, including the version

toolkit

The chemfp toolkit wrapper for the chemistry toolkit used to generate this fingerprint, or None

version

The fingerprint version (the part after the ‘/’ in the full name)

class chemfp.types.NoFingerprintParametersMixin(fingerprint_kwargs)

Bases: object

This fingerprint type does not support parameters

class chemfp.types.BaseFingerprintType(fingerprint_kwargs)

Bases: object

base_name = None

the part of the name before the ‘/’

compute_fingerprint(mol)

Compute and return the fingerprint byte string for the toolkit molecule

Parameters:mol – a toolkit molecule
Returns:the fingerprint as a byte string
compute_fingerprints(mols)

Compute and return the fingerprint for each toolkit molecule in an iterator

This function is a slightly optimized version of:

for mol in mols:
  yield self.compute_fingerprint(mol)
Parameters:mols – an iterable of toolkit molecules
Returns:a generator of fingerprints, one per molecule
fingerprinter_can_fail = False

an internal flag indicating if the fingerprinter can raise an exception when processing a molecule

get_fingerprint_family()

Return the fingerprint family for this fingerprint type

Returns:a FingerprintFamily
get_type()

Get the full type string (name and parameters) for this fingerprint type

Returns:a canonical fingerprint type string, including its parameters
make_fingerprinter()

Make a ‘fingerprinter’; a callable which takes a molecule and returns a fingerprint

Returns:a function object which takes a molecule and return a fingerprint
make_id_and_molecule_fingerprint_parser(format, id_tag=None, reader_args=None, errors='strict')

Make a function which parses molecule from a record and returns the id and computed fingerprint

This is a very specialized function, designed for performance, but it doesn’t appear to give any advantage. You likely don’t need it.

Return a function which parses a content string containing structure records in the given format to get a molecule. Use the molecule to compute the fingerprint and get its id. For an SD record use id_tag to get the record id from the given SD tag instead of from the title line.

The new function will return the (id, fingerprint) pair.

The reader_args dictionary parameters depend on the toolkit and format. For details see the docstring for self.toolkit.read_molecules.

The errors parameter specifies how to handle errors. “strict” raises an exception, “report” sends a message to stderr and return None for values it cannot compute, and “ignore” is like “report” but without the error message. For “report” and “ignore”, if the molecule cannot be parsed then the result will be (None, None). If the fingerprint cannot be computed then the result will be (id, None).

Parameters:
  • format (a format name string, or Format object) – the input structure format
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (a dictionary) – reader parameters passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
Returns:

a function which takes a content string and returns an (id, fingerprint) pair
name = None

the fingerprint name

parse_id_and_molecule_fingerprint(content, format, id_tag=None, reader_args=None, errors='strict')

Parse the first molecule record of the content then compute and return the id and fingerprint

Read the first molecule from content, which contains records in the given format. Compute its fingerprint and get the molecule id. For an SD record use id_tag to get the record id from the given SD tag instead of from the title line.

Return the id and fingerprint as the (id, fingerprint) pair.

The reader_args dictionary parameters depend on the toolkit and format. For details see the docstring for self.toolkit.read_molecules.

The errors parameter specifies how to handle errors. “strict” raises an exception, “report” sends a message to stderr and return None for values it cannot compute, and “ignore” is like “report” but without the error message. For “report” and “ignore”, if the molecule cannot be parsed then the result will be (None, None). If the fingerprint cannot be computed then the result will be (id, None).

Parameters:
  • content – the string containing at least one structure record
  • format (a format name string, or Format object) – the input structure format
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (a dictionary) – reader parameters passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
Returns:

a pair of (id string, fingerprint byte string)
parse_molecule_fingerprint(content, format, reader_args=None, errors='strict')

Parse the first molecule record of the content then compute and return the fingerprint

Read the first molecule from content, which contains records in the given format. Compute and return its fingerprint.

The reader_args dictionary parameters depend on the toolkit and format. For details see the docstring for self.toolkit.read_molecules.

The errors parameter specifies how to handle errors. “strict” raises an exception, “report” sends a message to stderr and return None for the fingerprint, and “ignore” returns None for the fingerprint without any extra message.

Parameters:
  • content – the string containing at least one structure record
  • format (a format name string, or Format object) – the input structure format
  • reader_args (a dictionary) – reader parameters passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
Returns:

the fingerprint as a byte string
read_molecule_fingerprints(source, format=None, id_tag=None, reader_args=None, errors='strict', location=None)

Read fingerprints from a structure source as a FingerprintIterator

Iterate through the format structure records in source. If format is None then auto-detect the format based on the source. Use the fingerprint type to compute the fingerprint. For SD files, use id_tag to get the record id from the given SD tag instead of the title line.

The reader_args dictionary parameters depend on the toolkit and format. For details see the docstring for self.toolkit.read_molecules.

The errors parameter specifies how to handle errors. “strict” raises an exception, “report” sends a message to stderr and goes to the next record, and “ignore” goes to the next record.

The location parameter takes a Location instance. If None then a default Location will be created.

Parameters:
  • source (a filename, file object, or None to read from stdin) – the structure source
  • format (a format name string, or Format object, or None to auto-detect) – the input structure format
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (a dictionary) – reader parameters passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • location (a Location object, or None) – object used to track parser state information
Returns:

a chemfp.FingerprintIterator which iterates over the (id, fingerprint) pair
read_molecule_fingerprints_from_string(content, format=None, id_tag=None, reader_args=None, errors='strict', location=None)

Read fingerprints from structure records in a string, as a FingerprintIterator

Iterate through the format structure records in content. Use the fingerprint type to compute the fingerprint. For SD files, use id_tag to get the record id from the given SD tag instead of the title line.

The reader_args dictionary parameters depend on the toolkit and format. For details see the docstring for self.toolkit.read_molecules.

The errors parameter specifies how to handle errors. “strict” raises an exception, “report” sends a message to stderr and goes to the next record, and “ignore” goes to the next record.

The location parameter takes a Location instance. If None then a default Location will be created.

Parameters:
  • content – the string containing structure records
  • format (a format name string, or Format object) – the input structure format
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (a dictionary) – reader parameters passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • location (a Location object, or None) – object used to track parser state information
Returns:

a chemfp.FingerprintIterator which iterates over the (id, fingerprint) pair
software = None

a description of the software package(s) used

toolkit = None

a reference to the underlying toolkit wrapper

version = None

the part of the name after the ‘/’

class chemfp.types.ThreadsafeFingerprinterMixin(fingerprint_kwargs)

Bases: object

This fingerprint type is thread-safe.

The make_fingerprint() method always returns the same fingerprinter.

make_fingerprinter()
class chemfp.types.FingerprintType(fingerprint_kwargs)

Bases: chemfp.types.BaseFingerprintType

The base to all fingerprint types

A fingerprint type has the following public attributes:

The built-in fingerprint types are:

compute_fingerprint(mol)

Compute and return the fingerprint byte string for the toolkit molecule

Parameters:mol – a toolkit molecule
Returns:the fingerprint as a byte string
compute_fingerprints(mols)

Compute and return the fingerprint for each toolkit molecule in an iterator

This function is a slightly optimized version of:

for mol in mols:
  yield self.compute_fingerprint(mol)
Parameters:mols – an iterable of toolkit molecules
Returns:a generator of fingerprints, one per molecule
from_mol(mol)

Return the corresponding fingerprint byte string for the molecule

from_mols(mols)

Return the corresponding fingerprint byte strings for a stream of molecules

get_metadata(sources=None)

Return a Metadata appropriate for the given fingerprint type.

This is most commonly used to make a chemfp.Metadata that can be passed into a chemfp.FingerprintWriter.

If sources is a string or a list of strings then it will passed to the newly created Metadata instance. It should contain filenames or other description of the fingerprint sources.

Parameters:sources (None, a string, or list of strings) – fingerprint source filenames or other description
Returns:a chemfp.Metadata
get_type()

Get the full type string (name and parameters) for this fingerprint type

Returns:a canonical fingerprint type string, including its parameters
make_fingerprinter()

Make a ‘fingerprinter’; a callable which takes a molecule and returns a fingerprint

Returns:a function object which takes a molecule and return a fingerprint
make_id_and_molecule_fingerprint_parser(format, id_tag=None, reader_args=None, errors='strict')

Make a function which parses molecule from a record and returns the id and computed fingerprint

This is a very specialized function, designed for performance, but it doesn’t appear to give any advantage. You likely don’t need it.

Return a function which parses a content string containing structure records in the given format to get a molecule. Use the molecule to compute the fingerprint and get its id. For an SD record use id_tag to get the record id from the given SD tag instead of from the title line.

The new function will return the (id, fingerprint) pair.

The reader_args dictionary parameters depend on the toolkit and format. For details see the docstring for self.toolkit.read_molecules.

The errors parameter specifies how to handle errors. “strict” raises an exception, “report” sends a message to stderr and return None for values it cannot compute, and “ignore” is like “report” but without the error message. For “report” and “ignore”, if the molecule cannot be parsed then the result will be (None, None). If the fingerprint cannot be computed then the result will be (id, None).

Parameters:
  • format (a format name string, or Format object) – the input structure format
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (a dictionary) – reader parameters passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
Returns:

a function which takes a content string and returns an (id, fingerprint) pair
parse_id_and_molecule_fingerprint(content, format, id_tag=None, reader_args=None, errors='strict')

Parse the first molecule record of the content then compute and return the id and fingerprint

Read the first molecule from content, which contains records in the given format. Compute its fingerprint and get the molecule id. For an SD record use id_tag to get the record id from the given SD tag instead of from the title line.

Return the id and fingerprint as the (id, fingerprint) pair.

The reader_args dictionary parameters depend on the toolkit and format. For details see the docstring for self.toolkit.read_molecules.

The errors parameter specifies how to handle errors. “strict” raises an exception, “report” sends a message to stderr and return None for values it cannot compute, and “ignore” is like “report” but without the error message. For “report” and “ignore”, if the molecule cannot be parsed then the result will be (None, None). If the fingerprint cannot be computed then the result will be (id, None).

Parameters:
  • content – the string containing at least one structure record
  • format (a format name string, or Format object) – the input structure format
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (a dictionary) – reader parameters passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
Returns:

a pair of (id string, fingerprint byte string)
parse_molecule_fingerprint(content, format, reader_args=None, errors='strict')

Parse the first molecule record of the content then compute and return the fingerprint

Read the first molecule from content, which contains records in the given format. Compute and return its fingerprint.

The reader_args dictionary parameters depend on the toolkit and format. For details see the docstring for self.toolkit.read_molecules.

The errors parameter specifies how to handle errors. “strict” raises an exception, “report” sends a message to stderr and return None for the fingerprint, and “ignore” returns None for the fingerprint without any extra message.

Parameters:
  • content – the string containing at least one structure record
  • format (a format name string, or Format object) – the input structure format
  • reader_args (a dictionary) – reader parameters passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
Returns:

the fingerprint as a byte string
read_molecule_fingerprints(source, format=None, id_tag=None, reader_args=None, errors='strict', location=None)

Read fingerprints from a structure source as a FingerprintIterator

Iterate through the format structure records in source. If format is None then auto-detect the format based on the source. Use the fingerprint type to compute the fingerprint. For SD files, use id_tag to get the record id from the given SD tag instead of the title line.

The reader_args dictionary parameters depend on the toolkit and format. For details see the docstring for self.toolkit.read_molecules.

The errors parameter specifies how to handle errors. “strict” raises an exception, “report” sends a message to stderr and goes to the next record, and “ignore” goes to the next record.

The location parameter takes a Location instance. If None then a default Location will be created.

Parameters:
  • source (a filename, file object, or None to read from stdin) – the structure source
  • format (a format name string, or Format object, or None to auto-detect) – the input structure format
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (a dictionary) – reader parameters passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • location (a Location object, or None) – object used to track parser state information
Returns:

a chemfp.FingerprintIterator which iterates over the (id, fingerprint) pair
read_molecule_fingerprints_from_string(content, format=None, id_tag=None, reader_args=None, errors='strict', location=None)

Read fingerprints from structure records in a string, as a FingerprintIterator

Iterate through the format structure records in content. Use the fingerprint type to compute the fingerprint. For SD files, use id_tag to get the record id from the given SD tag instead of the title line.

The reader_args dictionary parameters depend on the toolkit and format. For details see the docstring for self.toolkit.read_molecules.

The errors parameter specifies how to handle errors. “strict” raises an exception, “report” sends a message to stderr and goes to the next record, and “ignore” goes to the next record.

The location parameter takes a Location instance. If None then a default Location will be created.

Parameters:
  • content – the string containing structure records
  • format (a format name string, or Format object) – the input structure format
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (a dictionary) – reader parameters passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • location (a Location object, or None) – object used to track parser state information
Returns:

a chemfp.FingerprintIterator which iterates over the (id, fingerprint) pair
software = None
toolkit = None