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

Class DensityCacheLayout

java.lang.Object
org.biojava.nbio.structure.io.density.DensityCacheLayout
public class DensityCacheLayout extends Object
Where cached density files live on disk.

PDB-keyed maps follow the divided layout the rest of BioJava already uses, so that a cache with many entries does not end up with one enormous directory: 

 <cache>/density/cb/1cbs_2fofc_pdbe.ccp4
 <cache>/density/cb/1cbs_fofc_pdbe.ccp4
 <cache>/density/cb/1cbs_2fofc_rcsbvs_d0.bcif
 <cache>/density/cb/1cbs_2fofc_wwpdb.cif.gz
Both the kind and the source appear in the file name, so no two combinations can collide.

EMDB maps are keyed by EMDB identifier instead, mirroring the EMDB archive: 

 <cache>/density/emd/EMD-0262/emd_0262.map.gz
Several PDB entries are often fitted into a single EM map, and those maps can be hundreds of megabytes, so keying them by PDB entry would cache the same enormous file many times over.

The two-character directory needs no attention when the archive moves to extended identifiers in July 2027. It is a device for spreading files over directories, not a copy of the archive's own layout, and LocalPDBDirectory.getMiddleHash(String) counts from the right hand end of the identifier, so 1cbs and pdb_00001cbs both land in cb — which is also the rule the wwPDB documents for the new archive.

Deliberately not the archive's per-entry layout. A cache is not a mirror and cannot become one: the archive publishes structure factors and map coefficients but never grids, so density has to be fetched whatever else is mirrored, and writing it into a directory whose contents are an exact copy of upstream puts it at the mercy of the next rsync --delete. Should that judgement ever be revisited, every cached path is computed here and nowhere else, so a different layout is a change to this class plus a fallback probe for files in the old places — not a cache that everyone has to discard.

Since:
7.3.0
Author:
Amr ALHOSSARY

  • Field Details

    • DENSITY_DIR

      public static final String DENSITY_DIR
      Name of the density sub-directory within the BioJava cache directory.
      See Also:

    • EMDB_DIR

      public static final String EMDB_DIR
      Name of the sub-directory holding EMDB-keyed maps.
      See Also:

    • EMDB_MAPPING_DIR

      public static final String EMDB_MAPPING_DIR
      Name of the sub-directory holding cached PDB-to-EMDB mappings.
      See Also:

    • BOTH_KINDS_TOKEN

      public static final String BOTH_KINDS_TOKEN
      File-name token for a file that holds more than one kind of map, as a density server response does.
      See Also:

  • Method Details

    • densityRoot

      public static File densityRoot(File cacheRoot)
      The root density directory inside a cache directory.
      Parameters:
      cacheRoot - the BioJava cache directory
      Returns:
      the density directory, which need not exist yet

    • pdbMapFile

      public static File pdbMapFile(File cacheRoot, PdbId pdbId, DensityMapKind kind, DensityMapSource source, DensityFileFormat format, String qualifier)
      The cache file for a PDB-keyed map.
      Parameters:
      cacheRoot - the BioJava cache directory
      pdbId - the entry
      kind - the kind of map
      source - the service it came from
      format - the file format
      qualifier - an extra discriminator such as a detail level, or null. Anything that changes the content but not the entry, kind or source belongs here.
      Returns:
      the file, which need not exist

    • pdbMapFile

      public static File pdbMapFile(File cacheRoot, PdbId pdbId, String kindToken, DensityMapSource source, DensityFileFormat format, String qualifier)
      The cache file for a PDB-keyed map, naming the kind explicitly.

      The separate kind token exists for sources that deliver more than one kind of map in a single file. A density server response, for instance, carries both the 2Fo-Fc and the Fo-Fc blocks, so it is cached once under BOTH_KINDS_TOKEN rather than downloaded and stored twice.

      Parameters:
      cacheRoot - the BioJava cache directory
      pdbId - the entry
      kindToken - the token naming what the file holds
      source - the service it came from
      format - the file format
      qualifier - an extra discriminator such as a detail level, or null
      Returns:
      the file, which need not exist

    • emdbMapFile

      public static File emdbMapFile(File cacheRoot, String emdbId, DensityMapSource source, DensityFileFormat format, String qualifier)
      The cache file for an EMDB-keyed map.
      Parameters:
      cacheRoot - the BioJava cache directory
      emdbId - the EMDB entry, in any accepted form
      source - the service it came from
      format - the file format
      qualifier - an extra discriminator such as a detail level, or null
      Returns:
      the file, which need not exist

    • emdbMappingFile

      public static File emdbMappingFile(File cacheRoot, PdbId pdbId)
      The file caching the EMDB identifiers and author contour level associated with a PDB entry.
      Parameters:
      cacheRoot - the BioJava cache directory
      pdbId - the entry
      Returns:
      the file, which need not exist

    • emdbMapInfoFile

      public static File emdbMapInfoFile(File cacheRoot, String emdbId)
      The file caching an EMDB entry's map metadata as served by the EMDB API.
      Parameters:
      cacheRoot - the BioJava cache directory
      emdbId - the EMDB entry, in any accepted form
      Returns:
      the file, which need not exist

    • differenceMarkerFile

      public static File differenceMarkerFile(File mapFile)
      The companion name a density-server file must have for Jmol to read its difference-map block.

      A density server response holds both a 2FO-FC and an FO-FC data block, and Jmol's reader chooses between them by testing whether the file name contains the literal text &diff=1. That works for a URL fetched straight from the server, where the marker rides along in the query string, but a cached local file has no query string; appending the marker to the file URL only makes Jmol look for a file that does not exist. Putting the marker into the name itself is what actually selects the block.

      This was verified against Jmol 14.31.10 and is unchanged in current Jmol: the relevant line in BCifDensityReader still carries the author's "what about cached data" to-do beside it. Should Jmol gain a cleaner way to choose the block, this can be retired.

      Parameters:
      mapFile - the cached density-server file
      Returns:
      the sibling path that selects the difference map

    • shortIdOrFull

      public static String shortIdOrFull(PdbId pdbId)
      The short four-character spelling of an identifier where one exists.

      Every entry in the archive today has a four-character form, and the density services accept only that spelling. Extended-only identifiers will appear eventually; rather than refusing them, the extended spelling is passed through so that the services can start accepting it without a change here.

      Parameters:
      pdbId - the identifier
      Returns:
      the short spelling if available, otherwise the full one