Class AtomCache


  • public class AtomCache
    extends java.lang.Object
    A utility class that provides easy access to Structure objects. If you are running a script that is frequently re-using the same PDB structures, the AtomCache keeps an in-memory cache of the files for quicker access. The cache is a soft-cache, this means it won't cause out of memory exceptions, but garbage collects the data if the Java virtual machine needs to free up space. The AtomCache is thread-safe.
    Since:
    3.0
    Author:
    Andreas Prlic, Spencer Bliven, Peter Rose
    • Constructor Detail

      • AtomCache

        public AtomCache()
        Default AtomCache constructor. Usually stores files in a temp directory, but this can be overriden by setting the PDB_DIR variable at runtime.
        See Also:
        UserConfiguration()
      • AtomCache

        public AtomCache​(java.lang.String pdbFilePath)
        Creates an instance of an AtomCache that is pointed to the a particular path in the file system. It will use the same value for pdbFilePath and cachePath.
        Parameters:
        pdbFilePath - a directory in the file system to use as a location to cache files.
      • AtomCache

        public AtomCache​(java.lang.String pdbFilePath,
                         java.lang.String cachePath)
        Creates an instance of an AtomCache that is pointed to the a particular path in the file system.
        Parameters:
        pdbFilePath - a directory in the file system to use as a location to cache files.
        cachePath -
      • AtomCache

        @Deprecated
        public AtomCache​(java.lang.String pdbFilePath,
                         boolean isSplit)
        Deprecated.
        isSplit parameter is ignored (4.0.0)
        Parameters:
        isSplit - Ignored
      • AtomCache

        @Deprecated
        public AtomCache​(java.lang.String pdbFilePath,
                         java.lang.String cachePath,
                         boolean isSplit)
        Deprecated.
        isSplit parameter is ignored (4.0.0)
        Parameters:
        isSplit - Ignored
      • AtomCache

        public AtomCache​(UserConfiguration config)
        Creates a new AtomCache object based on the provided UserConfiguration.
        Parameters:
        config - the UserConfiguration to use for this cache.
    • Method Detail

      • getRepresentativeAtoms

        public Atom[] getRepresentativeAtoms​(java.lang.String name)
                                      throws java.io.IOException,
                                             StructureException
        Returns the representative atoms for the provided name. See getStructure(String) for supported naming conventions.
        Parameters:
        name -
        Returns:
        an array of Atoms.
        Throws:
        java.io.IOException
        StructureException
      • getBiologicalAssembly

        public Structure getBiologicalAssembly​(java.lang.String pdbId,
                                               int bioAssemblyId,
                                               boolean bioAssemblyFallback)
                                        throws StructureException,
                                               java.io.IOException
        Loads the biological assembly for a given PDB ID and bioAssemblyId. If a bioAssemblyId > 0 is specified, the corresponding biological assembly file will be loaded. Note, the number of available biological unit files varies. Many entries don't have a biological assembly specified (i.e. NMR structures), many entries have only one biological assembly (bioAssemblyId=1), and a few structures have multiple biological assemblies. Set bioAssemblyFallback to true, to download the original PDB file in cases that a biological assembly file is not available.
        Parameters:
        pdbId - the PDB ID
        bioAssemblyId - the 1-based index of the biological assembly (0 gets the asymmetric unit)
        bioAssemblyFallback - if true, try reading original PDB file in case the biological assembly file is not available
        Returns:
        a structure object
        Throws:
        java.io.IOException
        StructureException
        Since:
        3.2
      • getBiologicalAssembly

        public Structure getBiologicalAssembly​(java.lang.String pdbId)
                                        throws StructureException,
                                               java.io.IOException
        Loads the default biological unit (e.g. *.pdb1.gz). If it is not available, the asymmetric unit will be loaded, i.e. for NMR structures.

        Biological assemblies can also be accessed using getStructure("BIO:[pdbId]")

        Parameters:
        pdbId - the PDB ID
        Returns:
        a structure object
        Throws:
        java.io.IOException
        StructureException
        Since:
        4.2
      • getBiologicalUnit

        @Deprecated
        public Structure getBiologicalUnit​(java.lang.String pdbId)
                                    throws StructureException,
                                           java.io.IOException
        Deprecated.
        Loads the default biological unit (e.g. *.pdb1.gz). If it is not available, the asymmetric unit will be loaded, i.e. for NMR structures.
        Parameters:
        pdbId - the PDB ID
        Returns:
        a structure object
        Throws:
        java.io.IOException
        StructureException
        Since:
        3.2
      • getBiologicalAssembly

        public Structure getBiologicalAssembly​(java.lang.String pdbId,
                                               int bioAssemblyId)
                                        throws StructureException,
                                               java.io.IOException
        Loads the default biological unit (e.g. *.pdb1.gz). If it is not available, the asymmetric unit will be loaded, i.e. for NMR structures.
        Parameters:
        pdbId - the PDB ID
        bioAssemblyId - the 1-based index of the biological assembly (0 gets the asymmetric unit)
        Returns:
        a structure object
        Throws:
        java.io.IOException
        StructureException
        Since:
        4.2
      • getCachePath

        public java.lang.String getCachePath()
        Returns the path that contains the caching file for utility data, such as domain definitions.
        Returns:
      • getPath

        public java.lang.String getPath()
        Get the path that is used to cache PDB files.
        Returns:
        path to a directory
      • getStructure

        public Structure getStructure​(java.lang.String name)
                               throws java.io.IOException,
                                      StructureException
        Request a Structure based on a name.
                        Formal specification for how to specify the name:
        
                        name     := pdbID
                                       | pdbID '.' chainID
                                       | pdbID '.' range
                                       | scopID
                        range         := '('? range (',' range)? ')'?
                                       | chainID
                                       | chainID '_' resNum '-' resNum
                        pdbID         := [0-9][a-zA-Z0-9]{3}
                        chainID       := [a-zA-Z0-9]
                        scopID        := 'd' pdbID [a-z_][0-9_]
                        resNum        := [-+]?[0-9]+[A-Za-z]?
        
        
                        Example structures:
                        1TIM     #whole structure
                        4HHB.C     #single chain
                        4GCR.A_1-83     #one domain, by residue number
                        3AA0.A,B     #two chains treated as one structure
                        d2bq6a1     #scop domain
         
        With the additional set of rules:
        • If only a PDB code is provided, the whole structure will be return including ligands, but the first model only (for NMR).
        • Chain IDs are case sensitive, PDB ids are not. To specify a particular chain write as: 4hhb.A or 4HHB.A
        • To specify a SCOP domain write a scopId e.g. d2bq6a1. Some flexibility can be allowed in SCOP domain names, see setStrictSCOP(boolean)
        • URLs are accepted as well

        Note that this method should not be used in StructureIdentifier implementations to avoid circular calls.

        Parameters:
        name -
        Returns:
        a Structure object, or null if name appears improperly formated (eg too short, etc)
        Throws:
        java.io.IOException - The PDB file cannot be cached due to IO errors
        StructureException - The name appeared valid but did not correspond to a structure. Also thrown by some submethods upon errors, eg for poorly formatted subranges.
      • getStructureForDomain

        public Structure getStructureForDomain​(ScopDomain domain,
                                               ScopDatabase scopDatabase,
                                               boolean strictLigandHandling)
                                        throws java.io.IOException,
                                               StructureException
        Returns the representation of a ScopDomain as a BioJava Structure object.
        Parameters:
        domain - a SCOP domain
        scopDatabase - A ScopDatabase to use
        strictLigandHandling - If set to false, hetero-atoms are included if and only if they belong to a chain to which the SCOP domain belongs; if set to true, hetero-atoms are included if and only if they are strictly within the definition (residue numbers) of the SCOP domain
        Returns:
        a Structure object
        Throws:
        java.io.IOException
        StructureException
      • getStructureForDomain

        public Structure getStructureForDomain​(java.lang.String scopId)
                                        throws java.io.IOException,
                                               StructureException
        Returns the representation of a ScopDomain as a BioJava Structure object.
        Parameters:
        scopId - a SCOP Id
        Returns:
        a Structure object
        Throws:
        java.io.IOException
        StructureException
      • isAutoFetch

        @Deprecated
        public boolean isAutoFetch()
        Deprecated.
        Does the cache automatically download files that are missing from the local installation from the PDB FTP site?
        Returns:
        flag
      • isFetchCurrent

        @Deprecated
        public boolean isFetchCurrent()
        Deprecated.
        Use FileParsingParameters#getObsoleteBehavior() instead (4.0.0)
        N.B. This feature won't work unless the structure wasn't found & autoFetch is set to true.
        Returns:
        the fetchCurrent
      • isFetchFileEvenIfObsolete

        @Deprecated
        public boolean isFetchFileEvenIfObsolete()
        Deprecated.
        Use FileParsingParameters#getObsoleteBehavior() instead (4.0.0)
        forces the cache to fetch the file if its status is OBSOLETE. This feature has a higher priority than setFetchCurrent(boolean).
        N.B. This feature won't work unless the structure wasn't found & autoFetch is set to true.
        Returns:
        the fetchFileEvenIfObsolete
        Since:
        3.0.2
        See Also:
        #fetchCurrent
      • notifyShutdown

        public void notifyShutdown()
        Send a signal to the cache that the system is shutting down. Notifies underlying SerializableCache instances to flush themselves...
      • setAutoFetch

        @Deprecated
        public void setAutoFetch​(boolean autoFetch)
        Deprecated.
        Does the cache automatically download files that are missing from the local installation from the PDB FTP site?
        Parameters:
        autoFetch - flag
      • setCachePath

        public void setCachePath​(java.lang.String cachePath)
        set the location at which utility data should be cached.
        Parameters:
        cachePath -
      • setFetchCurrent

        @Deprecated
        public void setFetchCurrent​(boolean fetchNewestCurrent)
        Deprecated.
        Use FileParsingParameters#setObsoleteBehavior() instead (4.0.0)
        if enabled, the reader searches for the newest possible PDB ID, if not present in he local installation. The setFetchFileEvenIfObsolete(boolean) function has a higher priority than this function.
        N.B. This feature won't work unless the structure wasn't found & autoFetch is set to true.
        Parameters:
        fetchCurrent - the fetchCurrent to set
        Since:
        3.0.2
        See Also:
        setFetchFileEvenIfObsolete(boolean)
      • setFetchFileEvenIfObsolete

        @Deprecated
        public void setFetchFileEvenIfObsolete​(boolean fetchFileEvenIfObsolete)
        Deprecated.
        Use FileParsingParameters#setObsoleteBehavior() instead (4.0.0)
        N.B. This feature won't work unless the structure wasn't found & autoFetch is set to true.
        Parameters:
        fetchFileEvenIfObsolete - the fetchFileEvenIfObsolete to set
      • setObsoleteBehavior

        public void setObsoleteBehavior​(LocalPDBDirectory.ObsoleteBehavior behavior)
        [Optional] This method changes the behavior when obsolete entries are requested. Current behaviors are:
        • THROW_EXCEPTION Throw a StructureException (the default)
        • FETCH_OBSOLETE Load the requested ID from the PDB's obsolete repository
        • FETCH_CURRENT Load the most recent version of the requested structure

          This setting may be silently ignored by implementations which do not have access to the server to determine whether an entry is obsolete, such as if isAutoFetch() is false. Note that an obsolete entry may still be returned even this is FETCH_CURRENT if the entry is found locally.

        Parameters:
        fetchFileEvenIfObsolete - Whether to fetch obsolete records
        Since:
        4.0.0
        See Also:
        setFetchCurrent(boolean)
      • getObsoleteBehavior

        public LocalPDBDirectory.ObsoleteBehavior getObsoleteBehavior()
        Returns how this instance deals with obsolete entries. Note that this setting may be ignored by some implementations or in some situations, such as when isAutoFetch() is false.

        For most implementations, the default value is THROW_EXCEPTION.

        Returns:
        The ObsoleteBehavior
        Since:
        4.0.0
      • setFetchBehavior

        public void setFetchBehavior​(LocalPDBDirectory.FetchBehavior fetchBehavior)
        Set the behavior for fetching files from the server
        Parameters:
        fetchBehavior -
      • setPath

        public void setPath​(java.lang.String path)
        Set the path that is used to cache PDB files.
        Parameters:
        path - to a directory
      • setPdpprovider

        public void setPdpprovider​(PDPProvider pdpprovider)
      • isUseMmCif

        public boolean isUseMmCif()
        Returns:
        the useMmCif
      • setUseMmCif

        public void setUseMmCif​(boolean useMmCif)
        Parameters:
        useMmCif - the useMmCif to set
      • flagLoading

        protected void flagLoading​(java.lang.String name)
      • flagLoadingFinished

        protected void flagLoadingFinished​(java.lang.String name)
      • getStructureForPdbId

        public Structure getStructureForPdbId​(java.lang.String pdbId)
                                       throws java.io.IOException,
                                              StructureException
        Loads a structure directly by PDB ID
        Parameters:
        pdbId -
        Returns:
        Throws:
        java.io.IOException
        StructureException