src/jalview/structures/models/AAStructureBindingModel.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.structures.models;
  22
  23 import jalview.api.AlignmentViewPanel;
  24 import jalview.api.SequenceRendererI;
  25 import jalview.api.StructureSelectionManagerProvider;
  26 import jalview.api.structures.JalviewStructureDisplayI;
  27 import jalview.datamodel.AlignmentI;
  28 import jalview.datamodel.HiddenColumns;
  29 import jalview.datamodel.PDBEntry;
  30 import jalview.datamodel.SequenceI;
  31 import jalview.gui.AlignmentPanel;
  32 import jalview.gui.SequenceRenderer;
  33 import jalview.io.DataSourceType;
  34 import jalview.schemes.ColourSchemeI;
  35 import jalview.structure.AtomSpec;
  36 import jalview.structure.StructureListener;
  37 import jalview.structure.StructureMapping;
  38 import jalview.structure.StructureMappingcommandSet;
  39 import jalview.structure.StructureSelectionManager;
  40 import jalview.util.Comparison;
  41 import jalview.util.MessageManager;
  42
  43 import java.awt.Color;
  44 import java.util.ArrayList;
  45 import java.util.Arrays;
  46 import java.util.BitSet;
  47 import java.util.List;
  48
  49 /**
  50  *
  51  * A base class to hold common function for protein structure model binding.
  52  * Initial version created by refactoring JMol and Chimera binding models, but
  53  * other structure viewers could in principle be accommodated in future.
  54  *
  55  * @author gmcarstairs
  56  *
  57  */
  58 public abstract class AAStructureBindingModel
  59         extends SequenceStructureBindingModel
  60         implements StructureListener, StructureSelectionManagerProvider
  61 {
  62   public enum ColourBy
  63   {
  64     Sequence, Chain, ChargeAndCysteine, Jalview, Viewer
  65   }
  66
  67   /*
  68    * selected colour menu option
  69    */
  70   private ColourBy colourBy = ColourBy.Sequence;
  71
  72   /*
  73    * selected colour scheme, if a Jalview colour scheme is selected
  74    */
  75   private ColourSchemeI colourScheme;
  76
  77   private StructureSelectionManager ssm;
  78
  79   /*
  80    * distinct PDB entries (pdb files) associated
  81    * with sequences
  82    */
  83   private PDBEntry[] pdbEntry;
  84
  85   /*
  86    * sequences mapped to each pdbentry
  87    */
  88   private SequenceI[][] sequence;
  89
  90   /*
  91    * array of target chains for sequences - tied to pdbentry and sequence[]
  92    */
  93   private String[][] chains;
  94
  95   /*
  96    * datasource protocol for access to PDBEntrylatest
  97    */
  98   DataSourceType protocol = null;
  99
 100   private boolean nucleotide;
 101
 102   private boolean finishedInit = false;
 103
 104   /**
 105    * current set of model filenames loaded in the Jmol instance
 106    */
 107   protected String[] modelFileNames = null;
 108
 109   public String fileLoadingError;
 110
 111   /**
 112    * Data bean class to simplify parameterisation in superposeStructures
 113    */
 114   protected class SuperposeData
 115   {
 116     /**
 117      * Constructor with alignment width argument
 118      *
 119      * @param width
 120      */
 121     public SuperposeData(int width)
 122     {
 123       pdbResNo = new int[width];
 124     }
 125
 126     public String filename;
 127
 128     public String pdbId;
 129
 130     public String chain = "";
 131
 132     public boolean isRna;
 133
 134     /*
 135      * The pdb residue number (if any) mapped to each column of the alignment
 136      */
 137     public int[] pdbResNo;
 138   }
 139
 140   /**
 141    * Constructor
 142    *
 143    * @param ssm
 144    * @param seqs
 145    */
 146   public AAStructureBindingModel(StructureSelectionManager ssm,
 147           SequenceI[][] seqs)
 148   {
 149     this.ssm = ssm;
 150     this.sequence = seqs;
 151   }
 152
 153   /**
 154    * Constructor
 155    *
 156    * @param ssm
 157    * @param pdbentry
 158    * @param sequenceIs
 159    * @param protocol
 160    */
 161   public AAStructureBindingModel(StructureSelectionManager ssm,
 162           PDBEntry[] pdbentry, SequenceI[][] sequenceIs,
 163           DataSourceType protocol)
 164   {
 165     this.ssm = ssm;
 166     this.sequence = sequenceIs;
 167     this.nucleotide = Comparison.isNucleotide(sequenceIs);
 168     this.pdbEntry = pdbentry;
 169     this.protocol = protocol;
 170     resolveChains();
 171   }
 172
 173   private boolean resolveChains()
 174   {
 175     /**
 176      * final count of chain mappings discovered
 177      */
 178     int chainmaps = 0;
 179     // JBPNote: JAL-2693 - this should be a list of chain mappings per
 180     // [pdbentry][sequence]
 181     String[][] newchains = new String[pdbEntry.length][];
 182     int pe = 0;
 183     for (PDBEntry pdb : pdbEntry)
 184     {
 185       SequenceI[] seqsForPdb = sequence[pe];
 186       if (seqsForPdb != null)
 187       {
 188         newchains[pe] = new String[seqsForPdb.length];
 189         int se = 0;
 190         for (SequenceI asq : seqsForPdb)
 191         {
 192           String chain = (chains != null && chains[pe] != null)
 193                   ? chains[pe][se]
 194                   : null;
 195           SequenceI sq = (asq.getDatasetSequence() == null) ? asq
 196                   : asq.getDatasetSequence();
 197           if (sq.getAllPDBEntries() != null)
 198           {
 199             for (PDBEntry pdbentry : sq.getAllPDBEntries())
 200             {
 201               if (pdb.getFile() != null && pdbentry.getFile() != null
 202                       && pdb.getFile().equals(pdbentry.getFile()))
 203               {
 204                 String chaincode = pdbentry.getChainCode();
 205                 if (chaincode != null && chaincode.length() > 0)
 206                 {
 207                   chain = chaincode;
 208                   chainmaps++;
 209                   break;
 210                 }
 211               }
 212             }
 213           }
 214           newchains[pe][se] = chain;
 215           se++;
 216         }
 217         pe++;
 218       }
 219     }
 220
 221     chains = newchains;
 222     return chainmaps > 0;
 223   }
 224   public StructureSelectionManager getSsm()
 225   {
 226     return ssm;
 227   }
 228
 229   /**
 230    * Returns the i'th PDBEntry (or null)
 231    *
 232    * @param i
 233    * @return
 234    */
 235   public PDBEntry getPdbEntry(int i)
 236   {
 237     return (pdbEntry != null && pdbEntry.length > i) ? pdbEntry[i] : null;
 238   }
 239
 240   /**
 241    * Answers true if this binding includes the given PDB id, else false
 242    *
 243    * @param pdbId
 244    * @return
 245    */
 246   public boolean hasPdbId(String pdbId)
 247   {
 248     if (pdbEntry != null)
 249     {
 250       for (PDBEntry pdb : pdbEntry)
 251       {
 252         if (pdb.getId().equals(pdbId))
 253         {
 254           return true;
 255         }
 256       }
 257     }
 258     return false;
 259   }
 260
 261   /**
 262    * Returns the number of modelled PDB file entries.
 263    *
 264    * @return
 265    */
 266   public int getPdbCount()
 267   {
 268     return pdbEntry == null ? 0 : pdbEntry.length;
 269   }
 270
 271   public SequenceI[][] getSequence()
 272   {
 273     return sequence;
 274   }
 275
 276   public String[][] getChains()
 277   {
 278     return chains;
 279   }
 280
 281   public DataSourceType getProtocol()
 282   {
 283     return protocol;
 284   }
 285
 286   // TODO may remove this if calling methods can be pulled up here
 287   protected void setPdbentry(PDBEntry[] pdbentry)
 288   {
 289     this.pdbEntry = pdbentry;
 290   }
 291
 292   protected void setSequence(SequenceI[][] sequence)
 293   {
 294     this.sequence = sequence;
 295   }
 296
 297   protected void setChains(String[][] chains)
 298   {
 299     this.chains = chains;
 300   }
 301
 302   /**
 303    * Construct a title string for the viewer window based on the data Jalview
 304    * knows about
 305    *
 306    * @param viewerName
 307    *          TODO
 308    * @param verbose
 309    *
 310    * @return
 311    */
 312   public String getViewerTitle(String viewerName, boolean verbose)
 313   {
 314     if (getSequence() == null || getSequence().length < 1
 315             || getPdbCount() < 1 || getSequence()[0].length < 1)
 316     {
 317       return ("Jalview " + viewerName + " Window");
 318     }
 319     // TODO: give a more informative title when multiple structures are
 320     // displayed.
 321     StringBuilder title = new StringBuilder(64);
 322     final PDBEntry pdbe = getPdbEntry(0);
 323     title.append(viewerName + " view for " + getSequence()[0][0].getName()
 324             + ":" + pdbe.getId());
 325
 326     if (verbose)
 327     {
 328       String method = (String) pdbe.getProperty("method");
 329       if (method != null)
 330       {
 331         title.append(" Method: ").append(method);
 332       }
 333       String chain = (String) pdbe.getProperty("chains");
 334       if (chain != null)
 335       {
 336         title.append(" Chain:").append(chain);
 337       }
 338     }
 339     return title.toString();
 340   }
 341
 342   /**
 343    * Called by after closeViewer is called, to release any resources and
 344    * references so they can be garbage collected. Override if needed.
 345    */
 346   protected void releaseUIResources()
 347   {
 348
 349   }
 350
 351   public void setColourBy(ColourBy option)
 352   {
 353         colourBy = option;
 354   }
 355
 356   public boolean isColourBySequence()
 357   {
 358     return colourBy == ColourBy.Sequence;
 359   }
 360
 361   protected boolean isJalviewColourScheme()
 362   {
 363         return colourBy == ColourBy.Jalview;
 364   }
 365
 366   protected void addSequenceAndChain(int pe, SequenceI[] seq,
 367           String[] tchain)
 368   {
 369     if (pe < 0 || pe >= getPdbCount())
 370     {
 371       throw new Error(MessageManager.formatMessage(
 372               "error.implementation_error_no_pdbentry_from_index",
 373               new Object[]
 374               { Integer.valueOf(pe).toString() }));
 375     }
 376     final String nullChain = "TheNullChain";
 377     List<SequenceI> s = new ArrayList<SequenceI>();
 378     List<String> c = new ArrayList<String>();
 379     if (getChains() == null)
 380     {
 381       setChains(new String[getPdbCount()][]);
 382     }
 383     if (getSequence()[pe] != null)
 384     {
 385       for (int i = 0; i < getSequence()[pe].length; i++)
 386       {
 387         s.add(getSequence()[pe][i]);
 388         if (getChains()[pe] != null)
 389         {
 390           if (i < getChains()[pe].length)
 391           {
 392             c.add(getChains()[pe][i]);
 393           }
 394           else
 395           {
 396             c.add(nullChain);
 397           }
 398         }
 399         else
 400         {
 401           if (tchain != null && tchain.length > 0)
 402           {
 403             c.add(nullChain);
 404           }
 405         }
 406       }
 407     }
 408     for (int i = 0; i < seq.length; i++)
 409     {
 410       if (!s.contains(seq[i]))
 411       {
 412         s.add(seq[i]);
 413         if (tchain != null && i < tchain.length)
 414         {
 415           c.add(tchain[i] == null ? nullChain : tchain[i]);
 416         }
 417       }
 418     }
 419     SequenceI[] tmp = s.toArray(new SequenceI[s.size()]);
 420     getSequence()[pe] = tmp;
 421     if (c.size() > 0)
 422     {
 423       String[] tch = c.toArray(new String[c.size()]);
 424       for (int i = 0; i < tch.length; i++)
 425       {
 426         if (tch[i] == nullChain)
 427         {
 428           tch[i] = null;
 429         }
 430       }
 431       getChains()[pe] = tch;
 432     }
 433     else
 434     {
 435       getChains()[pe] = null;
 436     }
 437   }
 438
 439   /**
 440    * add structures and any known sequence associations
 441    *
 442    * @returns the pdb entries added to the current set.
 443    */
 444   public synchronized PDBEntry[] addSequenceAndChain(PDBEntry[] pdbe,
 445           SequenceI[][] seq, String[][] chns)
 446   {
 447     List<PDBEntry> v = new ArrayList<PDBEntry>();
 448     List<int[]> rtn = new ArrayList<int[]>();
 449     for (int i = 0; i < getPdbCount(); i++)
 450     {
 451       v.add(getPdbEntry(i));
 452     }
 453     for (int i = 0; i < pdbe.length; i++)
 454     {
 455       int r = v.indexOf(pdbe[i]);
 456       if (r == -1 || r >= getPdbCount())
 457       {
 458         rtn.add(new int[] { v.size(), i });
 459         v.add(pdbe[i]);
 460       }
 461       else
 462       {
 463         // just make sure the sequence/chain entries are all up to date
 464         addSequenceAndChain(r, seq[i], chns[i]);
 465       }
 466     }
 467     pdbe = v.toArray(new PDBEntry[v.size()]);
 468     setPdbentry(pdbe);
 469     if (rtn.size() > 0)
 470     {
 471       // expand the tied sequence[] and string[] arrays
 472       SequenceI[][] sqs = new SequenceI[getPdbCount()][];
 473       String[][] sch = new String[getPdbCount()][];
 474       System.arraycopy(getSequence(), 0, sqs, 0, getSequence().length);
 475       System.arraycopy(getChains(), 0, sch, 0, this.getChains().length);
 476       setSequence(sqs);
 477       setChains(sch);
 478       pdbe = new PDBEntry[rtn.size()];
 479       for (int r = 0; r < pdbe.length; r++)
 480       {
 481         int[] stri = (rtn.get(r));
 482         // record the pdb file as a new addition
 483         pdbe[r] = getPdbEntry(stri[0]);
 484         // and add the new sequence/chain entries
 485         addSequenceAndChain(stri[0], seq[stri[1]], chns[stri[1]]);
 486       }
 487     }
 488     else
 489     {
 490       pdbe = null;
 491     }
 492     return pdbe;
 493   }
 494
 495   /**
 496    * Add sequences to the pe'th pdbentry's sequence set.
 497    *
 498    * @param pe
 499    * @param seq
 500    */
 501   public void addSequence(int pe, SequenceI[] seq)
 502   {
 503     addSequenceAndChain(pe, seq, null);
 504   }
 505
 506   /**
 507    * add the given sequences to the mapping scope for the given pdb file handle
 508    *
 509    * @param pdbFile
 510    *          - pdbFile identifier
 511    * @param seq
 512    *          - set of sequences it can be mapped to
 513    */
 514   public void addSequenceForStructFile(String pdbFile, SequenceI[] seq)
 515   {
 516     for (int pe = 0; pe < getPdbCount(); pe++)
 517     {
 518       if (getPdbEntry(pe).getFile().equals(pdbFile))
 519       {
 520         addSequence(pe, seq);
 521       }
 522     }
 523   }
 524
 525   @Override
 526   public abstract void highlightAtoms(List<AtomSpec> atoms);
 527
 528   protected boolean isNucleotide()
 529   {
 530     return this.nucleotide;
 531   }
 532
 533   /**
 534    * Returns a readable description of all mappings for the wrapped pdbfile to
 535    * any mapped sequences
 536    *
 537    * @param pdbfile
 538    * @param seqs
 539    * @return
 540    */
 541   public String printMappings()
 542   {
 543     if (pdbEntry == null)
 544     {
 545       return "";
 546     }
 547     StringBuilder sb = new StringBuilder(128);
 548     for (int pdbe = 0; pdbe < getPdbCount(); pdbe++)
 549     {
 550       String pdbfile = getPdbEntry(pdbe).getFile();
 551       List<SequenceI> seqs = Arrays.asList(getSequence()[pdbe]);
 552       sb.append(getSsm().printMappings(pdbfile, seqs));
 553     }
 554     return sb.toString();
 555   }
 556
 557   /**
 558    * Returns the mapped structure position for a given aligned column of a given
 559    * sequence, or -1 if the column is gapped, beyond the end of the sequence, or
 560    * not mapped to structure.
 561    *
 562    * @param seq
 563    * @param alignedPos
 564    * @param mapping
 565    * @return
 566    */
 567   protected int getMappedPosition(SequenceI seq, int alignedPos,
 568           StructureMapping mapping)
 569   {
 570     if (alignedPos >= seq.getLength())
 571     {
 572       return -1;
 573     }
 574
 575     if (Comparison.isGap(seq.getCharAt(alignedPos)))
 576     {
 577       return -1;
 578     }
 579     int seqPos = seq.findPosition(alignedPos);
 580     int pos = mapping.getPDBResNum(seqPos);
 581     return pos;
 582   }
 583
 584   /**
 585    * Helper method to identify residues that can participate in a structure
 586    * superposition command. For each structure, identify a sequence in the
 587    * alignment which is mapped to the structure. Identify non-gapped columns in
 588    * the sequence which have a mapping to a residue in the structure. Returns
 589    * the index of the first structure that has a mapping to the alignment.
 590    *
 591    * @param alignment
 592    *          the sequence alignment which is the basis of structure
 593    *          superposition
 594    * @param matched
 595    *          a BitSet, where bit j is set to indicate that every structure has
 596    *          a mapped residue present in column j (so the column can
 597    *          participate in structure alignment)
 598    * @param structures
 599    *          an array of data beans corresponding to pdb file index
 600    * @return
 601    */
 602   protected int findSuperposableResidues(AlignmentI alignment,
 603           BitSet matched, SuperposeData[] structures)
 604   {
 605     int refStructure = -1;
 606     String[] files = getStructureFiles();
 607     if (files == null)
 608     {
 609       return -1;
 610     }
 611     for (int pdbfnum = 0; pdbfnum < files.length; pdbfnum++)
 612     {
 613       StructureMapping[] mappings = getSsm().getMapping(files[pdbfnum]);
 614       int lastPos = -1;
 615
 616       /*
 617        * Find the first mapped sequence (if any) for this PDB entry which is in
 618        * the alignment
 619        */
 620       final int seqCountForPdbFile = getSequence()[pdbfnum].length;
 621       for (int s = 0; s < seqCountForPdbFile; s++)
 622       {
 623         for (StructureMapping mapping : mappings)
 624         {
 625           final SequenceI theSequence = getSequence()[pdbfnum][s];
 626           if (mapping.getSequence() == theSequence
 627                   && alignment.findIndex(theSequence) > -1)
 628           {
 629             if (refStructure < 0)
 630             {
 631               refStructure = pdbfnum;
 632             }
 633             for (int r = 0; r < alignment.getWidth(); r++)
 634             {
 635               if (!matched.get(r))
 636               {
 637                 continue;
 638               }
 639               int pos = getMappedPosition(theSequence, r, mapping);
 640               if (pos < 1 || pos == lastPos)
 641               {
 642                 matched.clear(r);
 643                 continue;
 644               }
 645               lastPos = pos;
 646               structures[pdbfnum].pdbResNo[r] = pos;
 647             }
 648             String chain = mapping.getChain();
 649             if (chain != null && chain.trim().length() > 0)
 650             {
 651               structures[pdbfnum].chain = chain;
 652             }
 653             structures[pdbfnum].pdbId = mapping.getPdbId();
 654             structures[pdbfnum].isRna = theSequence.getRNA() != null;
 655
 656             /*
 657              * move on to next pdb file (ignore sequences for other chains
 658              * for the same structure)
 659              */
 660             s = seqCountForPdbFile;
 661             break;
 662           }
 663         }
 664       }
 665     }
 666     return refStructure;
 667   }
 668
 669   /**
 670    * Returns true if the structure viewer has loaded all of the files of
 671    * interest (identified by the file mapping having been set up), or false if
 672    * any are still not loaded after a timeout interval.
 673    *
 674    * @param files
 675    */
 676   protected boolean waitForFileLoad(String[] files)
 677   {
 678     /*
 679      * give up after 10 secs plus 1 sec per file
 680      */
 681     long starttime = System.currentTimeMillis();
 682     long endTime = 10000 + 1000 * files.length + starttime;
 683     String notLoaded = null;
 684
 685     boolean waiting = true;
 686     while (waiting && System.currentTimeMillis() < endTime)
 687     {
 688       waiting = false;
 689       for (String file : files)
 690       {
 691         notLoaded = file;
 692         if (file == null)
 693         {
 694           continue;
 695         }
 696         try
 697         {
 698           StructureMapping[] sm = getSsm().getMapping(file);
 699           if (sm == null || sm.length == 0)
 700           {
 701             waiting = true;
 702           }
 703         } catch (Throwable x)
 704         {
 705           waiting = true;
 706         }
 707       }
 708     }
 709
 710     if (waiting)
 711     {
 712       System.err.println(
 713               "Timed out waiting for structure viewer to load file "
 714                       + notLoaded);
 715       return false;
 716     }
 717     return true;
 718   }
 719
 720   @Override
 721   public boolean isListeningFor(SequenceI seq)
 722   {
 723     if (sequence != null)
 724     {
 725       for (SequenceI[] seqs : sequence)
 726       {
 727         if (seqs != null)
 728         {
 729           for (SequenceI s : seqs)
 730           {
 731             if (s == seq || (s.getDatasetSequence() != null
 732                     && s.getDatasetSequence() == seq.getDatasetSequence()))
 733             {
 734               return true;
 735             }
 736           }
 737         }
 738       }
 739     }
 740     return false;
 741   }
 742
 743   public boolean isFinishedInit()
 744   {
 745     return finishedInit;
 746   }
 747
 748   public void setFinishedInit(boolean fi)
 749   {
 750     this.finishedInit = fi;
 751   }
 752
 753   /**
 754    * Returns a list of chains mapped in this viewer.
 755    *
 756    * @return
 757    */
 758   public abstract List<String> getChainNames();
 759
 760   /**
 761    * Returns the Jalview panel hosting the structure viewer (if any)
 762    *
 763    * @return
 764    */
 765   public JalviewStructureDisplayI getViewer()
 766   {
 767     return null;
 768   }
 769
 770   /**
 771    * Sets the selected colour scheme, possibly with reference to the given
 772    * alignment view
 773    *
 774    * @param cs
 775    * @param ap
 776    */
 777   public void setJalviewColourScheme(ColourSchemeI cs, AlignmentViewPanel ap)
 778   {
 779     colourBy = ColourBy.Jalview;
 780     colourScheme = cs;
 781
 782     if (cs == null || cs.isSimple())
 783     {
 784       setSimpleColourScheme(cs);
 785     }
 786     else
 787     {
 788       colourBySequence(ap, new SequenceRenderer(ap.getAlignViewport(), cs));
 789     }
 790   }
 791
 792   /**
 793    * Sets a colour scheme which is determined solely by the residue at each
 794    * position
 795    *
 796    * @param cs
 797    */
 798   protected abstract void setSimpleColourScheme(ColourSchemeI cs);
 799
 800   /**
 801    * Constructs and sends a command to align structures against a reference
 802    * structure, based on one or more sequence alignments. May optionally return
 803    * an error or warning message for the alignment command.
 804    *
 805    * @param alignments
 806    *          an array of alignments to process
 807    * @param structureIndices
 808    *          an array of corresponding reference structures (index into pdb
 809    *          file array); if a negative value is passed, the first PDB file
 810    *          mapped to an alignment sequence is used as the reference for
 811    *          superposition
 812    * @param hiddenCols
 813    *          an array of corresponding hidden columns for each alignment
 814    * @return
 815    */
 816   public abstract String superposeStructures(AlignmentI[] alignments,
 817           int[] structureIndices, HiddenColumns[] hiddenCols);
 818
 819   public abstract void setBackgroundColour(Color col);
 820
 821   protected abstract StructureMappingcommandSet[] getColourBySequenceCommands(
 822           String[] files, SequenceRendererI sr, AlignmentViewPanel avp);
 823
 824   protected abstract void colourBySequence(
 825           StructureMappingcommandSet[] colourBySequenceCommands);
 826
 827   public void colourByChain()
 828   {
 829     colourBy = ColourBy.Chain;
 830   }
 831
 832   public void colourByCharge()
 833   {
 834         colourBy = ColourBy.ChargeAndCysteine;
 835   }
 836
 837   public void colourBySequence(AlignmentViewPanel alignmentv)
 838   {
 839         colourBySequence(alignmentv, alignmentv.getSequenceRenderer());
 840   }
 841
 842   /**
 843    * Colours any structures associated with sequences in the given alignment view
 844    * using the getFeatureRenderer() and getSequenceRenderer() renderers
 845    */
 846   public void colourBySequence(AlignmentViewPanel alignmentv, SequenceRendererI sr)
 847   {
 848     if (!isLoadingFinished())
 849     {
 850       return;
 851     }
 852     if (getSsm() == null)
 853     {
 854       return;
 855     }
 856     String[] files = getStructureFiles();
 857
 858     StructureMappingcommandSet[] colourBySequenceCommands = getColourBySequenceCommands(
 859             files, sr, alignmentv);
 860     colourBySequence(colourBySequenceCommands);
 861   }
 862
 863   public boolean hasFileLoadingError()
 864   {
 865     return fileLoadingError != null && fileLoadingError.length() > 0;
 866   }
 867
 868   public abstract jalview.api.FeatureRenderer getFeatureRenderer(
 869           AlignmentViewPanel alignment);
 870
 871 @Override
 872 public void updateColours(Object source) {
 873     AlignmentPanel ap = (AlignmentPanel) source;
 874
 875     /*
 876      * ignore events from panels not used to colour this view
 877      */
 878     if (!getViewer().isUsedForColourBy(ap))
 879     {
 880       return;
 881     }
 882
 883     /*
 884      * no need to update colours if structure colouring is not
 885      * viewport dependent
 886      */
 887     if (!isColourBySequence() && !isJalviewColourScheme())
 888     {
 889       return;
 890     }
 891     if (colourScheme == null || colourScheme.isSimple())
 892     {
 893       return;
 894     }
 895
 896     if (!isLoadingFromArchive())
 897     {
 898       if (isColourBySequence())
 899       {
 900             colourBySequence(ap, new SequenceRenderer(ap.getAlignViewport()));
 901       }
 902       else
 903       {
 904         colourBySequence(ap, new SequenceRenderer(ap.getAlignViewport(), colourScheme));
 905       }
 906     }
 907   }
 908 }