Class CircularFragmenter

java.lang.Object
org.openscience.cdk.fragment.CircularFragmenter
public class CircularFragmenter extends Object
Extracts atom-centered circular / spherical fragments from a molecule, analogous to HOSE codes, circular Morgan-type fingerprints, and Molecular Signatures.

For every atom in the input molecule, the neighborhood up to a user-defined radius (number of bonds, also called "height" or "level") is collected by a breadth-first expansion and returned as an independent IAtomContainer. All atoms and bonds in the resulting containers are deep copies of the originals, so modifying them does not affect the source molecule.

Usage example:

IAtomContainer molecule = ...; // fully configured molecule
CircularFragmenter fragmenter = new CircularFragmenter(3); //radius 3, also the default
List<IAtomContainer> fragments = fragmenter.getCircularFragments(molecule);

The list index of each fragment corresponds to the index of the center atom (also called "root") in the original atom container. But note that fragments.get(i).contains(mol.getAtom(i)) will produce false because the atoms (and bonds) are copied at fragment extraction.

Each atom in a fragment has the property with key FRAGMENT_ATOM_DEPTH_PROPERTY_KEY set, which contains the depth (sphere nr. / level / height) of the respective atom in the respective fragment. 0 stands for the center atom. These can, e.g., be used to generate SMILES strings of a fragment with atom-atom-mappings corresponding to the respective depth of each atom.

Additional configuration options (to the radius) include the saturation of the fragments where bonds were broken (either, per default, with implicit hydrogen atoms or, alternatively, with pseudo atoms to mark the attachment points) and whether stereochemistry annotations should be preserved in the fragments (default: false).

Note that the resulting fragments are not deduplicated! So, if you, e.g., fragment benzene with a radius of 3, you will get six benzene "fragments" as a result, since a radius of three includes the entire molecule, independent of which atom is taken as the center.

Also note that whether you have done an aromaticity perception or not on your input molecule before using this fragmentation routine influences the results, especially when analyzing a whole collection of molecules and deduplicating the fragments afterward.

Scaling: Let n be the number of atoms and r the radius. A single fragment extraction scales with the number of atoms k in the fragment (approx. min(n, 3r)). Extracting all fragments takes O(n·k). For typical small radii, this is effectively linear O(n); for large radii covering the whole molecule, it is O(n2).

