X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=src%2Fjalview%2Fext%2Frbvi%2Fchimera%2FChimeraCommands.java;h=d3dd6250a3e51a7c13383c13dee4954b2d6f109e;hb=57738a1f3c19b1c3a00bd3ac5108f8cd0af32f99;hp=3c47ed1a3e4befa31041491ddb95ea757e8ed454;hpb=81316c6cc11e29c893d55e87ebd16d9ecd09c1f3;p=jalview.git diff --git a/src/jalview/ext/rbvi/chimera/ChimeraCommands.java b/src/jalview/ext/rbvi/chimera/ChimeraCommands.java index 3c47ed1..d3dd625 100644 --- a/src/jalview/ext/rbvi/chimera/ChimeraCommands.java +++ b/src/jalview/ext/rbvi/chimera/ChimeraCommands.java @@ -1,6 +1,6 @@ /* - * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8.2) - * Copyright (C) 2014 The Jalview Authors + * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$) + * Copyright (C) $$Year-Rel$$ The Jalview Authors * * This file is part of Jalview. * @@ -20,296 +20,440 @@ */ package jalview.ext.rbvi.chimera; -import jalview.api.FeatureRenderer; -import jalview.api.SequenceRenderer; -import jalview.datamodel.AlignmentI; -import jalview.datamodel.SequenceI; -import jalview.structure.StructureMapping; -import jalview.structure.StructureMappingcommandSet; -import jalview.structure.StructureSelectionManager; -import jalview.util.Comparison; +import java.util.Locale; import java.awt.Color; -import java.io.File; -import java.io.FileOutputStream; -import java.io.IOException; import java.util.ArrayList; -import java.util.LinkedHashMap; +import java.util.Arrays; import java.util.List; import java.util.Map; +import jalview.structure.AtomSpecModel; +import jalview.structure.StructureCommand; +import jalview.structure.StructureCommandI; +import jalview.structure.StructureCommandsBase; +import jalview.structure.StructureCommandsI.AtomSpecType; +import jalview.util.ColorUtils; + /** * Routines for generating Chimera commands for Jalview/Chimera binding * * @author JimP * */ -public class ChimeraCommands +public class ChimeraCommands extends StructureCommandsBase { + // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/focus.html + private static final StructureCommand FOCUS_VIEW = new StructureCommand( + "focus"); + + // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/listen.html#listresattr + private static final StructureCommand LIST_RESIDUE_ATTRIBUTES = new StructureCommand( + "list resattr"); + + // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/stop.html + private static final StructureCommand CLOSE_CHIMERA = new StructureCommand( + "stop really"); + + // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/listen.html + private static final StructureCommand STOP_NOTIFY_SELECTION = new StructureCommand( + "listen stop selection"); + + private static final StructureCommand STOP_NOTIFY_MODELS = new StructureCommand( + "listen stop models"); + + // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/listen.html#listselection + private static final StructureCommand GET_SELECTION = new StructureCommand( + "list selection level residue"); + + private static final StructureCommand SHOW_BACKBONE = new StructureCommand( + "~display all;~ribbon;chain @CA|P"); + + private static final StructureCommandI COLOUR_BY_CHARGE = new StructureCommand( + "color white;color red ::ASP,GLU;color blue ::LYS,ARG;color yellow ::CYS"); + + // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/rainbow.html + private static final StructureCommandI COLOUR_BY_CHAIN = new StructureCommand( + "rainbow chain"); + + // Chimera clause to exclude alternate locations in atom selection + private static final String NO_ALTLOCS = "&~@.B-Z&~@.2-9"; + + @Override + public StructureCommandI colourResidues(String atomSpec, Color colour) + { + // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/color.html + String colourCode = getColourString(colour); + return new StructureCommand("color " + colourCode + " " + atomSpec); + } + + /** + * Returns a colour formatted suitable for use in viewer command syntax + * + * @param colour + * @return + */ + protected String getColourString(Color colour) + { + return ColorUtils.toTkCode(colour); + } /** - * utility to construct the commands to colour chains by the given alignment - * for passing to Chimera + * Traverse the map of features/values/models/chains/positions to construct a + * list of 'setattr' commands (one per distinct feature type and value). + *

+ * The format of each command is * - * @returns Object[] { Object[] { , + *

+   * 
setattr r " " #modelnumber:range.chain + * e.g. setattr r jv_chain <value> #0:2.B,4.B,9-12.B|#1:1.A,2-6.A,... + *
+ *
* + * @param featureMap + * @return */ - public static StructureMappingcommandSet[] getColourBySequenceCommand( - StructureSelectionManager ssm, String[] files, - SequenceI[][] sequence, SequenceRenderer sr, FeatureRenderer fr, - AlignmentI alignment) + @Override + public List setAttributes( + Map> featureMap) { - String defAttrPath = null; - FileOutputStream fos = null; - try - { - File outFile = File.createTempFile("jalviewdefattr", ".xml"); - outFile.deleteOnExit(); - defAttrPath = outFile.getPath(); - fos = new FileOutputStream(outFile); - fos.write("attribute: jalviewclr\n".getBytes()); - } catch (IOException e1) + List commands = new ArrayList<>(); + for (String featureType : featureMap.keySet()) { - e1.printStackTrace(); + String attributeName = makeAttributeName(featureType); + + /* + * clear down existing attributes for this feature + */ + // 'problem' - sets attribute to None on all residues - overkill? + // commands.add("~setattr r " + attributeName + " :*"); + + Map values = featureMap.get(featureType); + for (Object value : values.keySet()) + { + /* + * for each distinct value recorded for this feature type, + * add a command to set the attribute on the mapped residues + * Put values in single quotes, encoding any embedded single quotes + */ + AtomSpecModel atomSpecModel = values.get(value); + String featureValue = value.toString(); + featureValue = featureValue.replaceAll("\\'", "'"); + StructureCommandI cmd = setAttribute(attributeName, featureValue, + atomSpecModel); + commands.add(cmd); + } } - List cset = new ArrayList(); + + return commands; + } + + /** + * Returns a viewer command to set the given residue attribute value on + * residues specified by the AtomSpecModel, for example + * + *
+   * setatr res jv_chain 'primary' #1:12-34,48-55.B
+   * 
+ * + * @param attributeName + * @param attributeValue + * @param atomSpecModel + * @return + */ + protected StructureCommandI setAttribute(String attributeName, + String attributeValue, AtomSpecModel atomSpecModel) + { + StringBuilder sb = new StringBuilder(128); + sb.append("setattr res ").append(attributeName).append(" '") + .append(attributeValue).append("' "); + sb.append(getAtomSpec(atomSpecModel, AtomSpecType.RESIDUE_ONLY)); + return new StructureCommand(sb.toString()); + } + + /** + * Makes a prefixed and valid Chimera attribute name. A jv_ prefix is applied + * for a 'Jalview' namespace, and any non-alphanumeric character is converted + * to an underscore. + * + * @param featureType + * @return + * @see https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/setattr.html + */ + @Override + protected String makeAttributeName(String featureType) + { + String attName = super.makeAttributeName(featureType); /* - * Map of { colour, positionSpecs} + * Chimera treats an attribute name ending in 'color' as colour-valued; + * Jalview doesn't, so prevent this by appending an underscore */ - Map colranges = new LinkedHashMap(); - StringBuilder setAttributes = new StringBuilder(256); - String lastColour = "none"; - Color lastCol = null; - for (int pdbfnum = 0; pdbfnum < files.length; pdbfnum++) + if (attName.toUpperCase(Locale.ROOT).endsWith("COLOR")) { - boolean startModel = true; - StructureMapping[] mapping = ssm.getMapping(files[pdbfnum]); + attName += "_"; + } - if (mapping == null || mapping.length < 1) - { - continue; - } + return attName; + } + + @Override + public StructureCommandI colourByChain() + { + return COLOUR_BY_CHAIN; + } + + @Override + public List colourByCharge() + { + return Arrays.asList(COLOUR_BY_CHARGE); + } + + @Override + public String getResidueSpec(String residue) + { + return "::" + residue; + } + + @Override + public StructureCommandI setBackgroundColour(Color col) + { + // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/set.html#bgcolor + return new StructureCommand("set bgColor " + ColorUtils.toTkCode(col)); + } + + @Override + public StructureCommandI focusView() + { + return FOCUS_VIEW; + } - int startPos = -1, lastPos = -1; - String lastChain = ""; - for (int s = 0; s < sequence[pdbfnum].length; s++) + @Override + public List showChains(List toShow) + { + /* + * Construct a chimera command like + * + * ~display #*;~ribbon #*;ribbon :.A,:.B + */ + StringBuilder cmd = new StringBuilder(64); + boolean first = true; + for (String chain : toShow) + { + String[] tokens = chain.split(":"); + if (tokens.length == 2) { - for (int sp, m = 0; m < mapping.length; m++) + String showChainCmd = tokens[0] + ":." + tokens[1]; + if (!first) { - final SequenceI seq = sequence[pdbfnum][s]; - if (mapping[m].getSequence() == seq - && (sp = alignment.findIndex(seq)) > -1) - { - SequenceI asp = alignment.getSequenceAt(sp); - for (int r = 0; r < asp.getLength(); r++) - { - // no mapping to gaps in sequence - if (Comparison.isGap(asp.getCharAt(r))) - { - continue; - } - int pos = mapping[m].getPDBResNum(asp.findPosition(r)); - - if (pos < 1 || pos == lastPos) - { - continue; - } - - Color col = getResidueColour(seq, r, sr, fr); - /* - * Just keep incrementing the end position for this colour range - * _unless_ colour, PDB model or chain has changed, or there is a - * gap in the mapped residue sequence - */ - final boolean newColour = !col.equals(lastCol); - final boolean nonContig = lastPos + 1 != pos; - final boolean newChain = !mapping[m].getChain().equals(lastChain); - if (newColour || nonContig || startModel || newChain) - { - if (/* lastCol != null */startPos != -1) - { - addColourRange(colranges, lastCol, pdbfnum, startPos, - lastPos, lastChain, startModel); - startModel = false; - } - // lastCol = null; - startPos = pos; - } - lastCol = col; - lastPos = pos; - // lastModel = pdbfnum; - lastChain = mapping[m].getChain(); - } - // final colour range - if (lastCol != null) - { - addColourRange(colranges, lastCol, pdbfnum, startPos, - lastPos, lastChain, false); - } - break; - } + cmd.append(","); } + cmd.append(showChainCmd); + first = false; } } - try - { - lastColour = buildColourCommands(cset, colranges, - fos, setAttributes); - } catch (IOException e) - { - e.printStackTrace(); - } - try - { - fos.close(); - } catch (IOException e) - { - e.printStackTrace(); - } + /* + * could append ";focus" to this command to resize the display to fill the + * window, but it looks more helpful not to (easier to relate chains to the + * whole) + */ + final String command = "~display #*; ~ribbon #*; ribbon :" + + cmd.toString(); + return Arrays.asList(new StructureCommand(command)); + } + @Override + public List superposeStructures(AtomSpecModel ref, + AtomSpecModel spec, AtomSpecType backbone) + { /* - * Send a rangeColor command, preceded by either defattr or setattr, - * whichever we end up preferring! + * Form Chimera match command to match spec to ref + * (the first set of atoms are moved on to the second) * - * rangecolor requires a minimum of two attribute values to operate on + * match #1:1-30.B,81-100.B@CA #0:21-40.A,61-90.A@CA + * + * @see https://www.cgl.ucsf.edu/chimera/docs/UsersGuide/midas/match.html */ - StringBuilder rangeColor = new StringBuilder(256); - rangeColor.append("rangecolor jalviewclr"); - int colourId = 0; - for (String colour : colranges.keySet()) - { - colourId++; - rangeColor.append(" " + colourId + " " + colour); - } - String rangeColorCommand = rangeColor.toString(); - if (rangeColorCommand.split(" ").length < 5) - { - rangeColorCommand += " max " + lastColour; - } - final String defAttrCommand = "defattr " + defAttrPath - + " raiseTool false"; - final String setAttrCommand = setAttributes.toString(); - final String attrCommand = false ? defAttrCommand : setAttrCommand; - cset.add(new StructureMappingcommandSet(ChimeraCommands.class, null, - new String[] - { attrCommand /* , rangeColorCommand */})); - - return cset.toArray(new StructureMappingcommandSet[cset.size()]); + StringBuilder cmd = new StringBuilder(); + String atomSpecAlphaOnly = getAtomSpec(spec, backbone); + String refSpecAlphaOnly = getAtomSpec(ref, backbone); + cmd.append("match ").append(atomSpecAlphaOnly).append(" ") + .append(refSpecAlphaOnly); + + /* + * show superposed residues as ribbon + */ + String atomSpec = getAtomSpec(spec, AtomSpecType.RESIDUE_ONLY); + String refSpec = getAtomSpec(ref, AtomSpecType.RESIDUE_ONLY); + cmd.append("; ribbon "); + cmd.append(atomSpec).append("|").append(refSpec).append("; focus"); + + return Arrays.asList(new StructureCommand(cmd.toString())); } - /** - * Get the residue colour at the given sequence position - as determined by - * the sequence group colour (if any), else the colour scheme, possibly - * overridden by a feature colour. - * - * @param seq - * @param position - * @param sr - * @param fr - * @return - */ - protected static Color getResidueColour(final SequenceI seq, - int position, SequenceRenderer sr, FeatureRenderer fr) + @Override + public StructureCommandI openCommandFile(String path) { - Color col = sr.getResidueBoxColour(seq, position); + // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/filetypes.html + return new StructureCommand("open cmd:" + path); + } - if (fr != null) - { - col = fr.findFeatureColour(col, seq, position); - } - return col; + @Override + public StructureCommandI saveSession(String filepath) + { + // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/save.html + return new StructureCommand("save " + filepath); } /** - * Helper method to build the colour commands for one PDBfile. + * Returns the range(s) modelled by {@code atomSpec} formatted as a Chimera + * atomspec string, e.g. + * + *
+   * #0:15.A,28.A,54.A,70-72.A|#1:2.A,6.A,11.A,13-14.A
+   * 
+ * + * where + *
    + *
  • #0 is a model number
  • + *
  • 15 or 70-72 is a residue number, or range of residue numbers
  • + *
  • .A is a chain identifier
  • + *
  • residue ranges are separated by comma
  • + *
  • atomspecs for distinct models are separated by | (or)
  • + *
+ * + *
    * 
-   * @param cset
-   *          the list of commands to be added to
-   * @param colranges
-   *          the map of colours to residue positions already determined
-   * @param fos
-   *          file to write 'defattr' commands to
-   * @param setAttributes
-   * @throws IOException
+   * @param model
+   * @param specType
+   * @return
+   * @see https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/frameatom_spec.html
    */
-  protected static String buildColourCommands(
-          List cset,
-          Map colranges,
-          FileOutputStream fos, StringBuilder setAttributes)
-          throws IOException
+  @Override
+  public String getAtomSpec(AtomSpecModel atomSpec, AtomSpecType specType)
   {
-    int colourId = 0;
-    String lastColour = null;
-    for (String colour : colranges.keySet())
+    StringBuilder sb = new StringBuilder(128);
+    boolean firstModel = true;
+    for (String model : atomSpec.getModels())
     {
-      lastColour = colour;
-      colourId++;
-      /*
-       * Using color command directly is slow for larger structures.
-       * setAttributes.append("color #" + colour + " " + colranges.get(colour)+
-       * ";");
-       */
-      setAttributes.append("color " + colour + " " + colranges.get(colour)
-              + ";");
-      final String atomSpec = new String(colranges.get(colour));
-      // setAttributes.append("setattr r jalviewclr " + colourId + " "
-      // + atomSpec + ";");
-      fos.write(("\t" + atomSpec + "\t" + colourId + "\n").getBytes());
+      if (!firstModel)
+      {
+        sb.append("|");
+      }
+      firstModel = false;
+      appendModel(sb, model, atomSpec, specType);
     }
-    return lastColour;
+    return sb.toString();
   }
 
   /**
-   * Helper method to record a range of positions of the same colour.
+   * A helper method to append an atomSpec string for atoms in the given model
    * 
-   * @param colranges
-   * @param colour
+   * @param sb
    * @param model
-   * @param startPos
-   * @param endPos
-   * @param chain
-   * @param changeModel
+   * @param atomSpec
+   * @param alphaOnly
    */
-  private static void addColourRange(Map colranges,
-          Color colour, int model, int startPos, int endPos, String chain,
-          boolean startModel)
+  protected void appendModel(StringBuilder sb, String model,
+          AtomSpecModel atomSpec, AtomSpecType specType)
   {
-    String colstring = "#" + ((colour.getRed() < 16) ? "0" : "")
-            + Integer.toHexString(colour.getRed())
-            + ((colour.getGreen()< 16) ? "0":"")+Integer.toHexString(colour.getGreen())
-            + ((colour.getBlue()< 16) ? "0":"")+Integer.toHexString(colour.getBlue());
-    StringBuilder currange = colranges.get(colstring);
-    if (currange == null)
-    {
-      colranges.put(colstring, currange = new StringBuilder(256));
-    }
-    /*
-     * Format as (e.g.) #0:1-3.A,5.A,7-10.A,...#1:1-4.B,..etc
-     */
-    // if (currange.length() > 0)
-    // {
-    // currange.append("|");
-    // }
-    // currange.append("#" + model + ":" + ((startPos==endPos) ? startPos :
-    // startPos + "-"
-    // + endPos) + "." + chain);
-    if (currange.length() == 0)
+    sb.append("#").append(model).append(":");
+
+    boolean firstPositionForModel = true;
+
+    for (String chain : atomSpec.getChains(model))
     {
-      currange.append("#" + model + ":");
+      chain = " ".equals(chain) ? chain : chain.trim();
+
+      List rangeList = atomSpec.getRanges(model, chain);
+      for (int[] range : rangeList)
+      {
+        appendRange(sb, range[0], range[1], chain, firstPositionForModel,
+                false);
+        firstPositionForModel = false;
+      }
     }
-    else if (startModel)
+    if (specType == AtomSpecType.ALPHA)
     {
-      currange.append(",#" + model + ":");
+      /*
+       * restrict to alpha carbon, no alternative locations
+       * (needed to ensuring matching atom counts for superposition)
+       */
+      sb.append("@CA").append(NO_ALTLOCS);
     }
-    else
+    if (specType == AtomSpecType.PHOSPHATE)
     {
-      currange.append(",");
+      sb.append("@P").append(NO_ALTLOCS);
     }
-    final String rangeSpec = (startPos == endPos) ? Integer
-            .toString(startPos) : (startPos + "-" + endPos);
-    currange.append(rangeSpec + "." + chain);
+  }
+
+  @Override
+  public List showBackbone()
+  {
+    return Arrays.asList(SHOW_BACKBONE);
+  }
+
+  @Override
+  public StructureCommandI loadFile(String file)
+  {
+    return new StructureCommand("open " + file);
+  }
+
+  @Override
+  public StructureCommandI openSession(String filepath)
+  {
+    // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/filetypes.html
+    // this version of the command has no dependency on file extension
+    return new StructureCommand("open chimera:" + filepath);
+  }
+
+  @Override
+  public StructureCommandI closeViewer()
+  {
+    return CLOSE_CHIMERA;
+  }
+
+  @Override
+  public List startNotifications(String uri)
+  {
+    // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/listen.html
+    List cmds = new ArrayList<>();
+    cmds.add(new StructureCommand("listen start models url " + uri));
+    cmds.add(new StructureCommand(
+            "listen start select prefix SelectionChanged url " + uri));
+    return cmds;
+  }
+
+  @Override
+  public List stopNotifications()
+  {
+    List cmds = new ArrayList<>();
+    cmds.add(STOP_NOTIFY_MODELS);
+    cmds.add(STOP_NOTIFY_SELECTION);
+    return cmds;
+  }
+
+  @Override
+  public StructureCommandI getSelectedResidues()
+  {
+    return GET_SELECTION;
+  }
+
+  @Override
+  public StructureCommandI listResidueAttributes()
+  {
+    return LIST_RESIDUE_ATTRIBUTES;
+  }
+
+  @Override
+  public StructureCommandI getResidueAttributes(String attName)
+  {
+    // this alternative command
+    // list residues spec ':*/attName' attr attName
+    // doesn't report 'None' values (which is good), but
+    // fails for 'average.bfactor' (which is bad):
+    return new StructureCommand("list residues attr '" + attName + "'");
   }
 
 }