Class AtomContainerManipulator

java.lang.Object
org.openscience.cdk.tools.manipulator.AtomContainerManipulator
Direct Known Subclasses:
ExtAtomContainerManipulator, SMSDNormalizer

public class AtomContainerManipulator extends Object
Class with convenience methods that provide methods to manipulate AtomContainer's. For example:
 AtomContainerManipulator.replaceAtomByAtom(container, atom1, atom2);
 
will replace the Atom in the AtomContainer, but in all the ElectronContainer's it participates too.
Author:
Egon Willighagen
Source code:
main
Belongs to CDK module:
standard
Created on:
2003-08-07
  • Field Details

  • Constructor Details

    • AtomContainerManipulator

      public AtomContainerManipulator()
  • Method Details

    • extractSubstructure

      @Deprecated public static IAtomContainer extractSubstructure(IAtomContainer atomContainer, int... atomIndices) throws CloneNotSupportedException
      Extract a substructure from an atom container, in the form of a new cloned atom container with only the atoms with indices in atomIndices and bonds that connect these atoms. Note that this may result in a disconnected atom container.
      Parameters:
      atomContainer - the source container to extract from
      atomIndices - the indices of the substructure
      Returns:
      a cloned atom container with a substructure of the source
      Throws:
      CloneNotSupportedException - not thrown any longer, kept to retain compatability
    • copy

      public static void copy(IAtomContainer dest, IAtomContainer source, Predicate<IAtom> atomFilter, Predicate<IBond> bondFilter)
      Copy selected atoms/bonds from a 'source' molecule to the provided destination. For consistency the bond filter is only checked if both atoms of a bond pass the atom filter. i.e. you can't add a bond with atoms that would not be copied.
      Parameters:
      dest - the destination molecule
      source - the source molecule
      atomFilter - the atom filter indicates which atoms to copy
      bondFilter - the bond filter indicates which bonds to copy
    • copy

      public static void copy(IAtomContainer dest, IAtomContainer source, Predicate<IAtom> atomFilter)
      Copy selected atoms from a 'source' molecule to the provided destination.
      Parameters:
      dest - the destination molecule
      source - the source molecule
      atomFilter - the atom filter indicates which atoms to copy
      See Also:
    • copy

      public static void copy(IAtomContainer dest, IAtomContainer source, Collection<IAtom> atoms)
      Copy atoms in the collection from a 'source' molecule to the provided destination. For performance a Set of 'atoms' is preferred.
      Parameters:
      dest - the destination molecule
      source - the source molecule
      atoms - the atom collection indicates which atoms to copy
      See Also:
    • extractSubstructure

      public static IAtomContainer extractSubstructure(IAtomContainer source, Collection<IAtom> atoms)
      Extract a substructure from a 'source' molecule to the provided destination based on the collection of atoms. For performance a Set of atoms is preferred.
      Parameters:
      source - the source molecule
      atoms - the atom collection indicates which atoms to copy
      Returns:
      the extracted molecule
      See Also:
    • getAtomById

      public static IAtom getAtomById(IAtomContainer ac, String id) throws CDKException
      Returns an atom in an atomcontainer identified by id
      Parameters:
      ac - The AtomContainer to search in
      id - The id to search for
      Returns:
      An atom having id id
      Throws:
      CDKException - There is no such atom
    • replaceAtomByAtom

      public static boolean replaceAtomByAtom(IAtomContainer container, IAtom oldAtom, IAtom newAtom)
      Substitute one atom in a container for another adjusting bonds, single electrons, lone pairs, and stereochemistry as required.
      Parameters:
      container - the container to replace the atom of
      oldAtom - the atom to replace
      newAtom - the atom to insert
      Returns:
      whether replacement was made
    • getTotalCharge

      public static double getTotalCharge(IAtomContainer atomContainer)
      Get the summed charge of all atoms in an AtomContainer
      Parameters:
      atomContainer - The IAtomContainer to manipulate
      Returns:
      The summed charges of all atoms in this AtomContainer.
    • getMass

      public static double getMass(IAtomContainer mol, int flav)
      Calculate the mass of a molecule, this function takes an optional 'mass flavour' that switches the computation type. The key distinction is how specified/unspecified isotopes are handled. A specified isotope is an atom that has either IIsotope.setMassNumber(Integer) or IIsotope.setExactMass(Double) set to non-null and non-zero.
      The flavours are:
      • MolWeight (default) - uses the exact mass of each atom when an isotope is specified, if not specified the average mass of the element is used.
      • MolWeightIgnoreSpecified - uses the average mass of each element, ignoring any isotopic/exact mass specification
      • MonoIsotopic - uses the exact mass of each atom when an isotope is specified, if not specified the major isotope mass for that element is used.
      • MostAbundant - uses the exact mass of each atom when specified, if not specified a distribution is calculated and the most abundant isotope pattern is used.
      Parameters:
      mol - molecule to compute mass for
      flav - flavor
      Returns:
      the mass of the molecule
      See Also:
    • getMass

      public static double getMass(IAtomContainer mol)
      Calculate the mass of a molecule, this function takes an optional 'mass flavour' that switches the computation type. The key distinction is how specified/unspecified isotopes are handled. A specified isotope is an atom that has either IIsotope.setMassNumber(Integer) or IIsotope.setExactMass(Double) set to non-null and non-zero.
      The flavours are:
      • MolWeight (default) - uses the exact mass of each atom when an isotope is specified, if not specified the average mass of the element is used.
      • MolWeightIgnoreSpecified - uses the average mass of each element, ignoring any isotopic/exact mass specification
      • MonoIsotopic - uses the exact mass of each atom when an isotope is specified, if not specified the major isotope mass for that element is used.
      • MostAbundant - uses the exact mass of each atom when specified, if not specified a distribution is calculated and the most abundant isotope pattern is used.
      Parameters:
      mol - molecule to compute mass for
      Returns:
      the mass of the molecule
      See Also:
    • getTotalExactMass

      public static double getTotalExactMass(IAtomContainer mol)
    • getNaturalExactMass

      public static double getNaturalExactMass(IAtomContainer mol)
      Deprecated.
    • getMolecularWeight

      public static double getMolecularWeight(IAtomContainer mol)
    • getTotalNaturalAbundance

      public static double getTotalNaturalAbundance(IAtomContainer atomContainer)
      Get the summed natural abundance of all atoms in an AtomContainer
      Parameters:
      atomContainer - The IAtomContainer to manipulate
      Returns:
      The summed natural abundance of all atoms in this AtomContainer.
    • getTotalFormalCharge

      public static int getTotalFormalCharge(IAtomContainer atomContainer)
      Get the total formal charge on a molecule.
      Parameters:
      atomContainer - the atom container to consider
      Returns:
      The summed formal charges of all atoms in this AtomContainer.
    • getTotalNegativeFormalCharge

      public static int getTotalNegativeFormalCharge(IAtomContainer atomContainer)
      Get the total formal negative charge on a molecule.
      Parameters:
      atomContainer - the atom container to consider
      Returns:
      The summed negative formal charges of all atoms in this AtomContainer.
    • getTotalPositiveFormalCharge

      public static int getTotalPositiveFormalCharge(IAtomContainer atomContainer)
      Get the total positive formal charge on a molecule.
      Parameters:
      atomContainer - the atom container to consider
      Returns:
      The summed positive formal charges of all atoms in this AtomContainer.
    • getTotalHydrogenCount

      public static int getTotalHydrogenCount(IAtomContainer container)
      Counts the number of hydrogens on the provided IAtomContainer. As this method will sum all implicit hydrogens on each atom it is important to ensure the atoms have already been perceived (and thus have an implicit hydrogen count) (see. percieveAtomTypesAndConfigureAtoms(org.openscience.cdk.interfaces.IAtomContainer)).
      Parameters:
      container - the container to count the hydrogens on
      Returns:
      the total number of hydrogens
      Throws:
      IllegalArgumentException - if the provided container was null
      See Also:
    • getImplicitHydrogenCount

      public static int getImplicitHydrogenCount(IAtomContainer container)
      Counts the number of implicit hydrogens on the provided IAtomContainer. As this method will sum all implicit hydrogens on each atom it is important to ensure the atoms have already been perceived (and thus have an implicit hydrogen count) (see. percieveAtomTypesAndConfigureAtoms(org.openscience.cdk.interfaces.IAtomContainer)).
      Parameters:
      container - the container to count the implicit hydrogens on
      Returns:
      the total number of implicit hydrogens
      Throws:
      IllegalArgumentException - if the provided container was null
      See Also:
    • countExplicitHydrogens

      public static int countExplicitHydrogens(IAtomContainer atomContainer, IAtom atom)
      Count explicit hydrogens.
      Parameters:
      atomContainer - the atom container to consider
      Returns:
      The number of explicit hydrogens on the given IAtom.
      Throws:
      IllegalArgumentException - if either the container or atom were null
    • convertImplicitToExplicitHydrogens

      public static void convertImplicitToExplicitHydrogens(IAtomContainer atomContainer)
      Adds explicit hydrogens (without coordinates) to the IAtomContainer, equaling the number of set implicit hydrogens.
      Parameters:
      atomContainer - the atom container to consider
      Keywords:
      hydrogens, adding
    • countHydrogens

      public static int countHydrogens(IAtomContainer atomContainer, IAtom atom)
      Returns:
      The summed implicit + explicit hydrogens of the given IAtom.
    • getAllIDs

      public static List<String> getAllIDs(IAtomContainer mol)
    • removeNonChiralHydrogens

      public static IAtomContainer removeNonChiralHydrogens(IAtomContainer org)
      Produces an AtomContainer without explicit non stereo-relevant Hs but with H count from one with Hs. The new molecule is a deep copy.
      Parameters:
      org - The AtomContainer from which to remove the hydrogens
      Returns:
      The molecule without non stereo-relevant Hs.
      Keywords:
      hydrogens, removal
    • copyAndSuppressedHydrogens

      public static IAtomContainer copyAndSuppressedHydrogens(IAtomContainer org)
      Copy the input container and suppress any explicit hydrogens. Only hydrogens that can be represented as a hydrogen count value on the atom are suppressed. If a copy is not needed please use suppressHydrogens(org.openscience.cdk.interfaces.IAtomContainer).
      Parameters:
      org - the container from which to remove hydrogens
      Returns:
      a copy of the input with suppressed hydrogens
      See Also:
    • suppressHydrogens

      public static IAtomContainer suppressHydrogens(IAtomContainer org)
      Suppress any explicit hydrogens in the provided container. Only hydrogens that can be represented as a hydrogen count value on the atom are suppressed. The container is updated and no elements are copied, please use either copyAndSuppressedHydrogens(org.openscience.cdk.interfaces.IAtomContainer) if you would to preserve the old instance.
      Parameters:
      org - the container from which to remove hydrogens
      Returns:
      the input for convenience
      See Also:
    • removeHydrogens

      public static IAtomContainer removeHydrogens(IAtomContainer org)
      Create an copy of the org structure with explicit hydrogens removed. Stereochemistry is updated but up and down bonds in a depiction may need to be recalculated (see. StructureDiagramGenerator).
      Parameters:
      org - The AtomContainer from which to remove the hydrogens
      Returns:
      The molecule without hydrogens.
      See Also:
      Keywords:
      hydrogens, removal, suppress
    • removeHydrogensPreserveMultiplyBonded

      @Deprecated public static IAtomContainer removeHydrogensPreserveMultiplyBonded(IAtomContainer ac)
      Deprecated.
      suppressHydrogens(org.openscience.cdk.interfaces.IAtomContainer) will now not removed bridging hydrogens by default
      Produces an AtomContainer without explicit Hs but with H count from one with Hs. Hs bonded to more than one heavy atom are preserved. The new molecule is a deep copy.
      Returns:
      The mol without Hs.
      Keywords:
      hydrogens, removal
    • setAtomProperties

      public static void setAtomProperties(IAtomContainer container, Object propKey, Object propVal)
      Sets a property on all Atoms in the given container.
    • unregisterElectronContainerListeners

      public static void unregisterElectronContainerListeners(IAtomContainer container)
      A method to remove ElectronContainerListeners. ElectronContainerListeners are used to detect changes in ElectronContainers (like bonds) and to notifiy registered Listeners in the event of a change. If an object looses interest in such changes, it should unregister with this AtomContainer in order to improve performance of this class.
    • unregisterAtomListeners

      public static void unregisterAtomListeners(IAtomContainer container)
      A method to remove AtomListeners. AtomListeners are used to detect changes in Atom objects within this AtomContainer and to notifiy registered Listeners in the event of a change. If an object looses interest in such changes, it should unregister with this AtomContainer in order to improve performance of this class.
    • getIntersection

      public static IAtomContainer getIntersection(IAtomContainer container1, IAtomContainer container2)
      Compares this AtomContainer with another given AtomContainer and returns the Intersection between them.

      Important Note : This is not the maximum common substructure.

      Parameters:
      container1 - an AtomContainer object
      container2 - an AtomContainer object
      Returns:
      An AtomContainer containing the intersection between container1 and container2
    • getAtomArray

      public static IAtom[] getAtomArray(IAtomContainer container)
      Constructs an array of Atom objects from an AtomContainer.
      Parameters:
      container - The original AtomContainer.
      Returns:
      The array of Atom objects.
    • getAtomArray

      public static IAtom[] getAtomArray(List<IAtom> list)
      Constructs an array of Atom objects from a List of Atom objects.
      Parameters:
      list - The original List.
      Returns:
      The array of Atom objects.
    • getBondArray

      public static IBond[] getBondArray(IAtomContainer container)
      Constructs an array of Bond objects from an AtomContainer.
      Parameters:
      container - The original AtomContainer.
      Returns:
      The array of Bond objects.
    • getBondArray

      public static IBond[] getBondArray(List<IBond> list)
      Constructs an array of Atom objects from a List of Atom objects.
      Parameters:
      list - The original List.
      Returns:
      The array of Atom objects.
    • getElectronContainerArray

      public static IElectronContainer[] getElectronContainerArray(IAtomContainer container)
      Constructs an array of Bond objects from an AtomContainer.
      Parameters:
      container - The original AtomContainer.
      Returns:
      The array of Bond objects.
    • getElectronContainerArray

      public static IElectronContainer[] getElectronContainerArray(List<IElectronContainer> list)
      Constructs an array of Atom objects from a List of Atom objects.
      Parameters:
      list - The original List.
      Returns:
      The array of Atom objects.
    • percieveAtomTypesAndConfigureAtoms

      public static void percieveAtomTypesAndConfigureAtoms(IAtomContainer container) throws CDKException
      Convenience method to perceive atom types for all IAtoms in the IAtomContainer, using the CDKAtomTypeMatcher. If the matcher finds a matching atom type, the IAtom will be configured to have the same properties as the IAtomType. If no matching atom type is found, no configuration is performed.
      This method overwrites existing values.
      Parameters:
      container - the container whose atom types are to be perceived
      Throws:
      CDKException
      See Also:
    • percieveAtomTypesAndConfigureUnsetProperties

      public static void percieveAtomTypesAndConfigureUnsetProperties(IAtomContainer container) throws CDKException
      Convenience method to perceive atom types for all IAtoms in the IAtomContainer, using the CDKAtomTypeMatcher. If the matcher finds a matching atom type, the IAtom will be configured to have the same properties as the IAtomType. If no matching atom type is found, no configuration is performed.
      This method only sets null values.
      Parameters:
      container - the container whose atom types are to be perceived
      Throws:
      CDKException
      See Also:
    • clearAtomConfigurations

      public static void clearAtomConfigurations(IAtomContainer container)
      This method will reset all atom configuration to UNSET.
      This method is the reverse of percieveAtomTypesAndConfigureAtoms(org.openscience.cdk.interfaces.IAtomContainer) and after a call to this method all atoms will be "unconfigured".
      Note that it is not a complete reversal of percieveAtomTypesAndConfigureAtoms(org.openscience.cdk.interfaces.IAtomContainer) since the atomic symbol of the atoms remains unchanged. Also, all the flags that were set by the configuration method (such as IS_HYDROGENBOND_ACCEPTOR or ISAROMATIC) will be set to False.
      Parameters:
      container - The molecule whose atoms are to be unconfigured
      See Also:
    • getSingleBondEquivalentSum

      public static int getSingleBondEquivalentSum(IAtomContainer container)
      Returns the sum of bond orders, where a single bond counts as one single bond equivalent, a double as two, etc.
    • getMaximumBondOrder

      public static IBond.Order getMaximumBondOrder(IAtomContainer container)
    • getHeavyAtoms

      public static List<IAtom> getHeavyAtoms(IAtomContainer container)
      Returns a set of nodes excluding all the hydrogens.
      Returns:
      The heavyAtoms value
      Keywords:
      hydrogens, removal
    • createAllCarbonAllSingleNonAromaticBondAtomContainer

      public static IAtomContainer createAllCarbonAllSingleNonAromaticBondAtomContainer(IAtomContainer atomContainer) throws CloneNotSupportedException
      Deprecated.
      not all attributes are removed producing unexpected results, use anonymise(org.openscience.cdk.interfaces.IAtomContainer)
      Generates a cloned atomcontainer with all atoms being carbon, all bonds being single non-aromatic
      Parameters:
      atomContainer - The input atomcontainer
      Returns:
      The new atomcontainer
      Throws:
      CloneNotSupportedException - The atomcontainer cannot be cloned
    • anonymise

      public static IAtomContainer anonymise(IAtomContainer src)
      Anonymise the provided container to single-bonded carbon atoms. No information other then the connectivity from the original container is retrained.
      Parameters:
      src - an atom container
      Returns:
      anonymised container
    • skeleton

      public static IAtomContainer skeleton(IAtomContainer src)
      Create a skeleton copy of the provided structure. The skeleton copy is similar to an anonymous copy (anonymise(org.openscience.cdk.interfaces.IAtomContainer)) except that atom elements are preserved. All bonds are converted to single bonds and a 'clean' atom is created for the input elements. The 'clean' atom has unset charge, mass, and hydrogen count.
      Parameters:
      src - input structure
      Returns:
      the skeleton copy
    • getBondOrderSum

      public static double getBondOrderSum(IAtomContainer container, IAtom atom)
      Returns the sum of the bond order equivalents for a given IAtom. It considers single bonds as 1.0, double bonds as 2.0, triple bonds as 3.0, and quadruple bonds as 4.0.
      Parameters:
      atom - The atom for which to calculate the bond order sum
      Returns:
      The number of bond order equivalents for this atom
    • setSingleOrDoubleFlags

      public static IAtomContainer setSingleOrDoubleFlags(IAtomContainer ac)
      Assigns CDKConstants.SINGLE_OR_DOUBLE flags to the bonds of a container. The single or double flag indicates uncertainty of bond order and in this case is assigned to all aromatic bonds (and atoms) which occur in rings. If any such bonds are found the flag is also set on the container.
           SmilesParser parser = new SmilesParser(...);
           parser.setPreservingAromaticity(true);
      
           IAtomContainer biphenyl = parser.parseSmiles("c1cccc(c1)c1ccccc1");
      
           AtomContainerManipulator.setSingleOrDoubleFlags(biphenyl);
       
      Parameters:
      ac - container to which the flags are assigned
      Returns:
      the input for convenience