Package org.openscience.cdk.tools.manipulator

Class 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

    • Constructor Detail

      • AtomContainerManipulator

        public AtomContainerManipulator()

    • Method Detail

      • extractSubstructure

        @Deprecated
public static IAtomContainer extractSubstructure​(IAtomContainer atomContainer,
                                                 int... atomIndices)
                                          throws CloneNotSupportedException
        Deprecated.
        use extractSubstructure(IAtomContainer, Collection) instead
        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

      • 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(IAtomContainer, int), MolWeight, MolWeightIgnoreSpecified, MonoIsotopic, MostAbundant

      • 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:
        getMass(IAtomContainer, int), MolWeight, MolWeightIgnoreSpecified, MonoIsotopic, MostAbundant

      • 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.

      • 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.

      • 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

      • 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:
        copyAndSuppressedHydrogens(org.openscience.cdk.interfaces.IAtomContainer)
        Keywords:
        hydrogens, removal, suppress

      • 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:
        AtomTypeManipulator.configure(IAtom, IAtomType)

      • 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:
        AtomTypeManipulator.configureUnsetProperties(IAtom, IAtomType)

      • 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.

      • getHeavyAtoms

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

      • 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 IChemObject.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