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 java.util.Locale;
  24
  25 import java.awt.Color;
  26 import java.util.ArrayList;
  27 import java.util.Arrays;
  28 import java.util.List;
  29 import java.util.Map;
  30
  31 import jalview.structure.AtomSpecModel;
  32 import jalview.structure.StructureCommand;
  33 import jalview.structure.StructureCommandI;
  34 import jalview.structure.StructureCommandsBase;
  35 import jalview.util.ColorUtils;
  36
  37 /**
  38  * Routines for generating Chimera commands for Jalview/Chimera binding
  39  *
  40  * @author JimP
  41  *
  42  */
  43 public class ChimeraCommands extends StructureCommandsBase
  44 {
  45   // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/focus.html
  46   private static final StructureCommand FOCUS_VIEW = new StructureCommand("focus");
  47
  48   // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/listen.html#listresattr
  49   private static final StructureCommand LIST_RESIDUE_ATTRIBUTES = new StructureCommand("list resattr");
  50
  51   // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/stop.html
  52   private static final StructureCommand CLOSE_CHIMERA = new StructureCommand("stop really");
  53
  54   // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/listen.html
  55   private static final StructureCommand STOP_NOTIFY_SELECTION = new StructureCommand("listen stop selection");
  56
  57   private static final StructureCommand STOP_NOTIFY_MODELS = new StructureCommand("listen stop models");
  58
  59   // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/listen.html#listselection
  60   private static final StructureCommand GET_SELECTION = new StructureCommand("list selection level residue");
  61
  62   private static final StructureCommand SHOW_BACKBONE = new StructureCommand(
  63           "~display all;~ribbon;chain @CA|P");
  64
  65   private static final StructureCommandI COLOUR_BY_CHARGE = new StructureCommand(
  66           "color white;color red ::ASP,GLU;color blue ::LYS,ARG;color yellow ::CYS");
  67
  68   // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/rainbow.html
  69   private static final StructureCommandI COLOUR_BY_CHAIN = new StructureCommand(
  70           "rainbow chain");
  71
  72   // Chimera clause to exclude alternate locations in atom selection
  73   private static final String NO_ALTLOCS = "&~@.B-Z&~@.2-9";
  74
  75   @Override
  76   public StructureCommandI colourResidues(String atomSpec, Color colour)
  77   {
  78     // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/color.html
  79     String colourCode = getColourString(colour);
  80     return new StructureCommand("color " + colourCode + " " + atomSpec);
  81   }
  82
  83   /**
  84    * Returns a colour formatted suitable for use in viewer command syntax
  85    *
  86    * @param colour
  87    * @return
  88    */
  89   protected String getColourString(Color colour)
  90   {
  91     return ColorUtils.toTkCode(colour);
  92   }
  93
  94   /**
  95    * Traverse the map of features/values/models/chains/positions to construct a
  96    * list of 'setattr' commands (one per distinct feature type and value).
  97    * <p>
  98    * The format of each command is
  99    *
 100    * <pre>
 101    * <blockquote> setattr r <featureName> " " #modelnumber:range.chain
 102    * e.g. setattr r jv_chain &lt;value&gt; #0:2.B,4.B,9-12.B|#1:1.A,2-6.A,...
 103    * </blockquote>
 104    * </pre>
 105    *
 106    * @param featureMap
 107    * @return
 108    */
 109   @Override
 110   public List<StructureCommandI> setAttributes(
 111           Map<String, Map<Object, AtomSpecModel>> featureMap)
 112   {
 113     List<StructureCommandI> commands = new ArrayList<>();
 114     for (String featureType : featureMap.keySet())
 115     {
 116       String attributeName = makeAttributeName(featureType);
 117
 118       /*
 119        * clear down existing attributes for this feature
 120        */
 121       // 'problem' - sets attribute to None on all residues - overkill?
 122       // commands.add("~setattr r " + attributeName + " :*");
 123
 124       Map<Object, AtomSpecModel> values = featureMap.get(featureType);
 125       for (Object value : values.keySet())
 126       {
 127         /*
 128          * for each distinct value recorded for this feature type,
 129          * add a command to set the attribute on the mapped residues
 130          * Put values in single quotes, encoding any embedded single quotes
 131          */
 132         AtomSpecModel atomSpecModel = values.get(value);
 133         String featureValue = value.toString();
 134         featureValue = featureValue.replaceAll("\\'", "&#39;");
 135         StructureCommandI cmd = setAttribute(attributeName, featureValue,
 136                 atomSpecModel);
 137         commands.add(cmd);
 138       }
 139     }
 140
 141     return commands;
 142   }
 143
 144   /**
 145    * Returns a viewer command to set the given residue attribute value on
 146    * residues specified by the AtomSpecModel, for example
 147    *
 148    * <pre>
 149    * setatr res jv_chain 'primary' #1:12-34,48-55.B
 150    * </pre>
 151    *
 152    * @param attributeName
 153    * @param attributeValue
 154    * @param atomSpecModel
 155    * @return
 156    */
 157   protected StructureCommandI setAttribute(String attributeName,
 158           String attributeValue,
 159           AtomSpecModel atomSpecModel)
 160   {
 161     StringBuilder sb = new StringBuilder(128);
 162     sb.append("setattr res ").append(attributeName).append(" '")
 163             .append(attributeValue).append("' ");
 164     sb.append(getAtomSpec(atomSpecModel, false));
 165     return new StructureCommand(sb.toString());
 166   }
 167
 168   /**
 169    * Makes a prefixed and valid Chimera attribute name. A jv_ prefix is applied
 170    * for a 'Jalview' namespace, and any non-alphanumeric character is converted
 171    * to an underscore.
 172    *
 173    * @param featureType
 174    * @return
 175    * @see https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/setattr.html
 176    */
 177   @Override
 178   protected String makeAttributeName(String featureType)
 179   {
 180     String attName = super.makeAttributeName(featureType);
 181
 182     /*
 183      * Chimera treats an attribute name ending in 'color' as colour-valued;
 184      * Jalview doesn't, so prevent this by appending an underscore
 185      */
 186     if (attName.toUpperCase(Locale.ROOT).endsWith("COLOR"))
 187     {
 188       attName += "_";
 189     }
 190
 191     return attName;
 192   }
 193
 194   @Override
 195   public StructureCommandI colourByChain()
 196   {
 197     return COLOUR_BY_CHAIN;
 198   }
 199
 200   @Override
 201   public List<StructureCommandI> colourByCharge()
 202   {
 203     return Arrays.asList(COLOUR_BY_CHARGE);
 204   }
 205
 206   @Override
 207   public String getResidueSpec(String residue)
 208   {
 209     return "::" + residue;
 210   }
 211
 212   @Override
 213   public StructureCommandI setBackgroundColour(Color col)
 214   {
 215     // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/set.html#bgcolor
 216     return new StructureCommand("set bgColor " + ColorUtils.toTkCode(col));
 217   }
 218
 219   @Override
 220   public StructureCommandI focusView()
 221   {
 222     return FOCUS_VIEW;
 223   }
 224
 225   @Override
 226   public List<StructureCommandI> showChains(List<String> toShow)
 227   {
 228     /*
 229      * Construct a chimera command like
 230      *
 231      * ~display #*;~ribbon #*;ribbon :.A,:.B
 232      */
 233     StringBuilder cmd = new StringBuilder(64);
 234     boolean first = true;
 235     for (String chain : toShow)
 236     {
 237       String[] tokens = chain.split(":");
 238       if (tokens.length == 2)
 239       {
 240         String showChainCmd = tokens[0] + ":." + tokens[1];
 241         if (!first)
 242         {
 243           cmd.append(",");
 244         }
 245         cmd.append(showChainCmd);
 246         first = false;
 247       }
 248     }
 249
 250     /*
 251      * could append ";focus" to this command to resize the display to fill the
 252      * window, but it looks more helpful not to (easier to relate chains to the
 253      * whole)
 254      */
 255     final String command = "~display #*; ~ribbon #*; ribbon :"
 256             + cmd.toString();
 257     return Arrays.asList(new StructureCommand(command));
 258   }
 259
 260   @Override
 261   public List<StructureCommandI> superposeStructures(AtomSpecModel ref,
 262           AtomSpecModel spec)
 263   {
 264     /*
 265      * Form Chimera match command to match spec to ref
 266      * (the first set of atoms are moved on to the second)
 267      *
 268      * match #1:1-30.B,81-100.B@CA #0:21-40.A,61-90.A@CA
 269      *
 270      * @see https://www.cgl.ucsf.edu/chimera/docs/UsersGuide/midas/match.html
 271      */
 272     StringBuilder cmd = new StringBuilder();
 273     String atomSpecAlphaOnly = getAtomSpec(spec, true);
 274     String refSpecAlphaOnly = getAtomSpec(ref, true);
 275     cmd.append("match ").append(atomSpecAlphaOnly).append(" ").append(refSpecAlphaOnly);
 276
 277     /*
 278      * show superposed residues as ribbon
 279      */
 280     String atomSpec = getAtomSpec(spec, false);
 281     String refSpec = getAtomSpec(ref, false);
 282     cmd.append("; ribbon ");
 283     cmd.append(atomSpec).append("|").append(refSpec).append("; focus");
 284
 285     return Arrays.asList(new StructureCommand(cmd.toString()));
 286   }
 287
 288   @Override
 289   public StructureCommandI openCommandFile(String path)
 290   {
 291     // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/filetypes.html
 292     return new StructureCommand("open cmd:" + path);
 293   }
 294
 295   @Override
 296   public StructureCommandI saveSession(String filepath)
 297   {
 298     // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/save.html
 299     return new StructureCommand("save " + filepath);
 300   }
 301
 302   /**
 303    * Returns the range(s) modelled by {@code atomSpec} formatted as a Chimera
 304    * atomspec string, e.g.
 305    *
 306    * <pre>
 307    * #0:15.A,28.A,54.A,70-72.A|#1:2.A,6.A,11.A,13-14.A
 308    * </pre>
 309    *
 310    * where
 311    * <ul>
 312    * <li>#0 is a model number</li>
 313    * <li>15 or 70-72 is a residue number, or range of residue numbers</li>
 314    * <li>.A is a chain identifier</li>
 315    * <li>residue ranges are separated by comma</li>
 316    * <li>atomspecs for distinct models are separated by | (or)</li>
 317    * </ul>
 318    *
 319    * <pre>
 320    *
 321    * @param model
 322    * @param alphaOnly
 323    * @return
 324    * @see https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/frameatom_spec.html
 325    */
 326   @Override
 327   public String getAtomSpec(AtomSpecModel atomSpec, boolean alphaOnly)
 328   {
 329     StringBuilder sb = new StringBuilder(128);
 330     boolean firstModel = true;
 331     for (String model : atomSpec.getModels())
 332     {
 333       if (!firstModel)
 334       {
 335         sb.append("|");
 336       }
 337       firstModel = false;
 338       appendModel(sb, model, atomSpec, alphaOnly);
 339     }
 340     return sb.toString();
 341   }
 342
 343   /**
 344    * A helper method to append an atomSpec string for atoms in the given model
 345    *
 346    * @param sb
 347    * @param model
 348    * @param atomSpec
 349    * @param alphaOnly
 350    */
 351   protected void appendModel(StringBuilder sb, String model,
 352           AtomSpecModel atomSpec, boolean alphaOnly)
 353   {
 354     sb.append("#").append(model).append(":");
 355
 356     boolean firstPositionForModel = true;
 357
 358     for (String chain : atomSpec.getChains(model))
 359     {
 360       chain = " ".equals(chain) ? chain : chain.trim();
 361
 362       List<int[]> rangeList = atomSpec.getRanges(model, chain);
 363       for (int[] range : rangeList)
 364       {
 365         appendRange(sb, range[0], range[1], chain, firstPositionForModel,
 366                 false);
 367         firstPositionForModel = false;
 368       }
 369     }
 370     if (alphaOnly)
 371     {
 372       /*
 373        * restrict to alpha carbon, no alternative locations
 374        * (needed to ensuring matching atom counts for superposition)
 375        */
 376       // TODO @P instead if RNA - add nucleotide flag to AtomSpecModel?
 377       sb.append("@CA").append(NO_ALTLOCS);
 378     }
 379   }
 380
 381   @Override
 382   public List<StructureCommandI> showBackbone()
 383   {
 384     return Arrays.asList(SHOW_BACKBONE);
 385   }
 386
 387   @Override
 388   public StructureCommandI loadFile(String file)
 389   {
 390     return new StructureCommand("open " + file);
 391   }
 392
 393   @Override
 394   public StructureCommandI openSession(String filepath)
 395   {
 396     // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/filetypes.html
 397     // this version of the command has no dependency on file extension
 398     return new StructureCommand("open chimera:" + filepath);
 399   }
 400
 401   @Override
 402   public StructureCommandI closeViewer()
 403   {
 404     return CLOSE_CHIMERA;
 405   }
 406
 407   @Override
 408   public List<StructureCommandI> startNotifications(String uri)
 409   {
 410     // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/listen.html
 411     List<StructureCommandI> cmds = new ArrayList<>();
 412     cmds.add(new StructureCommand("listen start models url " + uri));
 413     cmds.add(new StructureCommand("listen start select prefix SelectionChanged url " + uri));
 414     return cmds;
 415   }
 416
 417   @Override
 418   public List<StructureCommandI> stopNotifications()
 419   {
 420     List<StructureCommandI> cmds = new ArrayList<>();
 421     cmds.add(STOP_NOTIFY_MODELS);
 422     cmds.add(STOP_NOTIFY_SELECTION);
 423     return cmds;
 424   }
 425
 426   @Override
 427   public StructureCommandI getSelectedResidues()
 428   {
 429     return GET_SELECTION;
 430   }
 431
 432   @Override
 433   public StructureCommandI listResidueAttributes()
 434   {
 435     return LIST_RESIDUE_ATTRIBUTES;
 436   }
 437
 438   @Override
 439   public StructureCommandI getResidueAttributes(String attName)
 440   {
 441     // this alternative command
 442     // list residues spec ':*/attName' attr attName
 443     // doesn't report 'None' values (which is good), but
 444     // fails for 'average.bfactor' (which is bad):
 445     return new StructureCommand("list residues attr '" + attName + "'");
 446   }
 447
 448 }