JAL-1632 add score model params to PCAModel and PCA constructors
[jalview.git] / src / jalview / datamodel / PDBEntry.java
1 /*
2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
4  * 
5  * This file is part of Jalview.
6  * 
7  * Jalview is free software: you can redistribute it and/or
8  * modify it under the terms of the GNU General Public License 
9  * as published by the Free Software Foundation, either version 3
10  * of the License, or (at your option) any later version.
11  *  
12  * Jalview is distributed in the hope that it will be useful, but 
13  * WITHOUT ANY WARRANTY; without even the implied warranty 
14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
15  * PURPOSE.  See the GNU General Public License for more details.
16  * 
17  * You should have received a copy of the GNU General Public License
18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
19  * The Jalview Authors are detailed in the 'AUTHORS' file.
20  */
21 package jalview.datamodel;
22
23 import jalview.util.CaseInsensitiveString;
24
25 import java.util.Collections;
26 import java.util.Enumeration;
27 import java.util.Hashtable;
28
29 public class PDBEntry
30 {
31
32   /**
33    * constant for storing chain code in properties table
34    */
35   private static final String CHAIN_ID = "chain_code";
36
37   private Hashtable<String, Object> properties;
38
39   private static final int PDB_ID_LENGTH = 4;
40
41   private String file;
42
43   private String type;
44
45   private String id;
46
47   public enum Type
48   {
49     // TODO is FILE needed; if not is this enum needed, or can we
50     // use FileFormatI for PDB, MMCIF?
51     PDB("pdb", "pdb"), MMCIF("mmcif", "cif"), FILE("?", "?");
52
53     /*
54      * file extension for cached structure file; must be one that
55      * is recognised by Chimera 'open' command
56      * @see https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/filetypes.html
57      */
58     String ext;
59
60     /*
61      * format specifier used in dbfetch request
62      * @see http://www.ebi.ac.uk/Tools/dbfetch/dbfetch/dbfetch.databases#pdb
63      */
64     String format;
65
66     private Type(String fmt, String ex)
67     {
68       format = fmt;
69       ext = ex;
70     }
71
72     public String getFormat()
73     {
74       return format;
75     }
76     public String getExtension()
77     {
78       return ext;
79     }
80
81     /**
82      * case insensitive matching for Type enum
83      * 
84      * @param value
85      * @return
86      */
87     public static Type getType(String value)
88     {
89       for (Type t : Type.values())
90       {
91         if (t.toString().equalsIgnoreCase(value))
92         {
93           return t;
94         }
95       }
96       return null;
97     }
98
99     /**
100      * case insensitive equivalence for strings resolving to PDBEntry type
101      * 
102      * @param t
103      * @return
104      */
105     public boolean matches(String t)
106     {
107       return (this.toString().equalsIgnoreCase(t));
108     }
109   }
110
111   /**
112    * Answers true if obj is a PDBEntry with the same id and chain code (both
113    * ignoring case), file, type and properties
114    */
115   @Override
116   public boolean equals(Object obj)
117   {
118     if (obj == null || !(obj instanceof PDBEntry))
119     {
120       return false;
121     }
122     if (obj == this)
123     {
124       return true;
125     }
126     PDBEntry o = (PDBEntry) obj;
127
128     /*
129      * note that chain code is stored as a property wrapped by a 
130      * CaseInsensitiveString, so we are in effect doing a 
131      * case-insensitive comparison of chain codes
132      */
133     boolean idMatches = id == o.id
134             || (id != null && id.equalsIgnoreCase(o.id));
135     boolean fileMatches = file == o.file
136             || (file != null && file.equals(o.file));
137     boolean typeMatches = type == o.type
138             || (type != null && type.equals(o.type));
139     if (idMatches && fileMatches && typeMatches)
140     {
141       return properties == o.properties
142               || (properties != null && properties.equals(o.properties));
143     }
144     return false;
145   }
146
147   /**
148    * Default constructor
149    */
150   public PDBEntry()
151   {
152   }
153
154
155   public PDBEntry(String pdbId, String chain, PDBEntry.Type type,
156           String filePath)
157   {
158     init(pdbId, chain, type, filePath);
159   }
160
161   /**
162    * @param pdbId
163    * @param chain
164    * @param entryType
165    * @param filePath
166    */
167   void init(String pdbId, String chain, PDBEntry.Type entryType, String filePath)
168   {
169     this.id = pdbId;
170     this.type = entryType == null ? null : entryType.toString();
171     this.file = filePath;
172     setChainCode(chain);
173   }
174
175   /**
176    * Copy constructor.
177    * 
178    * @param entry
179    */
180   public PDBEntry(PDBEntry entry)
181   {
182     file = entry.file;
183     type = entry.type;
184     id = entry.id;
185     if (entry.properties != null)
186     {
187       properties = (Hashtable<String, Object>) entry.properties.clone();
188     }
189   }
190
191   /**
192    * Make a PDBEntry from a DBRefEntry. The accession code is used for the PDB
193    * id, but if it is 5 characters in length, the last character is removed and
194    * set as the chain code instead.
195    * 
196    * @param dbr
197    */
198   public PDBEntry(DBRefEntry dbr)
199   {
200     if (!DBRefSource.PDB.equals(dbr.getSource()))
201     {
202       throw new IllegalArgumentException("Invalid source: "
203               + dbr.getSource());
204     }
205
206     String pdbId = dbr.getAccessionId();
207     String chainCode = null;
208     if (pdbId.length() == PDB_ID_LENGTH + 1)
209     {
210       char chain = pdbId.charAt(PDB_ID_LENGTH);
211       if (('a' <= chain && chain <= 'z') || ('A' <= chain && chain <= 'Z'))
212       {
213         pdbId = pdbId.substring(0, PDB_ID_LENGTH);
214         chainCode = String.valueOf(chain);
215       }
216     }
217     init(pdbId, chainCode, null, null);
218   }
219
220   public void setFile(String f)
221   {
222     this.file = f;
223   }
224
225   public String getFile()
226   {
227     return file;
228   }
229
230   public void setType(String t)
231   {
232     this.type = t;
233   }
234
235   public void setType(PDBEntry.Type type)
236   {
237     this.type = type == null ? null : type.toString();
238   }
239
240   public String getType()
241   {
242     return type;
243   }
244
245   public void setId(String id)
246   {
247     this.id = id;
248   }
249
250   public String getId()
251   {
252     return id;
253   }
254
255   public void setProperty(String key, Object value)
256   {
257     if (this.properties == null)
258     {
259       this.properties = new Hashtable<String, Object>();
260     }
261     properties.put(key, value);
262   }
263
264   public Object getProperty(String key)
265   {
266     return properties == null ? null : properties.get(key);
267   }
268
269   /**
270    * Returns an enumeration of the keys of this object's properties (or an empty
271    * enumeration if it has no properties)
272    * 
273    * @return
274    */
275   public Enumeration<String> getProperties()
276   {
277     if (properties == null)
278     {
279       return Collections.emptyEnumeration();
280     }
281     return properties.keys();
282   }
283
284   /**
285    * 
286    * @return null or a string for associated chain IDs
287    */
288   public String getChainCode()
289   {
290     return (properties == null || properties.get(CHAIN_ID) == null) ? null
291             : properties.get(CHAIN_ID).toString();
292   }
293
294   /**
295    * Sets a non-case-sensitive property for the given chain code. Two PDBEntry
296    * objects which differ only in the case of their chain code are considered
297    * equal. This avoids duplication of objects in lists of PDB ids.
298    * 
299    * @param chainCode
300    */
301   public void setChainCode(String chainCode)
302   {
303     if (chainCode == null)
304     {
305       deleteProperty(CHAIN_ID);
306     }
307     else
308     {
309       setProperty(CHAIN_ID, new CaseInsensitiveString(chainCode));
310     }
311   }
312
313   /**
314    * Deletes the property with the given key, and returns the deleted value (or
315    * null)
316    */
317   Object deleteProperty(String key)
318   {
319     Object result = null;
320     if (properties != null)
321     {
322       result = properties.remove(key);
323     }
324     return result;
325   }
326
327   @Override
328   public String toString()
329   {
330     return id;
331   }
332
333   /**
334    * Getter provided for Castor binding only. Application code should call
335    * getProperty() or getProperties() instead.
336    * 
337    * @deprecated
338    * @see #getProperty(String)
339    * @see #getProperties()
340    * @see jalview.ws.dbsources.Uniprot#getUniprotEntries
341    * @return
342    */
343   @Deprecated
344   public Hashtable<String, Object> getProps()
345   {
346     return properties;
347   }
348
349   /**
350    * Setter provided for Castor binding only. Application code should call
351    * setProperty() instead.
352    * 
353    * @deprecated
354    * @return
355    */
356   @Deprecated
357   public void setProps(Hashtable<String, Object> props)
358   {
359     properties = props;
360   }
361
362   /**
363    * Answers true if this object is either equivalent to, or can be 'improved'
364    * by, the given entry.
365    * <p>
366    * If newEntry has the same id (ignoring case), and doesn't have a conflicting
367    * file spec or chain code, then update this entry from its file and/or chain
368    * code.
369    * 
370    * @param newEntry
371    * @return true if modifications were made
372    */
373   public boolean updateFrom(PDBEntry newEntry)
374   {
375     if (this.equals(newEntry))
376     {
377       return true;
378     }
379
380     String newId = newEntry.getId();
381     if (newId == null || getId() == null)
382     {
383       return false; // shouldn't happen
384     }
385
386     /*
387      * id has to match (ignoring case)
388      */
389     if (!getId().equalsIgnoreCase(newId))
390     {
391       return false;
392     }
393
394     /*
395      * Don't update if associated with different structure files
396      */
397     String newFile = newEntry.getFile();
398     if (newFile != null && getFile() != null && !newFile.equals(getFile()))
399     {
400       return false;
401     }
402
403     /*
404      * Don't update if associated with different chains (ignoring case)
405      */
406     String newChain = newEntry.getChainCode();
407     if (newChain != null && newChain.length() > 0 && getChainCode() != null
408             && getChainCode().length() > 0
409             && !getChainCode().equalsIgnoreCase(newChain))
410     {
411       return false;
412     }
413
414     /*
415      * set file path if not already set
416      */
417     String newType = newEntry.getType();
418     if (getFile() == null && newFile != null)
419     {
420       setFile(newFile);
421       setType(newType);
422     }
423
424     /*
425      * set file type if new entry has it and we don't
426      * (for the case where file was not updated)
427      */
428     if (getType() == null && newType != null)
429     {
430       setType(newType);
431     }
432
433     /*
434      * set chain if not already set (we excluded differing 
435      * chains earlier) (ignoring case change only)
436      */
437     if (newChain != null && newChain.length() > 0
438             && !newChain.equalsIgnoreCase(getChainCode()))
439     {
440       setChainCode(newChain);
441     }
442
443     /*
444      * copy any new or modified properties
445      */
446     Enumeration<String> newProps = newEntry.getProperties();
447     while (newProps.hasMoreElements())
448     {
449       /*
450        * copy properties unless value matches; this defends against changing
451        * the case of chain_code which is wrapped in a CaseInsensitiveString
452        */
453       String key = newProps.nextElement();
454       Object value = newEntry.getProperty(key);
455       if (!value.equals(getProperty(key)))
456       {
457         setProperty(key, value);
458       }
459     }
460     return true;
461   }
462 }