Package org.biojava.nbio.structure.align.util

Class AtomCache

java.lang.Object
org.biojava.nbio.structure.align.util.AtomCache
public class AtomCache extends 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

  • Field Details

  • Constructor Details

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

    • AtomCache

      public AtomCache(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(String pdbFilePath, 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(String pdbFilePath, boolean isSplit)
      Deprecated.
      isSplit parameter is ignored (4.0.0)
      Parameters:
      isSplit - Ignored

    • AtomCache

      @Deprecated public AtomCache(String pdbFilePath, 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 Details

    • getAtoms

      public Atom[] getAtoms(String name) throws IOException, StructureException
      Returns the CA atoms for the provided name. See getStructure(String) for supported naming conventions.

      This method only works with protein chains. Use getRepresentativeAtoms(String) for a more general solution.

      Parameters:
      name -
      Returns:
      an array of Atoms.
      Throws:
      IOException
      StructureException

    • getAtoms

      public Atom[] getAtoms(StructureIdentifier name) throws IOException, StructureException
      Throws:
      IOException
      StructureException

    • getRepresentativeAtoms

      public Atom[] getRepresentativeAtoms(String name) throws 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:
      IOException
      StructureException

    • getRepresentativeAtoms

      public Atom[] getRepresentativeAtoms(StructureIdentifier name) throws IOException, StructureException
      Throws:
      IOException
      StructureException

    • getBiologicalAssembly

      public Structure getBiologicalAssembly(String pdbId, int bioAssemblyId, boolean bioAssemblyFallback) throws StructureException, 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:
      IOException
      StructureException
      Since:
      3.2

    • getBiologicalAssembly

      public Structure getBiologicalAssembly(String pdbId) throws StructureException, 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:
      IOException
      StructureException
      Since:
      4.2

    • getBiologicalUnit

      @Deprecated public Structure getBiologicalUnit(String pdbId) throws StructureException, IOException
      Deprecated.
      Renamed to getBiologicalAssembly(String) in 4.2
      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:
      IOException
      StructureException
      Since:
      3.2

    • getBiologicalAssembly

      public Structure getBiologicalAssembly(String pdbId, int bioAssemblyId) throws StructureException, 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:
      IOException
      StructureException
      Since:
      4.2

    • getCachePath

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

    • getFileParsingParams

      public FileParsingParameters getFileParsingParams()

    • getPath

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

    • getPdpprovider

      public PDPProvider getPdpprovider()

    • getStructure

      public Structure getStructure(String name) throws 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:
      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.

    • getStructure

      public Structure getStructure(StructureIdentifier strucId) throws IOException, StructureException
      Get the structure corresponding to the given StructureIdentifier. Equivalent to calling StructureIdentifier.loadStructure(AtomCache) followed by StructureIdentifier.reduce(Structure).

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

      Parameters:
      strucId -
      Returns:
      Throws:
      IOException
      StructureException

    • getStructureForDomain

      public Structure getStructureForDomain(ScopDomain domain) throws IOException, StructureException
      Returns the representation of a ScopDomain as a BioJava Structure object.
      Parameters:
      domain - a SCOP domain
      Returns:
      a Structure object
      Throws:
      IOException
      StructureException

    • getStructureForDomain

      public Structure getStructureForDomain(ScopDomain domain, ScopDatabase scopDatabase) throws IOException, StructureException
      Returns the representation of a ScopDomain as a BioJava Structure object.
      Parameters:
      domain - a SCOP domain
      scopDatabase - A ScopDatabase to use
      Returns:
      a Structure object
      Throws:
      IOException
      StructureException

    • getStructureForDomain

      public Structure getStructureForDomain(ScopDomain domain, ScopDatabase scopDatabase, boolean strictLigandHandling) throws 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:
      IOException
      StructureException

    • getStructureForDomain

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

    • getStructureForDomain

      public Structure getStructureForDomain(String scopId, ScopDatabase scopDatabase) throws IOException, StructureException
      Returns the representation of a ScopDomain as a BioJava Structure object.
      Parameters:
      scopId - a SCOP Id
      scopDatabase - A ScopDatabase to use
      Returns:
      a Structure object
      Throws:
      IOException
      StructureException

    • isAutoFetch

      @Deprecated public boolean isAutoFetch()
      Deprecated.
      Use getFetchBehavior()
      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

    • isStrictSCOP

      @Deprecated public boolean isStrictSCOP()
      Deprecated.
      since 4.2
      Scop handling was changed in 4.2.0. For behaviour equivalent to strictSCOP==true, use ScopDatabase.getDomainByScopID(String). For strictSCOP==False, create a StructureName or use StructureName.guessScopDomain(String, ScopDatabase) explicitely.
      Returns:
      false; ignored

    • 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.
      Use getFetchBehavior()
      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(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

      @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

    • setFileParsingParams

      public void setFileParsingParams(FileParsingParameters params)

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

    • 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

    • getFetchBehavior

      public LocalPDBDirectory.FetchBehavior getFetchBehavior()
      Get the behavior for fetching files from the server
      Returns:

    • setFetchBehavior

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

    • setPath

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

    • setPdpprovider

      public void setPdpprovider(PDPProvider pdpprovider)

    • setStrictSCOP

      @Deprecated public void setStrictSCOP(boolean ignored)
      Deprecated.
      Removed in 4.2.0
      This method does nothing. Scop handling was changed in 4.2.0. For behaviour equivalent to strictSCOP==true, use ScopDatabase.getDomainByScopID(String). For strictSCOP==False, create a StructureName or use StructureName.guessScopDomain(String, ScopDatabase) explicitely.
      Parameters:
      strictSCOP - Ignored

    • isUseMmCif

      public boolean isUseMmCif()
      Returns:
      the useMmCif

    • setUseMmCif

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

    • getStructureForCathDomain

      public Structure getStructureForCathDomain(StructureName structureName) throws IOException, StructureException
      Returns a Structure corresponding to the CATH identifier supplied in structureName, using the the CathDatabase at CathFactory.getCathDatabase().
      Throws:
      IOException
      StructureException

    • getStructureForCathDomain

      public Structure getStructureForCathDomain(StructureName structureName, CathDatabase cathInstall) throws IOException, StructureException
      Returns a Structure corresponding to the CATH identifier supplied in structureName, using the specified CathDatabase.
      Throws:
      IOException
      StructureException

    • flagLoading

      protected void flagLoading(String name)

    • flagLoadingFinished

      protected void flagLoadingFinished(String name)

    • getStructureForPdbId

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

    • loadStructureFromCifByPdbId

      protected Structure loadStructureFromCifByPdbId(String pdbId) throws IOException, StructureException
      Throws:
      IOException
      StructureException

    • loadStructureFromPdbByPdbId

      protected Structure loadStructureFromPdbByPdbId(String pdbId) throws IOException, StructureException
      Throws:
      IOException
      StructureException