Class AtomCache
- java.lang.Object
-
- org.biojava.nbio.structure.align.util.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
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
BIOL_ASSEMBLY_IDENTIFIER
static java.lang.String
CHAIN_NR_SYMBOL
static java.lang.String
CHAIN_SPLIT_SYMBOL
protected FileParsingParameters
params
static java.lang.String
PDP_DOMAIN_IDENTIFIER
protected PDPProvider
pdpprovider
static java.lang.String
UNDERSCORE
-
Constructor Summary
Constructors Constructor Description AtomCache()
Default AtomCache constructor.AtomCache(java.lang.String pdbFilePath)
Creates an instance of an AtomCache that is pointed to the a particular path in the file system.AtomCache(java.lang.String pdbFilePath, boolean isSplit)
Deprecated.isSplit parameter is ignored (4.0.0)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.AtomCache(java.lang.String pdbFilePath, java.lang.String cachePath, boolean isSplit)
Deprecated.isSplit parameter is ignored (4.0.0)AtomCache(UserConfiguration config)
Creates a new AtomCache object based on the provided UserConfiguration.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description protected void
flagLoading(java.lang.String name)
protected void
flagLoadingFinished(java.lang.String name)
Atom[]
getAtoms(java.lang.String name)
Returns the CA atoms for the provided name.Atom[]
getAtoms(StructureIdentifier name)
Structure
getBiologicalAssembly(java.lang.String pdbId)
Loads the default biological unit (e.g.Structure
getBiologicalAssembly(java.lang.String pdbId, int bioAssemblyId)
Loads the default biological unit (e.g.Structure
getBiologicalAssembly(java.lang.String pdbId, int bioAssemblyId, boolean bioAssemblyFallback)
Loads the biological assembly for a given PDB ID and bioAssemblyId.Structure
getBiologicalUnit(java.lang.String pdbId)
Deprecated.Renamed togetBiologicalAssembly(String)
in 4.2java.lang.String
getCachePath()
Returns the path that contains the caching file for utility data, such as domain definitions.LocalPDBDirectory.FetchBehavior
getFetchBehavior()
Get the behavior for fetching files from the serverFileParsingParameters
getFileParsingParams()
LocalPDBDirectory.ObsoleteBehavior
getObsoleteBehavior()
Returns how this instance deals with obsolete entries.java.lang.String
getPath()
Get the path that is used to cache PDB files.PDPProvider
getPdpprovider()
Atom[]
getRepresentativeAtoms(java.lang.String name)
Returns the representative atoms for the provided name.Atom[]
getRepresentativeAtoms(StructureIdentifier name)
Structure
getStructure(java.lang.String name)
Request a Structure based on a name.Structure
getStructure(StructureIdentifier strucId)
Get the structure corresponding to the givenStructureIdentifier
.Structure
getStructureForCathDomain(StructureName structureName)
Returns aStructure
corresponding to the CATH identifier supplied instructureName
, using the theCathDatabase
atCathFactory.getCathDatabase()
.Structure
getStructureForCathDomain(StructureName structureName, CathDatabase cathInstall)
Returns aStructure
corresponding to the CATH identifier supplied instructureName
, using the specifiedCathDatabase
.Structure
getStructureForDomain(java.lang.String scopId)
Returns the representation of aScopDomain
as a BioJavaStructure
object.Structure
getStructureForDomain(java.lang.String scopId, ScopDatabase scopDatabase)
Returns the representation of aScopDomain
as a BioJavaStructure
object.Structure
getStructureForDomain(ScopDomain domain)
Returns the representation of aScopDomain
as a BioJavaStructure
object.Structure
getStructureForDomain(ScopDomain domain, ScopDatabase scopDatabase)
Returns the representation of aScopDomain
as a BioJavaStructure
object.Structure
getStructureForDomain(ScopDomain domain, ScopDatabase scopDatabase, boolean strictLigandHandling)
Returns the representation of aScopDomain
as a BioJavaStructure
object.Structure
getStructureForPdbId(java.lang.String pdbId)
Loads a structure directly by PDB IDboolean
isAutoFetch()
Deprecated.boolean
isFetchCurrent()
Deprecated.UseFileParsingParameters#getObsoleteBehavior()
instead (4.0.0)boolean
isFetchFileEvenIfObsolete()
Deprecated.UseFileParsingParameters#getObsoleteBehavior()
instead (4.0.0)boolean
isStrictSCOP()
Deprecated.since 4.2boolean
isUseMmCif()
protected Structure
loadStructureFromCifByPdbId(java.lang.String pdbId)
protected Structure
loadStructureFromPdbByPdbId(java.lang.String pdbId)
void
notifyShutdown()
Send a signal to the cache that the system is shutting down.void
setAutoFetch(boolean autoFetch)
Deprecated.void
setCachePath(java.lang.String cachePath)
set the location at which utility data should be cached.void
setFetchBehavior(LocalPDBDirectory.FetchBehavior fetchBehavior)
Set the behavior for fetching files from the servervoid
setFetchCurrent(boolean fetchNewestCurrent)
Deprecated.UseFileParsingParameters#setObsoleteBehavior()
instead (4.0.0)void
setFetchFileEvenIfObsolete(boolean fetchFileEvenIfObsolete)
Deprecated.UseFileParsingParameters#setObsoleteBehavior()
instead (4.0.0)void
setFileParsingParams(FileParsingParameters params)
void
setObsoleteBehavior(LocalPDBDirectory.ObsoleteBehavior behavior)
[Optional] This method changes the behavior when obsolete entries are requested.void
setPath(java.lang.String path)
Set the path that is used to cache PDB files.void
setPdpprovider(PDPProvider pdpprovider)
void
setStrictSCOP(boolean ignored)
Deprecated.Removed in 4.2.0void
setUseMmCif(boolean useMmCif)
-
-
-
Field Detail
-
BIOL_ASSEMBLY_IDENTIFIER
public static final java.lang.String BIOL_ASSEMBLY_IDENTIFIER
- See Also:
- Constant Field Values
-
CHAIN_NR_SYMBOL
public static final java.lang.String CHAIN_NR_SYMBOL
- See Also:
- Constant Field Values
-
CHAIN_SPLIT_SYMBOL
public static final java.lang.String CHAIN_SPLIT_SYMBOL
- See Also:
- Constant Field Values
-
PDP_DOMAIN_IDENTIFIER
public static final java.lang.String PDP_DOMAIN_IDENTIFIER
- See Also:
- Constant Field Values
-
UNDERSCORE
public static final java.lang.String UNDERSCORE
- See Also:
- Constant Field Values
-
params
protected FileParsingParameters params
-
pdpprovider
protected PDPProvider pdpprovider
-
-
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
-
getAtoms
public Atom[] getAtoms(java.lang.String name) throws java.io.IOException, StructureException
Returns the CA atoms for the provided name. SeegetStructure(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:
java.io.IOException
StructureException
-
getAtoms
public Atom[] getAtoms(StructureIdentifier name) throws java.io.IOException, StructureException
- Throws:
java.io.IOException
StructureException
-
getRepresentativeAtoms
public Atom[] getRepresentativeAtoms(java.lang.String name) throws java.io.IOException, StructureException
Returns the representative atoms for the provided name. SeegetStructure(String)
for supported naming conventions.- Parameters:
name
-- Returns:
- an array of Atoms.
- Throws:
java.io.IOException
StructureException
-
getRepresentativeAtoms
public Atom[] getRepresentativeAtoms(StructureIdentifier name) throws java.io.IOException, StructureException
- 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 IDbioAssemblyId
- 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.Renamed togetBiologicalAssembly(String)
in 4.2Loads 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 IDbioAssemblyId
- 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:
-
getFileParsingParams
public FileParsingParameters getFileParsingParams()
-
getPath
public java.lang.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(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 errorsStructureException
- 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 java.io.IOException, StructureException
Get the structure corresponding to the givenStructureIdentifier
. Equivalent to callingStructureIdentifier.loadStructure(AtomCache)
followed byStructureIdentifier.reduce(Structure)
.Note that this method should not be used in StructureIdentifier implementations to avoid circular calls.
- Parameters:
strucId
-- Returns:
- Throws:
java.io.IOException
StructureException
-
getStructureForDomain
public Structure getStructureForDomain(ScopDomain domain) throws java.io.IOException, StructureException
Returns the representation of aScopDomain
as a BioJavaStructure
object.- Parameters:
domain
- a SCOP domain- Returns:
- a Structure object
- Throws:
java.io.IOException
StructureException
-
getStructureForDomain
public Structure getStructureForDomain(ScopDomain domain, ScopDatabase scopDatabase) throws java.io.IOException, StructureException
Returns the representation of aScopDomain
as a BioJavaStructure
object.- Parameters:
domain
- a SCOP domainscopDatabase
- AScopDatabase
to use- Returns:
- a Structure object
- Throws:
java.io.IOException
StructureException
-
getStructureForDomain
public Structure getStructureForDomain(ScopDomain domain, ScopDatabase scopDatabase, boolean strictLigandHandling) throws java.io.IOException, StructureException
Returns the representation of aScopDomain
as a BioJavaStructure
object.- Parameters:
domain
- a SCOP domainscopDatabase
- AScopDatabase
to usestrictLigandHandling
- 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 aScopDomain
as a BioJavaStructure
object.- Parameters:
scopId
- a SCOP Id- Returns:
- a Structure object
- Throws:
java.io.IOException
StructureException
-
getStructureForDomain
public Structure getStructureForDomain(java.lang.String scopId, ScopDatabase scopDatabase) throws java.io.IOException, StructureException
Returns the representation of aScopDomain
as a BioJavaStructure
object.- Parameters:
scopId
- a SCOP IdscopDatabase
- AScopDatabase
to use- 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.UseFileParsingParameters#getObsoleteBehavior()
instead (4.0.0)N.B. This feature won't work unless the structure wasn't found & autoFetch is set totrue
.- Returns:
- the fetchCurrent
-
isFetchFileEvenIfObsolete
@Deprecated public boolean isFetchFileEvenIfObsolete()
Deprecated.UseFileParsingParameters#getObsoleteBehavior()
instead (4.0.0)forces the cache to fetch the file if its status is OBSOLETE. This feature has a higher priority thansetFetchCurrent(boolean)
.
N.B. This feature won't work unless the structure wasn't found & autoFetch is set totrue
.- Returns:
- the fetchFileEvenIfObsolete
- Since:
- 3.0.2
- See Also:
#fetchCurrent
-
isStrictSCOP
@Deprecated public boolean isStrictSCOP()
Deprecated.since 4.2Scop handling was changed in 4.2.0. For behaviour equivalent to strictSCOP==true, useScopDatabase.getDomainByScopID(String)
. For strictSCOP==False, create aStructureName
or useStructureName.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.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.UseFileParsingParameters#setObsoleteBehavior()
instead (4.0.0)if enabled, the reader searches for the newest possible PDB ID, if not present in he local installation. ThesetFetchFileEvenIfObsolete(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 totrue
.- Parameters:
fetchCurrent
- the fetchCurrent to set- Since:
- 3.0.2
- See Also:
setFetchFileEvenIfObsolete(boolean)
-
setFetchFileEvenIfObsolete
@Deprecated public void setFetchFileEvenIfObsolete(boolean fetchFileEvenIfObsolete)
Deprecated.UseFileParsingParameters#setObsoleteBehavior()
instead (4.0.0)N.B. This feature won't work unless the structure wasn't found & autoFetch is set totrue
.- 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 aStructureException
(the default)FETCH_OBSOLETE
Load the requested ID from the PDB's obsolete repositoryFETCH_CURRENT
Load the most recent version of the requested structureThis 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 whenisAutoFetch()
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(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)
-
setStrictSCOP
@Deprecated public void setStrictSCOP(boolean ignored)
Deprecated.Removed in 4.2.0This method does nothing. Scop handling was changed in 4.2.0. For behaviour equivalent to strictSCOP==true, useScopDatabase.getDomainByScopID(String)
. For strictSCOP==False, create aStructureName
or useStructureName.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 java.io.IOException, StructureException
Returns aStructure
corresponding to the CATH identifier supplied instructureName
, using the theCathDatabase
atCathFactory.getCathDatabase()
.- Throws:
java.io.IOException
StructureException
-
getStructureForCathDomain
public Structure getStructureForCathDomain(StructureName structureName, CathDatabase cathInstall) throws java.io.IOException, StructureException
Returns aStructure
corresponding to the CATH identifier supplied instructureName
, using the specifiedCathDatabase
.- Throws:
java.io.IOException
StructureException
-
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
-
loadStructureFromCifByPdbId
protected Structure loadStructureFromCifByPdbId(java.lang.String pdbId) throws java.io.IOException, StructureException
- Throws:
java.io.IOException
StructureException
-
loadStructureFromPdbByPdbId
protected Structure loadStructureFromPdbByPdbId(java.lang.String pdbId) throws java.io.IOException, StructureException
- Throws:
java.io.IOException
StructureException
-
-