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 Summary

Fields

Modifier and Type	Field and Description
static String	BIOL_ASSEMBLY_IDENTIFIER
static String	CHAIN_NR_SYMBOL
static String	CHAIN_SPLIT_SYMBOL
protected FileParsingParameters	params
static String	PDP_DOMAIN_IDENTIFIER
protected PDPProvider	pdpprovider
static String	UNDERSCORE

Constructor Summary

Constructors

Constructor and 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, boolean isSplit) Deprecated. isSplit parameter is ignored (4.0.0)
AtomCache(String pdbFilePath, String cachePath) Creates an instance of an AtomCache that is pointed to the a particular path in the file system.
AtomCache(String pdbFilePath, 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

Modifier and Type	Method and 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)
Structure	getBiologicalAssembly(String pdbId) Loads the default biological unit (e.g.
Structure	getBiologicalAssembly(String pdbId, int bioAssemblyId) Loads the default biological unit (e.g.
Structure	getBiologicalAssembly(String pdbId, int bioAssemblyId, boolean bioAssemblyFallback) Loads the biological assembly for a given PDB ID and bioAssemblyId.
Structure	getBiologicalUnit(String pdbId) Deprecated. Renamed to getBiologicalAssembly(String) in 4.2
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 server
FileParsingParameters	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 given StructureIdentifier.
Structure	getStructureForCathDomain(StructureName structureName) Returns a Structure corresponding to the CATH identifier supplied in structureName, using the the CathDatabase at CathFactory.getCathDatabase().
Structure	getStructureForCathDomain(StructureName structureName, CathDatabase cathInstall) Returns a Structure corresponding to the CATH identifier supplied in structureName, using the specified CathDatabase.
Structure	getStructureForDomain(ScopDomain domain) Returns the representation of a ScopDomain as a BioJava Structure object.
Structure	getStructureForDomain(ScopDomain domain, ScopDatabase scopDatabase) Returns the representation of a ScopDomain as a BioJava Structure object.
Structure	getStructureForDomain(ScopDomain domain, ScopDatabase scopDatabase, boolean strictLigandHandling) Returns the representation of a ScopDomain as a BioJava Structure object.
Structure	getStructureForDomain(String scopId) Returns the representation of a ScopDomain as a BioJava Structure object.
Structure	getStructureForDomain(String scopId, ScopDatabase scopDatabase) Returns the representation of a ScopDomain as a BioJava Structure object.
Structure	getStructureForPdbId(String pdbId) Loads a structure directly by PDB ID
boolean	isAutoFetch() Deprecated. Use getFetchBehavior()
boolean	isFetchCurrent() Deprecated. Use FileParsingParameters#getObsoleteBehavior() instead (4.0.0)
boolean	isFetchFileEvenIfObsolete() Deprecated. Use FileParsingParameters#getObsoleteBehavior() instead (4.0.0)
boolean	isStrictSCOP() Deprecated. since 4.2
boolean	isUseMmCif()
protected Structure	loadStructureFromCifByPdbId(String pdbId)
protected Structure	loadStructureFromPdbByPdbId(String pdbId)
void	notifyShutdown() Send a signal to the cache that the system is shutting down.
void	setAutoFetch(boolean autoFetch) Deprecated. Use getFetchBehavior()
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 server
void	setFetchCurrent(boolean fetchNewestCurrent) Deprecated. Use FileParsingParameters#setObsoleteBehavior() instead (4.0.0)
void	setFetchFileEvenIfObsolete(boolean fetchFileEvenIfObsolete) Deprecated. Use FileParsingParameters#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(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.0
void	setUseMmCif(boolean useMmCif)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

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.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

@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 Detail

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(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

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:

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)

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