Package org.biojava.nbio.structure.io.density

Class DensityMapCache

java.lang.Object
org.biojava.nbio.structure.io.density.DensityMapCache
public class DensityMapCache extends Object
Downloads and caches electron density and cryo-EM maps, trying several sources in turn until one produces a map.

Cached files live under the BioJava cache directory (PDB_CACHE_DIR), laid out as described in DensityCacheLayout. Typical use is simply: 

 DensityMapCache cache = new DensityMapCache();
 DensityMapResult map = cache.getDensityMap(new PdbId("1cbs"), DensityMapKind.TWO_FO_FC);
 File file = map.getFile();

Source order. Sources are tried smallest-adequate-first, because they differ enormously in size for the same entry and the smallest is usually perfectly adequate to look at. For 1cbs a density-server slice is roughly a tenth the size of the equivalent pair of CCP4 files; for the cryo-EM entry behind EMD-0262 it is a few hundred kilobytes against 106 MB. Anything that cannot be displayed at all is tried last, and DensityMapSource.WWPDB_MAP_COEFFICIENTS is disabled altogether by default for that reason. Override with setSourceChain(DensityMapKind, java.util.List) or setSourceEnabled(DensityMapSource, boolean).

Failures. A source that has nothing for an entry is skipped and the next is tried; if every source is exhausted, NoDensityMapException is thrown carrying the reason from each one, so a caller can explain what happened. Genuine transport failures abort the chain instead, so that a network outage is never reported as "this entry has no density".

