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