001/* 002 * BioJava development code 003 * 004 * This code may be freely distributed and modified under the 005 * terms of the GNU Lesser General Public Licence. This should 006 * be distributed with the code. If you do not have a copy, 007 * see: 008 * 009 * http://www.gnu.org/copyleft/lesser.html 010 * 011 * Copyright for this code is held jointly by the individual 012 * authors. These should be listed in @author doc comments. 013 * 014 * For more information on the BioJava project and its aims, 015 * or to join the biojava-l mailing list, visit the home page 016 * at: 017 * 018 * http://www.biojava.org/ 019 * 020 */ 021package org.biojava.nbio.structure; 022 023import org.biojava.nbio.structure.align.util.AtomCache; 024import org.biojava.nbio.structure.io.StructureFiletype; 025 026import java.io.IOException; 027import java.util.List; 028 029/** 030 * A class that provides static access methods for easy lookup of protein structure related components 031 * 032 * @author Andreas Prlic 033 * 034 * @since 3.0.5 035 */ 036public class StructureIO { 037 private static AtomCache cache ; 038 039 /** 040 * Loads a structure based on a name. Supported naming conventions are: 041 * 042 * <pre> 043 Formal specification for how to specify the <i>name</i>: 044 045 name := pdbID 046 | pdbID '.' chainID 047 | pdbID '.' range 048 | scopID 049 | biol 050 | pdp 051 range := '('? range (',' range)? ')'? 052 | chainID 053 | chainID '_' resNum '-' resNum 054 pdbID := [1-9][a-zA-Z0-9]{3} 055 | PDB_[a-zA-Z0-9]{8} 056 chainID := [a-zA-Z0-9] 057 scopID := 'd' pdbID [a-z_][0-9_] 058 biol := 'BIO:' pdbID [:]? [0-9]+ 059 resNum := [-+]?[0-9]+[A-Za-z]? 060 061 062 Example structures: 063 1TIM #whole structure - asym unit (short format) 064 4HHB.C #single chain 065 4GCR.A_1-83 #one domain, by residue number 066 3AA0.A,B #two chains treated as one structure 067 PDB_00001TIM #whole structure - asym unit (extended format) 068 PDB_00004HHB.C #single chain 069 PDB_00004GCR.A_1-83 #one domain, by residue number 070 PDB_00003AA0.A,B #two chains treated as one structure 071 d2bq6a1 #scop domain 072 BIO:1fah #biological assembly nr 1 for 1fah 073 BIO:1fah:0 #asym unit for 1fah 074 BIO:1fah:1 #biological assembly nr 1 for 1fah 075 BIO:1fah:2 #biological assembly nr 2 for 1fah 076 077 * </pre> 078 * 079 * With the additional set of rules: 080 * 081 * <ul> 082 * <li>If only a PDB code is provided, the whole structure will be return including ligands, but the first model only (for NMR). 083 * <li>Chain IDs are case sensitive, PDB ids are not. To specify a particular chain write as: 4hhb.A or 4HHB.A </li> 084 * <li>To specify a SCOP domain write a scopId e.g. d2bq6a1. Some flexibility can be allowed in SCOP domain names, see {@link #setStrictSCOP(boolean)}</li> 085 * <li>URLs are accepted as well</li> 086 * </ul> 087 * 088 * @param name 089 * @return a Structure object, or null if name appears improperly formated (eg too short, etc) 090 * @throws IOException The PDB file cannot be cached due to IO errors 091 * @throws StructureException The name appeared valid but did not correspond to a structure. 092 * Also thrown by some submethods upon errors, eg for poorly formatted subranges. 093 */ 094 public static Structure getStructure(String name) throws IOException, StructureException { 095 checkInitAtomCache(); 096 // delegate this functionality to AtomCache... 097 return cache.getStructure(name); 098 } 099 100 private static void checkInitAtomCache() { 101 if (cache == null) { 102 cache = new AtomCache(); 103 } 104 } 105 106 public static void setAtomCache(AtomCache c){ 107 cache = c; 108 } 109 110 public static AtomCache getAtomCache() { 111 checkInitAtomCache(); 112 return cache; 113 } 114 115 /** 116 * Returns the first biological assembly that is available for the given PDB id. 117 * <p> 118 * The output Structure will be different depending on the multiModel parameter: 119 * <li> 120 * the symmetry-expanded chains are added as new models, one per transformId. All original models but 121 * the first one are discarded. 122 * </li> 123 * <li> 124 * as original with symmetry-expanded chains added with renamed chain ids and names (in the form 125 * originalAsymId_transformId and originalAuthId_transformId) 126 * </li> 127 * <p> 128 * For more documentation on quaternary structures see: 129 * {@link http://pdb101.rcsb.org/learn/guide-to-understanding-pdb-data/biological-assemblies} 130 * 131 * 132 * @param pdbId 133 * @param multiModel if true the output Structure will be a multi-model one with one transformId per model, 134 * if false the outputStructure will be as the original with added chains with renamed asymIds (in the form originalAsymId_transformId and originalAuthId_transformId). 135 * @return a Structure object or null if that assembly is not available 136 * @throws StructureException 137 * @throws IOException 138 */ 139 public static Structure getBiologicalAssembly(String pdbId, boolean multiModel) throws IOException, StructureException { 140 checkInitAtomCache(); 141 pdbId = pdbId.toLowerCase(); 142 return cache.getBiologicalAssembly(pdbId, multiModel); 143 } 144 145 /** 146 * Returns the first biological assembly that is available for the given PDB id, 147 * using multiModel={@value AtomCache#DEFAULT_BIOASSEMBLY_STYLE} 148 * <p> 149 * For more documentation on quaternary structures see: 150 * {@link http://pdb101.rcsb.org/learn/guide-to-understanding-pdb-data/biological-assemblies} 151 * 152 * 153 * @param pdbId 154 * @return a Structure object or null if that assembly is not available 155 * @throws StructureException 156 * @throws IOException 157 */ 158 public static Structure getBiologicalAssembly(String pdbId) throws IOException, StructureException { 159 return getBiologicalAssembly(pdbId, AtomCache.DEFAULT_BIOASSEMBLY_STYLE); 160 } 161 162 /** 163 * Returns the biological assembly for the given PDB id and bioassembly identifier. 164 * <p> 165 * The output Structure will be different depending on the multiModel parameter: 166 * <li> 167 * the symmetry-expanded chains are added as new models, one per transformId. All original models but 168 * the first one are discarded. 169 * </li> 170 * <li> 171 * as original with symmetry-expanded chains added with renamed chain ids and names (in the form 172 * originalAsymId_transformId and originalAuthId_transformId) 173 * </li> 174 * @param pdbId 175 * @param biolAssemblyNr - the ith biological assembly that is available for a PDB ID (we start counting at 1, 0 represents the asym unit). 176 * @param multiModel if true the output Structure will be a multi-model one with one transformId per model, 177 * if false the outputStructure will be as the original with added chains with renamed asymIds (in the form originalAsymId_transformId and originalAuthId_transformId). 178 * @return a Structure object or null if that assembly is not available 179 * @throws StructureException if there is no bioassembly available for given biolAssemblyNr or some other problems encountered while loading it 180 * @throws IOException 181 */ 182 public static Structure getBiologicalAssembly(String pdbId, int biolAssemblyNr, boolean multiModel) throws IOException, StructureException { 183 checkInitAtomCache(); 184 pdbId = pdbId.toLowerCase(); 185 return cache.getBiologicalAssembly(pdbId, biolAssemblyNr, multiModel); 186 } 187 188 /** 189 * Returns the biological assembly for the given PDB id and bioassembly identifier, 190 * using multiModel={@value AtomCache#DEFAULT_BIOASSEMBLY_STYLE} 191 * @param pdbId 192 * @param biolAssemblyNr - the ith biological assembly that is available for a PDB ID (we start counting at 1, 0 represents the asym unit). 193 * @return a Structure object or null if that assembly is not available 194 * @throws StructureException if there is no bioassembly available for given biolAssemblyNr or some other problems encountered while loading it 195 * @throws IOException 196 */ 197 public static Structure getBiologicalAssembly(String pdbId, int biolAssemblyNr) throws IOException, StructureException { 198 return getBiologicalAssembly(pdbId, biolAssemblyNr, AtomCache.DEFAULT_BIOASSEMBLY_STYLE); 199 } 200 201 /** 202 * Returns all biological assemblies for the given PDB id. 203 * <p> 204 * The output Structure will be different depending on the multiModel parameter: 205 * <li> 206 * the symmetry-expanded chains are added as new models, one per transformId. All original models but 207 * the first one are discarded. 208 * </li> 209 * <li> 210 * as original with symmetry-expanded chains added with renamed chain ids and names (in the form 211 * originalAsymId_transformId and originalAuthId_transformId) 212 * </li> 213 * If only one biological assembly is required use {@link #getBiologicalAssembly(String)} or {@link #getBiologicalAssembly(String, int)} instead. 214 * @param pdbId 215 * @param multiModel if true the output Structure will be a multi-model one with one transformId per model, 216 * if false the outputStructure will be as the original with added chains with renamed asymIds (in the form originalAsymId_transformId and originalAuthId_transformId). 217 * @return 218 * @throws IOException 219 * @throws StructureException 220 * @since 5.0 221 */ 222 public static List<Structure> getBiologicalAssemblies(String pdbId, boolean multiModel) throws IOException, StructureException { 223 checkInitAtomCache(); 224 pdbId = pdbId.toLowerCase(); 225 return cache.getBiologicalAssemblies(pdbId, multiModel); 226 } 227 228 /** 229 * Returns all biological assemblies for the given PDB id, 230 * using multiModel={@value AtomCache#DEFAULT_BIOASSEMBLY_STYLE} 231 * <p> 232 * If only one biological assembly is required use {@link #getBiologicalAssembly(String)} or {@link #getBiologicalAssembly(String, int)} instead. 233 * @param pdbId 234 * @return 235 * @throws IOException 236 * @throws StructureException 237 * @since 5.0 238 */ 239 public static List<Structure> getBiologicalAssemblies(String pdbId) throws IOException, StructureException { 240 return getBiologicalAssemblies(pdbId, AtomCache.DEFAULT_BIOASSEMBLY_STYLE); 241 } 242 243 /** 244 * Attempts to guess the type of a structure file based on the extension 245 * @param filename 246 * @return 247 */ 248 public static StructureFiletype guessFiletype(String filename) { 249 String lower = filename.toLowerCase(); 250 for (StructureFiletype type : StructureFiletype.values()) { 251 for (String ext : type.getExtensions()) { 252 if (lower.endsWith(ext.toLowerCase())) { 253 return type; 254 } 255 } 256 } 257 return StructureFiletype.UNKNOWN; 258 } 259}