Class StructureTools


  • public class StructureTools
    extends java.lang.Object
    A class that provides some tool methods.
    Since:
    1.0
    Author:
    Andreas Prlic, Jules Jacobsen
    • Field Detail

      • CA_ATOM_NAME

        public static final java.lang.String CA_ATOM_NAME
        The atom name of the backbone C-alpha atom. Note that this can be ambiguous depending on the context since Calcium atoms use the same name in PDB.
        See Also:
        Constant Field Values
      • N_ATOM_NAME

        public static final java.lang.String N_ATOM_NAME
        The atom name for the backbone amide nitrogen
        See Also:
        Constant Field Values
      • C_ATOM_NAME

        public static final java.lang.String C_ATOM_NAME
        The atom name for the backbone carbonyl
        See Also:
        Constant Field Values
      • O_ATOM_NAME

        public static final java.lang.String O_ATOM_NAME
        The atom name for the backbone carbonyl oxygen
        See Also:
        Constant Field Values
      • CB_ATOM_NAME

        public static final java.lang.String CB_ATOM_NAME
        The atom name of the side-chain C-beta atom
        See Also:
        Constant Field Values
      • C1_ATOM_NAME

        public static final java.lang.String C1_ATOM_NAME
        The atom name of the backbone C1' in RNA
        See Also:
        Constant Field Values
      • C2_ATOM_NAME

        public static final java.lang.String C2_ATOM_NAME
        The atom name of the backbone C2' in RNA
        See Also:
        Constant Field Values
      • C3_ATOM_NAME

        public static final java.lang.String C3_ATOM_NAME
        The atom name of the backbone C3' in RNA
        See Also:
        Constant Field Values
      • C4_ATOM_NAME

        public static final java.lang.String C4_ATOM_NAME
        The atom name of the backbone C4' in RNA
        See Also:
        Constant Field Values
      • O2_ATOM_NAME

        public static final java.lang.String O2_ATOM_NAME
        The atom name of the backbone O2' in RNA
        See Also:
        Constant Field Values
      • O3_ATOM_NAME

        public static final java.lang.String O3_ATOM_NAME
        The atom name of the backbone O3' in RNA
        See Also:
        Constant Field Values
      • O4_ATOM_NAME

        public static final java.lang.String O4_ATOM_NAME
        The atom name of the backbone O4' in RNA
        See Also:
        Constant Field Values
      • O5_ATOM_NAME

        public static final java.lang.String O5_ATOM_NAME
        The atom name of the backbone O4' in RNA
        See Also:
        Constant Field Values
      • OP1_ATOM_NAME

        public static final java.lang.String OP1_ATOM_NAME
        The atom name of the backbone O4' in RNA
        See Also:
        Constant Field Values
      • OP2_ATOM_NAME

        public static final java.lang.String OP2_ATOM_NAME
        The atom name of the backbone O4' in RNA
        See Also:
        Constant Field Values
      • P_ATOM_NAME

        public static final java.lang.String P_ATOM_NAME
        The atom name of the backbone phosphate in RNA
        See Also:
        Constant Field Values
      • NUCLEOTIDE_REPRESENTATIVE

        public static final java.lang.String NUCLEOTIDE_REPRESENTATIVE
        The atom used as representative for nucleotides, equivalent to CA_ATOM_NAME for proteins
        See Also:
        Constant Field Values
      • UNKNOWN_GROUP_LABEL

        public static final char UNKNOWN_GROUP_LABEL
        The character to use for unknown compounds in sequence strings
        See Also:
        Constant Field Values
      • RATIO_RESIDUES_TO_TOTAL

        public static final double RATIO_RESIDUES_TO_TOTAL
        Below this ratio of aminoacid/nucleotide residues to the sequence total, we use simple majority of aminoacid/nucleotide residues to decide the character of the chain (protein/nucleotide)
        See Also:
        Constant Field Values
    • Constructor Detail

      • StructureTools

        public StructureTools()
    • Method Detail

      • getNrAtoms

        public static final int getNrAtoms​(Structure s)
        Count how many Atoms are contained within a Structure object.
        Parameters:
        s - the structure object
        Returns:
        the number of Atoms in this Structure
      • getNrGroups

        public static final int getNrGroups​(Structure s)
        Count how many groups are contained within a structure object.
        Parameters:
        s - the structure object
        Returns:
        the number of groups in the structure
      • getAtomArray

        public static final Atom[] getAtomArray​(Structure s,
                                                java.lang.String[] atomNames)
        Returns an array of the requested Atoms from the Structure object. Iterates over all groups and checks if the requested atoms are in this group, no matter if this is a AminoAcid or HetatomImpl group. If the group does not contain all requested atoms then no atoms are added for that group. For structures with more than one model, only model 0 will be used.
        Parameters:
        s - the structure to get the atoms from
        atomNames - contains the atom names to be used.
        Returns:
        an Atom[] array
      • getAtomArrayAllModels

        public static final Atom[] getAtomArrayAllModels​(Structure s,
                                                         java.lang.String[] atomNames)
        Returns an array of the requested Atoms from the Structure object. In contrast to getAtomArray(Structure, String[]) this method iterates over all chains. Iterates over all chains and groups and checks if the requested atoms are in this group, no matter if this is a AminoAcid or HetatomImpl group. If the group does not contain all requested atoms then no atoms are added for that group. For structures with more than one model, only model 0 will be used.
        Parameters:
        s - the structure to get the atoms from
        atomNames - contains the atom names to be used.
        Returns:
        an Atom[] array
      • getAllAtomArray

        public static final Atom[] getAllAtomArray​(Structure s)
        Convert all atoms of the structure (first model) into an Atom array
        Parameters:
        s - input structure
        Returns:
        all atom array
      • getAllAtomArray

        public static final Atom[] getAllAtomArray​(Chain c)
        Returns and array of all atoms of the chain (first model), including Hydrogens (if present) and all HETATOMs. Waters are not included.
        Parameters:
        c - input chain
        Returns:
        all atom array
      • getUnalignedGroups

        public static java.util.List<Group> getUnalignedGroups​(Atom[] ca)
        List of groups from the structure not included in ca (e.g. ligands). Unaligned groups are searched from all chains referenced in ca, as well as any chains in the first model of the structure from ca[0], if any.
        Parameters:
        ca - an array of atoms
        Returns:
      • getAllNonHAtomArray

        public static final Atom[] getAllNonHAtomArray​(Structure s,
                                                       boolean hetAtoms)
        Returns and array of all non-Hydrogen atoms in the given Structure, optionally including HET atoms or not. Waters are not included.
        Parameters:
        s -
        hetAtoms - if true HET atoms are included in array, if false they are not
        Returns:
      • getAllNonHAtomArray

        public static final Atom[] getAllNonHAtomArray​(Chain c,
                                                       boolean hetAtoms)
        Returns and array of all non-Hydrogen atoms in the given Chain, optionally including HET atoms or not Waters are not included.
        Parameters:
        c -
        hetAtoms - if true HET atoms are included in array, if false they are not
        Returns:
      • getAtomArray

        public static final Atom[] getAtomArray​(Chain c,
                                                java.lang.String[] atomNames)
        Returns an array of the requested Atoms from the Chain object. Iterates over all groups and checks if the requested atoms are in this group, no matter if this is a AminoAcid or Hetatom group. If the group does not contain all requested atoms then no atoms are added for that group.
        Parameters:
        c - the Chain to get the atoms from
        atomNames - contains the atom names to be used.
        Returns:
        an Atom[] array
      • getAtomCAArray

        public static final Atom[] getAtomCAArray​(Chain c)
        Returns an Atom array of the C-alpha atoms. Any atom that is a carbon and has CA name will be returned.
        Parameters:
        c - the structure object
        Returns:
        an Atom[] array
        See Also:
        getRepresentativeAtomArray(Chain)
      • getRepresentativeAtomArray

        public static final Atom[] getRepresentativeAtomArray​(Chain c)
        Gets a representative atom for each group that is part of the chain backbone. Note that modified aminoacids won't be returned as part of the backbone if the ReducedChemCompProvider was used to load the structure. For amino acids, the representative is a CA carbon. For nucleotides, the representative is the "P". Other group types will be ignored.
        Parameters:
        c -
        Returns:
        representative Atoms of the chain backbone
        Since:
        Biojava 4.1.0
      • cloneCAArray

        @Deprecated
        public static final Atom[] cloneCAArray​(Atom[] ca)
        Deprecated.
        Use the better-named cloneAtomArray(Atom[]) instead
        Provides an equivalent copy of Atoms in a new array. Clones everything, starting with parent groups and chains. The chain will only contain groups that are part of the input array.
        Parameters:
        ca - array of representative atoms, e.g. CA atoms
        Returns:
        Atom array
      • cloneAtomArray

        public static final Atom[] cloneAtomArray​(Atom[] ca)
        Provides an equivalent copy of Atoms in a new array. Clones everything, starting with parent groups and chains. The chain will only contain groups that are part of the input array.
        Parameters:
        ca - array of representative atoms, e.g. CA atoms
        Returns:
        Atom array
        Since:
        Biojava 4.1.0
      • cloneGroups

        public static Group[] cloneGroups​(Atom[] ca)
        Clone a set of representative Atoms, but returns the parent groups
        Parameters:
        ca - Atom array
        Returns:
        Group array
      • duplicateCA2

        public static Atom[] duplicateCA2​(Atom[] ca2)
        Utility method for working with circular permutations. Creates a duplicated and cloned set of Calpha atoms from the input array.
        Parameters:
        ca2 - atom array
        Returns:
        cloned and duplicated set of input array
      • getAtomCAArray

        public static Atom[] getAtomCAArray​(Structure s)
        Return an Atom array of the C-alpha atoms. Any atom that is a carbon and has CA name will be returned.
        Parameters:
        s - the structure object
        Returns:
        an Atom[] array
        See Also:
        getRepresentativeAtomArray(Structure)
      • getRepresentativeAtomArray

        public static Atom[] getRepresentativeAtomArray​(Structure s)
        Gets a representative atom for each group that is part of the chain backbone. Note that modified aminoacids won't be returned as part of the backbone if the ReducedChemCompProvider was used to load the structure. For amino acids, the representative is a CA carbon. For nucleotides, the representative is the "P". Other group types will be ignored.
        Parameters:
        s - Input structure
        Returns:
        representative Atoms of the structure backbone
        Since:
        Biojava 4.1.0
      • getBackboneAtomArray

        public static Atom[] getBackboneAtomArray​(Structure s)
        Return an Atom array of the main chain atoms: CA, C, N, O Any group that contains those atoms will be included, be it a standard aminoacid or not
        Parameters:
        s - the structure object
        Returns:
        an Atom[] array
      • get1LetterCodeAmino

        public static final java.lang.Character get1LetterCodeAmino​(java.lang.String groupCode3)
        Convert three character amino acid codes into single character e.g. convert CYS to C. Valid 3-letter codes will be those of the standard 20 amino acids plus MSE, CSE, SEC, PYH, PYL (see the aminoAcids map)
        Parameters:
        groupCode3 - a three character amino acid representation String
        Returns:
        the 1 letter code, or null if the given 3 letter code does not correspond to an amino acid code
      • convert_3code_1code

        @Deprecated
        public static final java.lang.Character convert_3code_1code​(java.lang.String code3)
        Deprecated.
        Parameters:
        code3 -
        Returns:
      • get1LetterCode

        public static final java.lang.Character get1LetterCode​(java.lang.String groupCode3)
        Convert a three letter amino acid or nucleotide code into a single character code. If the code does not correspond to an amino acid or nucleotide, returns UNKNOWN_GROUP_LABEL. Returned null for nucleotides prior to version 4.0.1.
        Parameters:
        groupCode3 - three letter representation
        Returns:
        The 1-letter abbreviation
      • isNucleotide

        public static final boolean isNucleotide​(java.lang.String groupCode3)
        Test if the three-letter code of an ATOM entry corresponds to a nucleotide or to an aminoacid.
        Parameters:
        groupCode3 - 3-character code for a group.
      • getReducedStructure

        @Deprecated
        public static final Structure getReducedStructure​(Structure s,
                                                          java.lang.String chainId)
                                                   throws StructureException
        Deprecated.
        Reduce a structure to provide a smaller representation . Only takes the first model of the structure. If chainId is provided only return a structure containing that Chain ID. Converts lower case chain IDs to upper case if structure does not contain a chain with that ID.
        Parameters:
        s -
        chainId -
        Returns:
        Structure
        Throws:
        StructureException
        Since:
        3.0
      • getReducedStructure

        @Deprecated
        public static final Structure getReducedStructure​(Structure s,
                                                          int chainNr)
                                                   throws StructureException
        Deprecated.
        Reduce a structure to provide a smaller representation. Only takes the first model of the structure. If chainNr >=0 only takes the chain at that position into account.
        Parameters:
        s -
        chainNr - can be -1 to request all chains of model 0, otherwise will only add chain at this position
        Returns:
        Structure object
        Throws:
        StructureException
        Since:
        3.0
Parameters:
s - The full structure
ranges - A comma-separated list of ranges, optionally surrounded by parentheses
Returns:
Substructure of s specified by ranges
Throws:
java.lang.IllegalArgumentException - for malformed range strings
StructureException - for errors when reducing the Structure
Parameters:
c -
Returns: