src/jalview/structures/models/AAStructureBindingModel.java

   1 package jalview.structures.models;
   2
   3 import java.util.ArrayList;
   4 import java.util.Arrays;
   5 import java.util.List;
   6
   7 import jalview.api.StructureSelectionManagerProvider;
   8 import jalview.datamodel.PDBEntry;
   9 import jalview.datamodel.SequenceI;
  10 import jalview.structure.AtomSpec;
  11 import jalview.structure.StructureListener;
  12 import jalview.structure.StructureSelectionManager;
  13 import jalview.util.Comparison;
  14 import jalview.util.MessageManager;
  15
  16 /**
  17  *
  18  * A base class to hold common function for protein structure model binding.
  19  * Initial version created by refactoring JMol and Chimera binding models, but
  20  * other structure viewers could in principle be accommodated in future.
  21  *
  22  * @author gmcarstairs
  23  *
  24  */
  25 public abstract class AAStructureBindingModel extends
  26         SequenceStructureBindingModel implements StructureListener,
  27         StructureSelectionManagerProvider
  28 {
  29
  30   private StructureSelectionManager ssm;
  31
  32   private PDBEntry[] pdbEntry;
  33
  34   /*
  35    * sequences mapped to each pdbentry
  36    */
  37   private SequenceI[][] sequence;
  38
  39   /*
  40    * array of target chains for sequences - tied to pdbentry and sequence[]
  41    */
  42   private String[][] chains;
  43
  44   /*
  45    * datasource protocol for access to PDBEntrylatest
  46    */
  47   String protocol = null;
  48
  49   protected boolean colourBySequence = true;
  50
  51   private boolean nucleotide;
  52
  53   /**
  54    * Constructor
  55    *
  56    * @param ssm
  57    * @param seqs
  58    */
  59   public AAStructureBindingModel(StructureSelectionManager ssm,
  60           SequenceI[][] seqs)
  61   {
  62     this.ssm = ssm;
  63     this.sequence = seqs;
  64   }
  65
  66   /**
  67    * Constructor
  68    *
  69    * @param ssm
  70    * @param pdbentry
  71    * @param sequenceIs
  72    * @param chains
  73    * @param protocol
  74    */
  75   public AAStructureBindingModel(StructureSelectionManager ssm,
  76           PDBEntry[] pdbentry, SequenceI[][] sequenceIs, String[][] chains,
  77           String protocol)
  78   {
  79     this.ssm = ssm;
  80     this.sequence = sequenceIs;
  81     this.nucleotide = Comparison.isNucleotide(sequenceIs);
  82     this.chains = chains;
  83     this.pdbEntry = pdbentry;
  84     this.protocol = protocol;
  85     if (chains == null)
  86     {
  87       this.chains = new String[pdbentry.length][];
  88     }
  89   }
  90
  91   public StructureSelectionManager getSsm()
  92   {
  93     return ssm;
  94   }
  95
  96   /**
  97    * Returns the i'th PDBEntry (or null)
  98    *
  99    * @param i
 100    * @return
 101    */
 102   public PDBEntry getPdbEntry(int i)
 103   {
 104     return (pdbEntry != null && pdbEntry.length > i) ? pdbEntry[i] : null;
 105   }
 106
 107   /**
 108    * Answers true if this binding includes the given PDB id, else false
 109    *
 110    * @param pdbId
 111    * @return
 112    */
 113   public boolean hasPdbId(String pdbId)
 114   {
 115     if (pdbEntry != null)
 116     {
 117       for (PDBEntry pdb : pdbEntry)
 118       {
 119         if (pdb.getId().equals(pdbId))
 120         {
 121           return true;
 122         }
 123       }
 124     }
 125     return false;
 126   }
 127
 128   /**
 129    * Returns the number of modelled PDB file entries.
 130    *
 131    * @return
 132    */
 133   public int getPdbCount()
 134   {
 135     return pdbEntry == null ? 0 : pdbEntry.length;
 136   }
 137
 138   public SequenceI[][] getSequence()
 139   {
 140     return sequence;
 141   }
 142
 143   public String[][] getChains()
 144   {
 145     return chains;
 146   }
 147
 148   public String getProtocol()
 149   {
 150     return protocol;
 151   }
 152
 153   // TODO may remove this if calling methods can be pulled up here
 154   protected void setPdbentry(PDBEntry[] pdbentry)
 155   {
 156     this.pdbEntry = pdbentry;
 157   }
 158
 159   protected void setSequence(SequenceI[][] sequence)
 160   {
 161     this.sequence = sequence;
 162   }
 163
 164   protected void setChains(String[][] chains)
 165   {
 166     this.chains = chains;
 167   }
 168
 169   /**
 170    * Construct a title string for the viewer window based on the data Jalview
 171    * knows about
 172    * @param viewerName TODO
 173    * @param verbose
 174    *
 175    * @return
 176    */
 177   public String getViewerTitle(String viewerName, boolean verbose)
 178   {
 179     if (getSequence() == null || getSequence().length < 1
 180             || getPdbCount() < 1
 181             || getSequence()[0].length < 1)
 182     {
 183       return ("Jalview " + viewerName + " Window");
 184     }
 185     // TODO: give a more informative title when multiple structures are
 186     // displayed.
 187     StringBuilder title = new StringBuilder(64);
 188     final PDBEntry pdbEntry = getPdbEntry(0);
 189     title.append(viewerName + " view for " + getSequence()[0][0].getName()
 190             + ":"
 191             + pdbEntry.getId());
 192
 193     if (verbose)
 194     {
 195       if (pdbEntry.getProperty() != null)
 196       {
 197         if (pdbEntry.getProperty().get("method") != null)
 198         {
 199           title.append(" Method: ");
 200           title.append(pdbEntry.getProperty().get("method"));
 201         }
 202         if (pdbEntry.getProperty().get("chains") != null)
 203         {
 204           title.append(" Chain:");
 205           title.append(pdbEntry.getProperty().get("chains"));
 206         }
 207       }
 208     }
 209     return title.toString();
 210   }
 211
 212   /**
 213    * Called by after closeViewer is called, to release any resources and
 214    * references so they can be garbage collected. Override if needed.
 215    */
 216   protected void releaseUIResources()
 217   {
 218
 219   }
 220
 221   public boolean isColourBySequence()
 222   {
 223     return colourBySequence;
 224   }
 225
 226   public void setColourBySequence(boolean colourBySequence)
 227   {
 228     this.colourBySequence = colourBySequence;
 229   }
 230
 231   protected void addSequenceAndChain(int pe, SequenceI[] seq,
 232           String[] tchain)
 233   {
 234     if (pe < 0 || pe >= getPdbCount())
 235     {
 236       throw new Error(MessageManager.formatMessage(
 237               "error.implementation_error_no_pdbentry_from_index",
 238               new Object[]
 239               { Integer.valueOf(pe).toString() }));
 240     }
 241     final String nullChain = "TheNullChain";
 242     List<SequenceI> s = new ArrayList<SequenceI>();
 243     List<String> c = new ArrayList<String>();
 244     if (getChains() == null)
 245     {
 246       setChains(new String[getPdbCount()][]);
 247     }
 248     if (getSequence()[pe] != null)
 249     {
 250       for (int i = 0; i < getSequence()[pe].length; i++)
 251       {
 252         s.add(getSequence()[pe][i]);
 253         if (getChains()[pe] != null)
 254         {
 255           if (i < getChains()[pe].length)
 256           {
 257             c.add(getChains()[pe][i]);
 258           }
 259           else
 260           {
 261             c.add(nullChain);
 262           }
 263         }
 264         else
 265         {
 266           if (tchain != null && tchain.length > 0)
 267           {
 268             c.add(nullChain);
 269           }
 270         }
 271       }
 272     }
 273     for (int i = 0; i < seq.length; i++)
 274     {
 275       if (!s.contains(seq[i]))
 276       {
 277         s.add(seq[i]);
 278         if (tchain != null && i < tchain.length)
 279         {
 280           c.add(tchain[i] == null ? nullChain : tchain[i]);
 281         }
 282       }
 283     }
 284     SequenceI[] tmp = s.toArray(new SequenceI[s.size()]);
 285     getSequence()[pe] = tmp;
 286     if (c.size() > 0)
 287     {
 288       String[] tch = c.toArray(new String[c.size()]);
 289       for (int i = 0; i < tch.length; i++)
 290       {
 291         if (tch[i] == nullChain)
 292         {
 293           tch[i] = null;
 294         }
 295       }
 296       getChains()[pe] = tch;
 297     }
 298     else
 299     {
 300       getChains()[pe] = null;
 301     }
 302   }
 303
 304   /**
 305    * add structures and any known sequence associations
 306    *
 307    * @returns the pdb entries added to the current set.
 308    */
 309   public synchronized PDBEntry[] addSequenceAndChain(PDBEntry[] pdbe, SequenceI[][] seq,
 310           String[][] chns)
 311   {
 312     List<PDBEntry> v = new ArrayList<PDBEntry>();
 313     List<int[]> rtn = new ArrayList<int[]>();
 314     for (int i = 0; i < getPdbCount(); i++)
 315     {
 316       v.add(getPdbEntry(i));
 317     }
 318     for (int i = 0; i < pdbe.length; i++)
 319     {
 320       int r = v.indexOf(pdbe[i]);
 321       if (r == -1 || r >= getPdbCount())
 322       {
 323         rtn.add(new int[]
 324         { v.size(), i });
 325         v.add(pdbe[i]);
 326       }
 327       else
 328       {
 329         // just make sure the sequence/chain entries are all up to date
 330         addSequenceAndChain(r, seq[i], chns[i]);
 331       }
 332     }
 333     pdbe = v.toArray(new PDBEntry[v.size()]);
 334     setPdbentry(pdbe);
 335     if (rtn.size() > 0)
 336     {
 337       // expand the tied sequence[] and string[] arrays
 338       SequenceI[][] sqs = new SequenceI[getPdbCount()][];
 339       String[][] sch = new String[getPdbCount()][];
 340       System.arraycopy(getSequence(), 0, sqs, 0, getSequence().length);
 341       System.arraycopy(getChains(), 0, sch, 0, this.getChains().length);
 342       setSequence(sqs);
 343       setChains(sch);
 344       pdbe = new PDBEntry[rtn.size()];
 345       for (int r = 0; r < pdbe.length; r++)
 346       {
 347         int[] stri = (rtn.get(r));
 348         // record the pdb file as a new addition
 349         pdbe[r] = getPdbEntry(stri[0]);
 350         // and add the new sequence/chain entries
 351         addSequenceAndChain(stri[0], seq[stri[1]], chns[stri[1]]);
 352       }
 353     }
 354     else
 355     {
 356       pdbe = null;
 357     }
 358     return pdbe;
 359   }
 360
 361   /**
 362    * Add sequences to the pe'th pdbentry's sequence set.
 363    *
 364    * @param pe
 365    * @param seq
 366    */
 367   public void addSequence(int pe, SequenceI[] seq)
 368   {
 369     addSequenceAndChain(pe, seq, null);
 370   }
 371
 372   /**
 373    * add the given sequences to the mapping scope for the given pdb file handle
 374    *
 375    * @param pdbFile
 376    *          - pdbFile identifier
 377    * @param seq
 378    *          - set of sequences it can be mapped to
 379    */
 380   public void addSequenceForStructFile(String pdbFile, SequenceI[] seq)
 381   {
 382     for (int pe = 0; pe < getPdbCount(); pe++)
 383     {
 384       if (getPdbEntry(pe).getFile().equals(pdbFile))
 385       {
 386         addSequence(pe, seq);
 387       }
 388     }
 389   }
 390
 391   /**
 392    * Returns a readable description of all mappings for the wrapped pdbfile to
 393    * any mapped sequences
 394    *
 395    * @param pdbfile
 396    * @param seqs
 397    * @return
 398    */
 399   public String printMappings()
 400   {
 401     if (pdbEntry == null)
 402     {
 403       return "";
 404     }
 405     StringBuilder sb = new StringBuilder(128);
 406     for (int pdbe = 0; pdbe < getPdbCount(); pdbe++)
 407     {
 408       String pdbfile = getPdbEntry(pdbe).getFile();
 409       List<SequenceI> seqs = Arrays.asList(getSequence()[pdbe]);
 410       sb.append(getSsm().printMappings(pdbfile, seqs));
 411     }
 412     return sb.toString();
 413   }
 414
 415   @Override
 416   public void highlightAtoms(List<AtomSpec> atoms)
 417   {
 418     if (atoms != null)
 419     {
 420       for (AtomSpec atom : atoms)
 421       {
 422         highlightAtom(atom.getAtomIndex(), atom.getPdbResNum(),
 423                 atom.getChain(), atom.getPdbFile());
 424       }
 425     }
 426   }
 427
 428   protected abstract void highlightAtom(int atomIndex, int pdbResNum,
 429           String chain, String pdbFile);
 430
 431   protected boolean isNucleotide()
 432   {
 433     return this.nucleotide;
 434   }
 435 }