Author:
Jonas Schaub (jonas.schaub@uni-jena.de | jonas-schaub@gmx.de | JonasSchaub on GitHub)
Keywords:
fragment, circular fingerprint, HOSE code, molecular signature, spherical environment

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    FRAGMENT_ATOM_DEPTH_PROPERTY_KEY
    Property key to retrieve the depth (sphere nr. / level / height) of a fragment atom in the respective circular fragment. 0 stands for the center atom.

  • Constructor Summary

    Constructors
    Constructor
    Description
    CircularFragmenter()
    Creates a new CircularFragmenter with the default radius (= 3 bonds), the default stereochemistry setting (= false, no preservation of stereochemistry), and the default attachment point marking setting (= false, no marking of attachment points; saturation with implicit hydrogen atoms instead).
    CircularFragmenter(int radius)
    Creates a new CircularFragmenter with the given radius, the default stereochemistry setting (= false, no preservation of stereochemistry), and the default attachment point marking setting (= false, no marking of attachment points; saturation with implicit hydrogen atoms instead).
    CircularFragmenter(int radius, boolean preserveStereo)
    Creates a new CircularFragmenter with the given radius and stereochemistry setting and the default attachment point marking setting (= false, no marking of attachment points; saturation with implicit hydrogen atoms instead).
    CircularFragmenter(int radius, boolean preserveStereo, boolean markAttachments)
    Creates a new CircularFragmenter with the given radius, stereochemistry, and attachment point marking setting.

  • Method Summary

    Modifier and Type
    Method
    Description
    IAtomContainer
    getCircularFragment(IAtom atom)
    Extracts a single circular fragment centered on the given atom from the molecule the atom is a part of.
    IAtomContainer
    getCircularFragment(IAtomContainer molecule, IAtom atom)
    Extracts a single circular fragment centered on the given atom from the given molecule.
    List<IAtomContainer>
    getCircularFragments(IAtomContainer molecule)
    Extracts one circular fragment per atom of the input molecule.
    int
    getRadius()
    Returns the current radius setting for atom environment extraction.
    boolean
    isMarkAttachments()
    Returns the current attachment point marking setting.
    boolean
    isPreserveStereo()
    Returns the current stereochemistry setting.
    void
    setMarkAttachments(boolean markAttachments)
    Sets the attachment point marking setting.
    void
    setPreserveStereo(boolean preserveStereo)
    Sets the stereochemistry setting.
    void
    setRadius(int radius)
    Sets the radius for atom environment extraction.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • FRAGMENT_ATOM_DEPTH_PROPERTY_KEY

      public static final String FRAGMENT_ATOM_DEPTH_PROPERTY_KEY
      Property key to retrieve the depth (sphere nr. / level / height) of a fragment atom in the respective circular fragment. 0 stands for the center atom.
      See Also:

  • Constructor Details

    • CircularFragmenter

      public CircularFragmenter()
      Creates a new CircularFragmenter with the default radius (= 3 bonds), the default stereochemistry setting (= false, no preservation of stereochemistry), and the default attachment point marking setting (= false, no marking of attachment points; saturation with implicit hydrogen atoms instead).

    • CircularFragmenter

      public CircularFragmenter(int radius)
      Creates a new CircularFragmenter with the given radius, the default stereochemistry setting (= false, no preservation of stereochemistry), and the default attachment point marking setting (= false, no marking of attachment points; saturation with implicit hydrogen atoms instead).
      Parameters:
      radius - the number of bonds to expand from each center atom; must be >= 0; a radius of 0 produces fragments containing only the respective center atom itself
      Throws:
      IllegalArgumentException - if radius is negative

    • CircularFragmenter

      public CircularFragmenter(int radius, boolean preserveStereo)
      Creates a new CircularFragmenter with the given radius and stereochemistry setting and the default attachment point marking setting (= false, no marking of attachment points; saturation with implicit hydrogen atoms instead).
      Parameters:
      radius - the number of bonds to expand from each center atom; must be >= 0; a radius of 0 produces fragments containing only the respective center atom itself
      preserveStereo - whether to preserve stereochemistry annotations during fragmentation
      Throws:
      IllegalArgumentException - if radius is negative

    • CircularFragmenter

      public CircularFragmenter(int radius, boolean preserveStereo, boolean markAttachments)
      Creates a new CircularFragmenter with the given radius, stereochemistry, and attachment point marking setting.
      Parameters:
      radius - the number of bonds to expand from each center atom; must be >= 0; a radius of 0 produces fragments containing only the respective center atom itself
      preserveStereo - whether to preserve stereochemistry annotations during fragmentation
      markAttachments - whether to mark attachment points of broken bonds with pseudo atoms
      Throws:
      IllegalArgumentException - if radius is negative

  • Method Details

    • getRadius

      public int getRadius()
      Returns the current radius setting for atom environment extraction.
      Returns:
      radius in nr. of bonds

    • setRadius

      public void setRadius(int radius)
      Sets the radius for atom environment extraction.
      Parameters:
      radius - in nr. of bonds; must be >= 0
      Throws:
      IllegalArgumentException - if radius is negative

    • isPreserveStereo

      public boolean isPreserveStereo()
      Returns the current stereochemistry setting.
      Returns:
      whether to preserve stereochemistry annotations during fragmentation

    • setPreserveStereo

      public void setPreserveStereo(boolean preserveStereo)
      Sets the stereochemistry setting.
      Parameters:
      preserveStereo - whether to preserve stereochemistry annotations during fragmentation

    • isMarkAttachments

      public boolean isMarkAttachments()
      Returns the current attachment point marking setting.
      Returns:
      whether to mark attachment points of broken bonds with pseudo atoms

    • setMarkAttachments

      public void setMarkAttachments(boolean markAttachments)
      Sets the attachment point marking setting.
      Parameters:
      markAttachments - whether to mark attachment points of broken bonds with pseudo atoms

    • getCircularFragments

      public List<IAtomContainer> getCircularFragments(IAtomContainer molecule)
      Extracts one circular fragment per atom of the input molecule.

      The fragment for atom i contains deep copies of all atoms reachable from atom i within at most getRadius() bonds, together with all bonds between those atoms.

      The list index of each fragment corresponds to the index of the center atom in the input atom container.

      Note that the resulting fragments are not deduplicated!

      Parameters:
      molecule - the input molecule; must not be null; an empty input molecule yields an empty return list; the method does not modify the molecule
      Returns:
      a list of IAtomContainer objects, one per atom in molecule, in atom-index order; never null but can be empty if the input molecule is empty
      Throws:
      NullPointerException - if molecule is null

    • getCircularFragment

      public IAtomContainer getCircularFragment(IAtom atom)
      Extracts a single circular fragment centered on the given atom from the molecule the atom is a part of.

      The same algorithm as in getCircularFragments(IAtomContainer) is applied, but for only one center atom.

      This method will only work if the atom has been accessed in the context of an IAtomContainer, for example:

      IAtomContainer mol  = new AtomContainer();
IAtom          atom = new Atom(6);

atom.getContainer(); // null
mol.add(atom);
atom.getContainer(); // still null
mol.getAtom(0).getContainer(); // not-null, returns 'mol'
      Parameters:
      atom - the center atom; must not be null and must be accessed in the context of an IAtomContainer
      Returns:
      a deep-copied IAtomContainer of the circular environment
      Throws:
      NullPointerException - if atom is null
      IllegalArgumentException - if atom is not accessed in the context of an IAtomContainer

    • getCircularFragment

      public IAtomContainer getCircularFragment(IAtomContainer molecule, IAtom atom)
      Extracts a single circular fragment centered on the given atom from the given molecule.

      The same algorithm as in getCircularFragments(IAtomContainer) is applied, but for only one center atom.

      Parameters:
      molecule - the source molecule; must not be null
      atom - the center atom; must not be null and must be part of molecule
      Returns:
      a deep-copied IAtomContainer of the circular environment
      Throws:
      NullPointerException - if molecule or atom is null
      IllegalArgumentException - if atom is not part of molecule