Since:
7.3.0
Author:
Amr ALHOSSARY

  • Field Details

    • DEFAULT_MAX_DOWNLOAD_BYTES

      public static final long DEFAULT_MAX_DOWNLOAD_BYTES
      Default ceiling on a single download, 256 MiB. Exceeding it is not an error: the chain moves on to a source that offers a smaller representation. Set to 0 to remove the limit.
      See Also:

    • DEFAULT_XRAY_SOURCE_CHAIN

      public static final List<DensityMapSource> DEFAULT_XRAY_SOURCE_CHAIN
      Order in which sources are tried for X-ray and neutron entries.

    • DEFAULT_EM_SOURCE_CHAIN

      public static final List<DensityMapSource> DEFAULT_EM_SOURCE_CHAIN
      Order in which sources are tried for cryo-EM entries.

  • Constructor Details

    • DensityMapCache

      public DensityMapCache()
      Creates a cache using the standard BioJava cache directory, i.e. PDB_CACHE_DIR falling back to PDB_DIR.

    • DensityMapCache

      public DensityMapCache(String cachePath)
      Parameters:
      cachePath - the directory to cache under

  • Method Details

    • getInstance

      public static DensityMapCache getInstance()
      A lazily created shared instance, for callers that do not want to manage one.
      Returns:
      the shared cache

    • getCachePath

      public String getCachePath()
      Returns:
      the directory maps are cached under

    • setCachePath

      public void setCachePath(String cachePath)
      Parameters:
      cachePath - the directory to cache under

    • getFetchBehavior

      public LocalPDBDirectory.FetchBehavior getFetchBehavior()
      Returns:
      how aggressively cached maps are re-fetched

    • setFetchBehavior

      public void setFetchBehavior(LocalPDBDirectory.FetchBehavior fetchBehavior)
      Parameters:
      fetchBehavior - how aggressively to re-fetch. LocalPDBDirectory.FetchBehavior.FETCH_REMEDIATED behaves as LocalPDBDirectory.FetchBehavior.FETCH_FILES: the 2011 remediation date is a coordinate-file concept with no meaning for maps.

    • getMaxDownloadBytes

      public long getMaxDownloadBytes()
      Returns:
      the ceiling on a single download in bytes, or 0 for no limit

    • setMaxDownloadBytes

      public void setMaxDownloadBytes(long maxDownloadBytes)
      Parameters:
      maxDownloadBytes - the ceiling on a single download in bytes, or 0 for no limit

    • getSourceChain

      public List<DensityMapSource> getSourceChain(DensityMapKind kind)
      The order sources are tried in for a given kind of map.
      Parameters:
      kind - the kind of map
      Returns:
      the source order

    • setSourceChain

      public void setSourceChain(DensityMapKind kind, List<DensityMapSource> chain)
      Overrides the order sources are tried in.
      Parameters:
      kind - DensityMapKind.EM to set the cryo-EM order, anything else to set the X-ray order
      chain - the new order

    • isSourceEnabled

      public boolean isSourceEnabled(DensityMapSource source)
      Parameters:
      source - the source
      Returns:
      whether it will be tried

    • setSourceEnabled

      public void setSourceEnabled(DensityMapSource source, boolean enabled)
      Enables or disables a source.

      DensityMapSource.WWPDB_MAP_COEFFICIENTS is disabled by default because it delivers structure factors rather than a map; enable it explicitly if you want the archival form and are prepared to run a Fourier transform.

      Parameters:
      source - the source
      enabled - whether to try it

    • registerProvider

      public void registerProvider(DensityMapProvider provider)
      Replaces the provider used for a source. Mainly a testing seam, but also the way to plug in a site-local mirror.
      Parameters:
      provider - the provider to use

    • getEmdbResolver

      public EmdbEntryResolver getEmdbResolver()
      Returns:
      the resolver used to map PDB entries to EMDB entries

    • setEmdbResolver

      public void setEmdbResolver(EmdbEntryResolver resolver)
      Parameters:
      resolver - the resolver used to map PDB entries to EMDB entries

    • getDensityMap

      public DensityMapResult getDensityMap(PdbId pdbId, DensityMapKind kind) throws IOException
      Fetches a density map, using the cache where possible.
      Parameters:
      pdbId - the entry
      kind - the kind of map, or DensityMapKind.AUTO to take whatever the entry has
      Returns:
      the map
      Throws:
      NoDensityMapException - if no enabled source has a map for this entry
      IOException - on transport failure

    • getDensityMap

      public DensityMapResult getDensityMap(String id, DensityMapKind kind) throws IOException
      Fetches a density map for a PDB or EMDB identifier.
      Parameters:
      id - a PDB identifier, or an EMDB identifier such as EMD-0262
      kind - the kind of map wanted
      Returns:
      the map
      Throws:
      NoDensityMapException - if no enabled source has a map for this entry
      IOException - on transport failure

    • getDensityMap

      public DensityMapResult getDensityMap(Structure structure, DensityMapKind kind) throws IOException
      Fetches a density map for an already-loaded structure.

      Knowing the structure lets the experimental method be read directly rather than guessed, so a cryo-EM entry goes straight to the EM sources instead of trying the X-ray ones first. No extra network request is involved.

      Parameters:
      structure - the structure
      kind - the kind of map wanted
      Returns:
      the map
      Throws:
      NoDensityMapException - if no enabled source has a map for this entry
      IOException - on transport failure

    • getDensityMap

      public DensityMapResult getDensityMap(DensityMapRequest request) throws IOException
      Fetches a density map.
      Parameters:
      request - what is wanted
      Returns:
      the map
      Throws:
      NoDensityMapException - if no enabled source has a map for this entry
      IOException - on transport failure

    • findDensityMap

      public Optional<DensityMapResult> findDensityMap(PdbId pdbId, DensityMapKind kind)
      As getDensityMap(PdbId, DensityMapKind) but returning an empty Optional rather than throwing when nothing is available. Genuine transport failures are still logged and swallowed, so use this only where "no map" and "could not reach the server" need not be told apart.
      Parameters:
      pdbId - the entry
      kind - the kind of map wanted
      Returns:
      the map, if one could be obtained

    • getDifferenceMapPair

      public List<DensityMapResult> getDifferenceMapPair(PdbId pdbId)
      Fetches both halves of the conventional X-ray pair: the 2mFo-DFc map and the mFo-DFc difference map.
      Parameters:
      pdbId - the entry
      Returns:
      whichever of the two could be obtained, in that order; possibly empty

    • getCached

      public DensityMapResult getCached(PdbId pdbId, DensityMapKind kind, DensityMapSource source)
      Looks a map up in the cache without contacting any server.
      Parameters:
      pdbId - the entry
      kind - the kind of map
      source - the source it would have come from
      Returns:
      the cached map, or null if it is not cached

    • deleteDensityMaps

      public int deleteDensityMaps(PdbId pdbId)
      Removes every cached density file for an entry, including the sidecars.
      Parameters:
      pdbId - the entry
      Returns:
      the number of files deleted