Class TorsionDB


  • public class TorsionDB
    extends java.lang.Object
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static double calculateTorsionExtended​(Conformer conformer, int[] atom)
      Calculates a signed torsion like calculateTorsion().
      static double calculateTorsionExtended​(StereoMolecule mol, int[] atom)
      Calculates a signed torsion like calculateTorsion().
      static int[] findRearAtoms​(StereoMolecule mol, int[] torsionAtom)
      If the atom sequence contains a straight chain of sp-hybridized atoms, then the atom array contain the first two and last two atoms of a sequence of 2n+4 atoms (n: number of conjugated triple bonds).
      static int findRotatableBonds​(StereoMolecule mol, boolean skipAllRingBonds, boolean[] isRotatableBond)
      Locates all relevant rotatable bonds, i.e.
      static int[] getExtendedAtomSequence​(StereoMolecule mol, int[] atom)
      If the atom sequence contains a straight chain of sp-hybridized atoms, then the atom array contain the first two and last two atoms of a sequence of 2n+4 atoms (n: number of conjugated triple bonds).
      static int getNormalizedTorsionIndex​(java.lang.String torsionID, double angle)
      Normalizes a torsion angle considering the fragments symmetry type by returning the lowest symmetrically equivalent torsion that is >= 0.
      static int getSymmetryType​(java.lang.String torsionID)
      A fragment's symmetry type defines whether one part of a full 360 degree matches symmetrically another range.
      static byte[] getTorsionBinCounts​(java.lang.String torsionID)
      Returns the full circle histogram of torsion angles.
      static short[] getTorsionFrequencies​(java.lang.String torsionID)
      Returns an array of frequencies in rounded percent.
      static java.lang.String getTorsionID​(StereoMolecule mol, int bond, int[] torsionAtom, TorsionDetail detail)
      Determines uniquely an identifying name for the rotatable bond and its vicinity.
      static short[][] getTorsionRanges​(java.lang.String torsionID)
      Returns an array containing left and right limits of the torsion curves, of which the maxima are returned by getTorsions().
      static short[] getTorsions​(java.lang.String torsionID)
      Returns an array of maxima of the smoothened torsion histogram as short values in the range: 0 <= v < 360.
      static int getTorsionStrainClass​(java.lang.String torsionID, double angle)
      Checks, whether the torsion angle lies within statistical limits.
      static void initialize​(int mode)
      Initializes the in memory torsion database by reading torsion list, associated torsion frequencies, torsion peak widths (ranges), and/or normalized 3-degree bins into memory.
      static void initialize​(int mode, int mergeSpan)
      Initializes the in memory torsion database by reading torsion list, associated torsion frequencies, torsion peak widths (ranges), and/or normalized 3-degree bins into memory.
      static boolean isInverted​(java.lang.String torsionID)  
      static java.lang.String normalizeID​(java.lang.String torsionID)  
      protected static java.io.BufferedReader openReader​(java.lang.String resourceName)  
      static void setResourcePath​(java.lang.String path)
      Use this method before initializing the TorsionDB, if you want to open the resource files from an external location in the file system rather than from the project resources.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • setResourcePath

        public static void setResourcePath​(java.lang.String path)
        Use this method before initializing the TorsionDB, if you want to open the resource files from an external location in the file system rather than from the project resources.
        Parameters:
        path - absolute path of resource file directory ending with a file separator
      • initialize

        public static void initialize​(int mode)
        Initializes the in memory torsion database by reading torsion list, associated torsion frequencies, torsion peak widths (ranges), and/or normalized 3-degree bins into memory.
        Parameters:
        mode - combination of MODE_ flags
      • initialize

        public static void initialize​(int mode,
                                      int mergeSpan)
        Initializes the in memory torsion database by reading torsion list, associated torsion frequencies, torsion peak widths (ranges), and/or normalized 3-degree bins into memory. If mergeSpan is given, then torsions closer than mergeSpan are merged using their frequencies as weights. Frequencies and ranges are adapted to new merged and reduced torsion lists.
        Parameters:
        mode - combination of MODE_ flags
        mergeSpan - 0 or merge span in degrees
      • findRotatableBonds

        public static int findRotatableBonds​(StereoMolecule mol,
                                             boolean skipAllRingBonds,
                                             boolean[] isRotatableBond)
        Locates all relevant rotatable bonds, i.e. single bonds, which are not in a ring with less than 6 members, where both atoms are sp2 or sp3 and carry at least one more non-hydrogen neighbor, which are not redundant, and those where a torsion change modifies the relative location of atoms. For chains of conjugated triple bonds the following applies: If at least one terminal sp2/sp3 atom has no external neighbor, then no single bond is considered rotatable. Otherwise that terminal single bond connecting the smaller substituent is considered the only rotatable bond of the linear atom strand. Bonds considered rotatable by this method are guaranteed to produce a valid torsionID with getTorsionID().
        Parameters:
        mol -
        skipAllRingBonds - if true, then considers bonds in small and large(!) rings as non-rotatable
        isRotatableBond - null or empty(!) array that will be filled by this method
        Returns:
        number of rotatable bonds
      • openReader

        protected static java.io.BufferedReader openReader​(java.lang.String resourceName)
                                                    throws java.io.IOException
        Throws:
        java.io.IOException
      • getTorsions

        public static short[] getTorsions​(java.lang.String torsionID)
        Returns an array of maxima of the smoothened torsion histogram as short values in the range: 0 <= v < 360. Every v[i] represents a bin from v-0.5 to v+0.5.
        Parameters:
        torsionID -
        Returns:
        null, if torsion type was not found
      • getTorsionRanges

        public static short[][] getTorsionRanges​(java.lang.String torsionID)
        Returns an array containing left and right limits of the torsion curves, of which the maxima are returned by getTorsions(). First index matches the torsion angle array returned by getTorsions(). The second index being 0 or 1 gives lower or higher curve limit, respectively. These limits are either those angles where the curve has been fallen below 50% of the maximum frequency or where the curve has a minimum value and touches the next peak.
        Parameters:
        torsionID -
        Returns:
        null, if torsion type was not found
      • getTorsionFrequencies

        public static short[] getTorsionFrequencies​(java.lang.String torsionID)
        Returns an array of frequencies in rounded percent. Indices match the torsion angle array returned by getTorsions().
        Parameters:
        torsionID -
        Returns:
        null, if torsion type was not found
      • getTorsionBinCounts

        public static byte[] getTorsionBinCounts​(java.lang.String torsionID)
        Returns the full circle histogram of torsion angles. Bin size is 5 degrees. Bins are centered around values 0,5,10,...,355 degrees. Counts are normalized to 127 as maximum value.
        Parameters:
        torsionID -
        Returns:
        null if torsionID not in collection.
      • getTorsionID

        public static java.lang.String getTorsionID​(StereoMolecule mol,
                                                    int bond,
                                                    int[] torsionAtom,
                                                    TorsionDetail detail)
        Determines uniquely an identifying name for the rotatable bond and its vicinity. Based on this name various statistic parameters can be retrieved from this class. If the bond is not a single bond, is aromatic, is a member of a <=5-membered ring, if one of its atoms has 0,3 or more neighbours other than the other bond atom, or if one of its atoms is a stereo center with unknown parity, then this method returns null. Otherwise a fragment being unique for the this particular torsion situation is determined. If one of the bond's atoms is a stereo center, the fragment may be inverted for normalization, which would be represented with a trailing '<'. A trailing '>' indicates a non-inverted stereo center. If a TorsionDetail is given, then this will be filled with all classification information. If an torsionAtom array is given instead, then this is filled with the four torsion defining atoms. Terminal torsion atoms in torsionAtom (indexes 0,3) may be -1, which indicates a virtual atom assumed to lie on the third terminal sp3 position, when we have two real terminal atoms with equal symmetry ranks. If bond is part of a consecutive sp-sp atom chain, then the classifying fragment covers all linear atoms plus two end atoms not being member of the linear sp-atom strand. In this case torsionAtom (indexes 1,2) contains the two end-atoms of the linear atom strand, which are sp2- or sp3-hybridized.
        Parameters:
        mol - source molecule
        bond - of which to determine torsion statistics
        torsionAtom - null or int[4] to receive torsion atoms
        detail - null or empty TorsionDetail to receive torsion fragment, atom map, etc.
        Returns:
        null or idcode identifying the bond and its vicinity
      • getSymmetryType

        public static int getSymmetryType​(java.lang.String torsionID)
        A fragment's symmetry type defines whether one part of a full 360 degree matches symmetrically another range. SYMMETRY_D1D1 (0 -> 180 match 0 -> -180): Two times D1 symmetry, i.e. one terminal neighbor or two symmetrical sp3 neighbors. SYMMETRY_C1D2 (0 -> 180 match -180 -> 0): One stereo center on one side and two symmetrical sp2 neighbors on the other. SYMMETRY_D1D2_OR_D2D2 (0 -> 90 match 180 -> 90, 0 -> -90, -180 -> -90): Two symmetrical sp2 neighbors on one side and at least D1 (mirror plane) on the other. SYMMETRY_C1C1_OR_C1D1 (no symmetry): one stereo center on one side and not more than D1 (mirror plane) on the other. This is a quick lookup, because this information is encoded in the torsionID itself.
        Parameters:
        torsionID -
        Returns:
      • isInverted

        public static boolean isInverted​(java.lang.String torsionID)
      • normalizeID

        public static java.lang.String normalizeID​(java.lang.String torsionID)
      • calculateTorsionExtended

        public static double calculateTorsionExtended​(StereoMolecule mol,
                                                      int[] atom)
        Calculates a signed torsion like calculateTorsion(). However, terminal atoms of the defined atom sequence may be set to -1, referring to a hydrogen or electron pair in the 3rd terminal sp2 position, when the other two positions are occupied by two atoms that share the same symmetry rank.
        Parameters:
        mol -
        atom - valid 4-atom sequence with terminal atoms optionally set to -1
        Returns:
        torsion in the range: -pi <= torsion <= pi
      • calculateTorsionExtended

        public static double calculateTorsionExtended​(Conformer conformer,
                                                      int[] atom)
        Calculates a signed torsion like calculateTorsion(). However, terminal atoms of the defined atom sequence may be set to -1, referring to a hydrogen or electron pair in the 3rd terminal sp2 position, when the other two positions are occupied by two atoms that share the same symmetry rank.
        Parameters:
        conformer -
        atom - valid 4-atom sequence with terminal atoms optionally set to -1
        Returns:
        torsion in the range: -pi <= torsion <= pi (NaN, e.g. if 3 atoms on straight line)
      • findRearAtoms

        public static int[] findRearAtoms​(StereoMolecule mol,
                                          int[] torsionAtom)
        If the atom sequence contains a straight chain of sp-hybridized atoms, then the atom array contain the first two and last two atoms of a sequence of 2n+4 atoms (n: number of conjugated triple bonds). This method finds the 3rd and 3rd-last atoms of the chain. rearAtom[0] is connected to atom[1] and rearAtom[1] is connected to atom[2].
        Parameters:
        mol -
        torsionAtom -
        Returns:
      • getExtendedAtomSequence

        public static int[] getExtendedAtomSequence​(StereoMolecule mol,
                                                    int[] atom)
        If the atom sequence contains a straight chain of sp-hybridized atoms, then the atom array contain the first two and last two atoms of a sequence of 2n+4 atoms (n: number of conjugated triple bonds). This method finds extends the chain by inserting all sp-hybridised atoms into the strand.
        Parameters:
        mol -
        atom - torsion defining (1st two and last two) atoms of atom sequence
        Returns:
        2n+4 atom indexes (n: number of conjugated triple bonds)
      • getTorsionStrainClass

        public static int getTorsionStrainClass​(java.lang.String torsionID,
                                                double angle)
        Checks, whether the torsion angle lies within statistical limits. The torsion angle used should be obtained from a call to calculateTorsionExtended() in order to be canonical concerning to the chosen terminal (pseudo)atoms. Requires TorsionDB to be initialized with MODE_RANGES.
        Parameters:
        torsionID - as obtained by getTorsionID()
        angle - obtained from a call to calculateTorsionExtended()
        Returns:
        TORSION_GREEN,TORSION_YELLOW,TORSION_RED or TORSION_NOT_FOUND
      • getNormalizedTorsionIndex

        public static int getNormalizedTorsionIndex​(java.lang.String torsionID,
                                                    double angle)
        Normalizes a torsion angle considering the fragments symmetry type by returning the lowest symmetrically equivalent torsion that is >= 0.
        Parameters:
        torsionID -
        angle -
        Returns:
        angle within native range of symmetry type