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