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 Summary
Fields Modifier and Type Field Description static String
BIOL_ASSEMBLY_IDENTIFIER
static String
CHAIN_NR_SYMBOL
static String
CHAIN_SPLIT_SYMBOL
static boolean
DEFAULT_BIOASSEMBLY_STYLE
The default output bioassembly style: if true the bioassemblies are multimodel, if false the bioassemblies are flat with renamed chains for symmetry-partners.protected FileParsingParameters
params
static String
PDP_DOMAIN_IDENTIFIER
protected PDPProvider
pdpprovider
static String
UNDERSCORE
-
Constructor Summary
Constructors Constructor Description AtomCache()
Default AtomCache constructor.AtomCache(String pdbFilePath)
Creates an instance of an AtomCache that is pointed to the a particular path in the file system.AtomCache(String pdbFilePath, String cachePath)
Creates an instance of an AtomCache that is pointed to the a particular path in the file system.AtomCache(UserConfiguration config)
Creates a new AtomCache object based on the provided UserConfiguration.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected void
flagLoading(String name)
protected void
flagLoadingFinished(String name)
Atom[]
getAtoms(String name)
Returns the CA atoms for the provided name.Atom[]
getAtoms(StructureIdentifier name)
List<Structure>
getBiologicalAssemblies(String pdbId, boolean multiModel)
Returns all biological assemblies for given PDB id.Structure
getBiologicalAssembly(String pdbId, boolean multiModel)
Returns the default biological unit (bioassemblyId=1, known in PDB as pdb1.gz).Structure
getBiologicalAssembly(String pdbId, int bioAssemblyId, boolean multiModel)
Returns the biological assembly for a given PDB ID and bioAssemblyId, by building the assembly from the biounit annotations found inStructure.getPDBHeader()
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.String
getPath()
Get the path that is used to cache PDB files.PDPProvider
getPdpprovider()
Atom[]
getRepresentativeAtoms(String name)
Returns the representative atoms for the provided name.Atom[]
getRepresentativeAtoms(StructureIdentifier name)
Structure
getStructure(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(String scopId)
Returns the representation of aScopDomain
as a BioJavaStructure
object.Structure
getStructureForDomain(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(String pdbId)
Loads a structure directly by PDB IDboolean
isUseMmCif()
boolean
isUseMmtf()
Returns useMmtf flagprotected Structure
loadStructureFromCifByPdbId(String pdbId)
protected Structure
loadStructureFromPdbByPdbId(String pdbId)
void
notifyShutdown()
Send a signal to the cache that the system is shutting down.void
setCachePath(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
setFileParsingParams(FileParsingParameters params)
void
setObsoleteBehavior(LocalPDBDirectory.ObsoleteBehavior behavior)
[Optional] This method changes the behavior when obsolete entries are requested.void
setPath(String path)
Set the path that is used to cache PDB files.void
setPdpprovider(PDPProvider pdpprovider)
void
setUseMmCif(boolean useMmCif)
void
setUseMmtf(boolean useMmtf)
Set whether to use mmtf.
-
-
-
Field Detail
-
DEFAULT_BIOASSEMBLY_STYLE
public static final boolean DEFAULT_BIOASSEMBLY_STYLE
The default output bioassembly style: if true the bioassemblies are multimodel, if false the bioassemblies are flat with renamed chains for symmetry-partners.- See Also:
- Constant Field Values
-
BIOL_ASSEMBLY_IDENTIFIER
public static final String BIOL_ASSEMBLY_IDENTIFIER
- See Also:
- Constant Field Values
-
CHAIN_NR_SYMBOL
public static final String CHAIN_NR_SYMBOL
- See Also:
- Constant Field Values
-
CHAIN_SPLIT_SYMBOL
public static final String CHAIN_SPLIT_SYMBOL
- See Also:
- Constant Field Values
-
PDP_DOMAIN_IDENTIFIER
public static final String PDP_DOMAIN_IDENTIFIER
- See Also:
- Constant Field Values
-
UNDERSCORE
public static final 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(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
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(String name) throws 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:
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. SeegetStructure(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 multiModel) throws StructureException, IOException
Returns the biological assembly for a given PDB ID and bioAssemblyId, by building the assembly from the biounit annotations found inStructure.getPDBHeader()
Note, the number of available biological unit files varies. Many entries don't have a biological assembly specified (e.g. NMR structures), many entries have only one biological assembly (bioAssemblyId=1), and some structures have multiple biological assemblies.
- Parameters:
pdbId
- the PDB IDbioAssemblyId
- the 1-based index of the biological assembly (0 gets the asymmetric unit)multiModel
- if true the output Structure will be a multi-model one with one transformId per model, if false the outputStructure will be as the original with added chains with renamed asymIds (in the form originalAsymId_transformId and originalAuthId_transformId).- Returns:
- a structure object
- Throws:
IOException
StructureException
- if biassemblyId < 0 or other problems while loading structure- Since:
- 3.2
-
getBiologicalAssembly
public Structure getBiologicalAssembly(String pdbId, boolean multiModel) throws StructureException, IOException
Returns the default biological unit (bioassemblyId=1, known in PDB as pdb1.gz). If it is not available, the asymmetric unit will be returned, e.g. for NMR structures.Biological assemblies can also be accessed using getStructure("BIO:[pdbId]")
- Parameters:
pdbId
- the PDB idmultiModel
- if true the output Structure will be a multi-model one with one transformId per model, if false the outputStructure will be as the original with added chains with renamed asymIds (in the form originalAsymId_transformId and originalAuthId_transformId).- Returns:
- a structure object
- Throws:
IOException
StructureException
- Since:
- 4.2
-
getBiologicalAssemblies
public List<Structure> getBiologicalAssemblies(String pdbId, boolean multiModel) throws StructureException, IOException
Returns all biological assemblies for given PDB id.- Parameters:
pdbId
-multiModel
- if true the output Structure will be a multi-model one with one transformId per model, if false the outputStructure will be as the original with added chains with renamed asymIds (in the form originalAsymId_transformId and originalAuthId_transformId).- Returns:
- Throws:
StructureException
IOException
- Since:
- 5.0
-
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 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 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:
IOException
StructureException
-
getStructureForDomain
public Structure getStructureForDomain(ScopDomain domain) throws IOException, StructureException
Returns the representation of aScopDomain
as a BioJavaStructure
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 aScopDomain
as a BioJavaStructure
object.- Parameters:
domain
- a SCOP domainscopDatabase
- AScopDatabase
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 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:
IOException
StructureException
-
getStructureForDomain
public Structure getStructureForDomain(String scopId) throws IOException, StructureException
Returns the representation of aScopDomain
as a BioJavaStructure
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 aScopDomain
as a BioJavaStructure
object.- Parameters:
scopId
- a SCOP IdscopDatabase
- AScopDatabase
to use- Returns:
- a Structure object
- Throws:
IOException
StructureException
-
notifyShutdown
public void notifyShutdown()
Send a signal to the cache that the system is shutting down. Notifies underlying SerializableCache instances to flush themselves...
-
setCachePath
public void setCachePath(String cachePath)
set the location at which utility data should be cached.- Parameters:
cachePath
-
-
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 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)
-
isUseMmCif
public boolean isUseMmCif()
- Returns:
- the useMmCif
-
setUseMmCif
public void setUseMmCif(boolean useMmCif)
- Parameters:
useMmCif
- the useMmCif to set
-
setUseMmtf
public void setUseMmtf(boolean useMmtf)
Set whether to use mmtf.- Parameters:
useMmtf
- the input boolean to set
-
isUseMmtf
public boolean isUseMmtf()
Returns useMmtf flag- Returns:
- true if will load data via mmtf file format
-
getStructureForCathDomain
public Structure getStructureForCathDomain(StructureName structureName) throws IOException, StructureException
Returns aStructure
corresponding to the CATH identifier supplied instructureName
, using the theCathDatabase
atCathFactory.getCathDatabase()
.- Throws:
IOException
StructureException
-
getStructureForCathDomain
public Structure getStructureForCathDomain(StructureName structureName, CathDatabase cathInstall) throws IOException, StructureException
Returns aStructure
corresponding to the CATH identifier supplied instructureName
, using the specifiedCathDatabase
.- 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
-
-