src/jalview/ext/rbvi/chimera/ChimeraCommands.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.ext.rbvi.chimera;
  22
  23 import jalview.api.FeatureRenderer;
  24 import jalview.api.SequenceRenderer;
  25 import jalview.datamodel.AlignmentI;
  26 import jalview.datamodel.SequenceI;
  27 import jalview.structure.StructureMapping;
  28 import jalview.structure.StructureMappingcommandSet;
  29 import jalview.structure.StructureSelectionManager;
  30 import jalview.util.ColorUtils;
  31 import jalview.util.Comparison;
  32
  33 import java.awt.Color;
  34 import java.util.ArrayList;
  35 import java.util.LinkedHashMap;
  36 import java.util.List;
  37 import java.util.Map;
  38 import java.util.TreeMap;
  39
  40 /**
  41  * Routines for generating Chimera commands for Jalview/Chimera binding
  42  *
  43  * @author JimP
  44  *
  45  */
  46 public class ChimeraCommands
  47 {
  48
  49   /**
  50    * utility to construct the commands to colour chains by the given alignment
  51    * for passing to Chimera
  52    *
  53    * @returns Object[] { Object[] { <model being coloured>,
  54    *
  55    */
  56   public static StructureMappingcommandSet[] getColourBySequenceCommand(
  57           StructureSelectionManager ssm, String[] files,
  58           SequenceI[][] sequence, SequenceRenderer sr, FeatureRenderer fr,
  59           AlignmentI alignment)
  60   {
  61     Map<Color, Map<Integer, Map<String, List<int[]>>>> colourMap = buildColoursMap(
  62             ssm, files, sequence, sr, fr, alignment);
  63
  64     List<String> colourCommands = buildColourCommands(colourMap);
  65
  66     StructureMappingcommandSet cs = new StructureMappingcommandSet(
  67             ChimeraCommands.class, null,
  68             colourCommands.toArray(new String[0]));
  69
  70     return new StructureMappingcommandSet[] { cs };
  71   }
  72
  73   /**
  74    * Traverse the map of colours/models/chains/positions to construct a list of
  75    * 'color' commands (one per distinct colour used). The format of each command
  76    * is
  77    *
  78    * <blockquote> color colorname #modelnumber:range.chain e.g. color #00ff00
  79    * #0:2.B,4.B,9-12.B|#1:1.A,2-6.A,...
  80    *
  81    * @see http
  82    *      ://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/frameatom_spec
  83    *      .html </pre>
  84    *
  85    * @param colourMap
  86    * @return
  87    */
  88   protected static List<String> buildColourCommands(
  89           Map<Color, Map<Integer, Map<String, List<int[]>>>> colourMap)
  90   {
  91     /*
  92      * This version concatenates all commands into a single String (semi-colon
  93      * delimited). If length limit issues arise, refactor to return one color
  94      * command per colour.
  95      */
  96     List<String> commands = new ArrayList<String>();
  97     StringBuilder sb = new StringBuilder(256);
  98     boolean firstColour = true;
  99     for (Color colour : colourMap.keySet())
 100     {
 101       String colourCode = ColorUtils.toTkCode(colour);
 102       if (!firstColour)
 103       {
 104         sb.append("; ");
 105       }
 106       sb.append("color ").append(colourCode).append(" ");
 107       firstColour = false;
 108       boolean firstModelForColour = true;
 109       final Map<Integer, Map<String, List<int[]>>> colourData = colourMap
 110               .get(colour);
 111       for (Integer model : colourData.keySet())
 112       {
 113         boolean firstPositionForModel = true;
 114         if (!firstModelForColour)
 115         {
 116           sb.append("|");
 117         }
 118         firstModelForColour = false;
 119         sb.append("#").append(model).append(":");
 120
 121         final Map<String, List<int[]>> modelData = colourData.get(model);
 122         for (String chain : modelData.keySet())
 123         {
 124           boolean hasChain = !"".equals(chain.trim());
 125           for (int[] range : modelData.get(chain))
 126           {
 127             if (!firstPositionForModel)
 128             {
 129               sb.append(",");
 130             }
 131             if (range[0] == range[1])
 132             {
 133               sb.append(range[0]);
 134             }
 135             else
 136             {
 137               sb.append(range[0]).append("-").append(range[1]);
 138             }
 139             if (hasChain)
 140             {
 141               sb.append(".").append(chain);
 142             }
 143             firstPositionForModel = false;
 144           }
 145         }
 146       }
 147     }
 148     commands.add(sb.toString());
 149     return commands;
 150   }
 151
 152   /**
 153    * <pre>
 154    * Build a data structure which maps contiguous subsequences for each colour.
 155    * This generates a data structure from which we can easily generate the
 156    * Chimera command for colour by sequence.
 157    * Color
 158    *     Model number
 159    *         Chain
 160    *             list of start/end ranges
 161    * Ordering is by order of addition (for colours and positions), natural ordering (for models and chains)
 162    * </pre>
 163    */
 164   protected static Map<Color, Map<Integer, Map<String, List<int[]>>>> buildColoursMap(
 165           StructureSelectionManager ssm, String[] files,
 166           SequenceI[][] sequence, SequenceRenderer sr, FeatureRenderer fr,
 167           AlignmentI alignment)
 168   {
 169     Map<Color, Map<Integer, Map<String, List<int[]>>>> colourMap = new LinkedHashMap<Color, Map<Integer, Map<String, List<int[]>>>>();
 170     Color lastColour = null;
 171     for (int pdbfnum = 0; pdbfnum < files.length; pdbfnum++)
 172     {
 173       StructureMapping[] mapping = ssm.getMapping(files[pdbfnum]);
 174
 175       if (mapping == null || mapping.length < 1)
 176       {
 177         continue;
 178       }
 179
 180       int startPos = -1, lastPos = -1;
 181       String lastChain = "";
 182       for (int s = 0; s < sequence[pdbfnum].length; s++)
 183       {
 184         for (int sp, m = 0; m < mapping.length; m++)
 185         {
 186           final SequenceI seq = sequence[pdbfnum][s];
 187           if (mapping[m].getSequence() == seq
 188                   && (sp = alignment.findIndex(seq)) > -1)
 189           {
 190             SequenceI asp = alignment.getSequenceAt(sp);
 191             for (int r = 0; r < asp.getLength(); r++)
 192             {
 193               // no mapping to gaps in sequence
 194               if (Comparison.isGap(asp.getCharAt(r)))
 195               {
 196                 continue;
 197               }
 198               int pos = mapping[m].getPDBResNum(asp.findPosition(r));
 199
 200               if (pos < 1 || pos == lastPos)
 201               {
 202                 continue;
 203               }
 204
 205               Color colour = sr.getResidueColour(seq, r, fr);
 206               final String chain = mapping[m].getChain();
 207
 208               /*
 209                * Just keep incrementing the end position for this colour range
 210                * _unless_ colour, PDB model or chain has changed, or there is a
 211                * gap in the mapped residue sequence
 212                */
 213               final boolean newColour = !colour.equals(lastColour);
 214               final boolean nonContig = lastPos + 1 != pos;
 215               final boolean newChain = !chain.equals(lastChain);
 216               if (newColour || nonContig || newChain)
 217               {
 218                 if (startPos != -1)
 219                 {
 220                   addColourRange(colourMap, lastColour, pdbfnum, startPos,
 221                           lastPos, lastChain);
 222                 }
 223                 startPos = pos;
 224               }
 225               lastColour = colour;
 226               lastPos = pos;
 227               lastChain = chain;
 228             }
 229             // final colour range
 230             if (lastColour != null)
 231             {
 232               addColourRange(colourMap, lastColour, pdbfnum, startPos,
 233                       lastPos, lastChain);
 234             }
 235             break;
 236           }
 237         }
 238       }
 239     }
 240     return colourMap;
 241   }
 242
 243   /**
 244    * Helper method to add one contiguous colour range to the colour map.
 245    *
 246    * @param colourMap
 247    * @param colour
 248    * @param model
 249    * @param startPos
 250    * @param endPos
 251    * @param chain
 252    */
 253   protected static void addColourRange(
 254           Map<Color, Map<Integer, Map<String, List<int[]>>>> colourMap,
 255           Color colour, int model, int startPos, int endPos, String chain)
 256   {
 257     /*
 258      * Get/initialize map of data for the colour
 259      */
 260     Map<Integer, Map<String, List<int[]>>> colourData = colourMap
 261             .get(colour);
 262     if (colourData == null)
 263     {
 264       colourMap
 265               .put(colour,
 266                       colourData = new TreeMap<Integer, Map<String, List<int[]>>>());
 267     }
 268
 269     /*
 270      * Get/initialize map of data for the colour and model
 271      */
 272     Map<String, List<int[]>> modelData = colourData.get(model);
 273     if (modelData == null)
 274     {
 275       colourData.put(model, modelData = new TreeMap<String, List<int[]>>());
 276     }
 277
 278     /*
 279      * Get/initialize map of data for colour, model and chain
 280      */
 281     List<int[]> chainData = modelData.get(chain);
 282     if (chainData == null)
 283     {
 284       modelData.put(chain, chainData = new ArrayList<int[]>());
 285     }
 286
 287     /*
 288      * Add the start/end positions
 289      */
 290     chainData.add(new int[] { startPos, endPos });
 291   }
 292
 293 }