X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=src%2Fjalview%2Fext%2Frbvi%2Fchimera%2FChimeraCommands.java;h=5beee568eb8397fb3fea1121c9d9d8e5407bcaaa;hb=c38d37887ae51d63942ac4321f6769308188ed6b;hp=95757fd3e1a8904131e96a029bba15ba1e0544e4;hpb=13fd7bc6175d7aa66d8e161d21183e7e33c9150a;p=jalview.git diff --git a/src/jalview/ext/rbvi/chimera/ChimeraCommands.java b/src/jalview/ext/rbvi/chimera/ChimeraCommands.java index 95757fd..5beee56 100644 --- a/src/jalview/ext/rbvi/chimera/ChimeraCommands.java +++ b/src/jalview/ext/rbvi/chimera/ChimeraCommands.java @@ -20,529 +20,390 @@ */ package jalview.ext.rbvi.chimera; -import jalview.api.AlignViewportI; -import jalview.api.AlignmentViewPanel; -import jalview.api.FeatureRenderer; -import jalview.api.SequenceRenderer; -import jalview.datamodel.AlignmentI; -import jalview.datamodel.ColumnSelection; -import jalview.datamodel.SequenceFeature; -import jalview.datamodel.SequenceI; -import jalview.renderer.seqfeatures.FeatureColourFinder; -import jalview.structure.StructureMapping; -import jalview.structure.StructureMappingcommandSet; -import jalview.structure.StructureSelectionManager; -import jalview.util.ColorUtils; -import jalview.util.Comparison; - import java.awt.Color; import java.util.ArrayList; -import java.util.HashMap; -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.util.ColorUtils; + /** * Routines for generating Chimera commands for Jalview/Chimera binding * * @author JimP * */ -public class ChimeraCommands +public class ChimeraCommands extends StructureCommandsBase { + 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"); + + 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"; - public static final String NAMESPACE_PREFIX = "jv_"; + @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); + } /** - * Constructs Chimera commands to colour residues as per the Jalview alignment + * Returns a colour formatted suitable for use in viewer command syntax * - * @param ssm - * @param files - * @param sequence - * @param sr - * @param fr - * @param viewPanel + * @param colour * @return */ - public static StructureMappingcommandSet[] getColourBySequenceCommand( - StructureSelectionManager ssm, String[] files, - SequenceI[][] sequence, SequenceRenderer sr, - AlignmentViewPanel viewPanel) + protected String getColourString(Color colour) { - Map colourMap = buildColoursMap(ssm, files, - sequence, sr, viewPanel); - - List colourCommands = buildColourCommands(colourMap); - - StructureMappingcommandSet cs = new StructureMappingcommandSet( - ChimeraCommands.class, null, - colourCommands.toArray(new String[colourCommands.size()])); - - return new StructureMappingcommandSet[] { cs }; + return ColorUtils.toTkCode(colour); } /** - * Traverse the map of colours/models/chains/positions to construct a list of - * 'color' commands (one per distinct colour used). The format of each command - * is + * 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 * * 

-   * 
 
-   * color colorname #modelnumber:range.chain 
-   * e.g. color #00ff00 #0:2.B,4.B,9-12.B|#1:1.A,2-6.A,...
+   * 
 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 colourMap + * @param featureMap * @return */ - protected static List buildColourCommands( - Map colourMap) + @Override + public List setAttributes( + Map> featureMap) { - /* - * This version concatenates all commands into a single String (semi-colon - * delimited). If length limit issues arise, refactor to return one color - * command per colour. - */ - List commands = new ArrayList(); - StringBuilder sb = new StringBuilder(256); - boolean firstColour = true; - for (Object key : colourMap.keySet()) + List commands = new ArrayList<>(); + for (String featureType : featureMap.keySet()) { - Color colour = (Color) key; - String colourCode = ColorUtils.toTkCode(colour); - if (!firstColour) + 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()) { - sb.append("; "); + /* + * 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); } - sb.append("color ").append(colourCode).append(" "); - firstColour = false; - final AtomSpecModel colourData = colourMap.get(colour); - sb.append(colourData.getAtomSpec()); } - commands.add(sb.toString()); + return commands; } /** - * Traverses a map of { modelNumber, {chain, {list of from-to ranges} } } and - * builds a Chimera format atom spec + * Returns a viewer command to set the given residue attribute value on + * residues specified by the AtomSpecModel, for example * - * @param modelAndChainRanges + * 
+   * setatr res jv_chain 'primary' #1:12-34,48-55.B
+   *
+ * + * @param attributeName + * @param attributeValue + * @param atomSpecModel + * @return */ - protected static String getAtomSpec( - Map>> modelAndChainRanges) + protected StructureCommandI setAttribute(String attributeName, + String attributeValue, + AtomSpecModel atomSpecModel) { StringBuilder sb = new StringBuilder(128); - boolean firstModelForColour = true; - for (Integer model : modelAndChainRanges.keySet()) - { - boolean firstPositionForModel = true; - if (!firstModelForColour) - { - sb.append("|"); - } - firstModelForColour = false; - sb.append("#").append(model).append(":"); - - final Map> modelData = modelAndChainRanges - .get(model); - for (String chain : modelData.keySet()) - { - boolean hasChain = !"".equals(chain.trim()); - for (int[] range : modelData.get(chain)) - { - if (!firstPositionForModel) - { - sb.append(","); - } - if (range[0] == range[1]) - { - sb.append(range[0]); - } - else - { - sb.append(range[0]).append("-").append(range[1]); - } - if (hasChain) - { - sb.append(".").append(chain); - } - firstPositionForModel = false; - } - } - } - return sb.toString(); + sb.append("setattr res ").append(attributeName).append(" '") + .append(attributeValue).append("' "); + sb.append(getAtomSpec(atomSpecModel, false)); + return new StructureCommand(sb.toString()); } /** - * 
-   * Build a data structure which records contiguous subsequences for each colour. 
-   * From this we can easily generate the Chimera command for colour by sequence.
-   * Color
-   *     Model number
-   *         Chain
-   *             list of start/end ranges
-   * Ordering is by order of addition (for colours and positions), natural ordering (for models and chains)
-   *
+ * 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 */ - protected static Map buildColoursMap( - StructureSelectionManager ssm, String[] files, - SequenceI[][] sequence, SequenceRenderer sr, - AlignmentViewPanel viewPanel) + @Override + protected String makeAttributeName(String featureType) { - FeatureRenderer fr = viewPanel.getFeatureRenderer(); - FeatureColourFinder finder = new FeatureColourFinder(fr); - AlignViewportI viewport = viewPanel.getAlignViewport(); - ColumnSelection cs = viewport.getColumnSelection(); - AlignmentI al = viewport.getAlignment(); - Map colourMap = new LinkedHashMap(); - Color lastColour = null; - - for (int pdbfnum = 0; pdbfnum < files.length; pdbfnum++) + String attName = super.makeAttributeName(featureType); + + /* + * Chimera treats an attribute name ending in 'color' as colour-valued; + * Jalview doesn't, so prevent this by appending an underscore + */ + if (attName.toUpperCase().endsWith("COLOR")) { - StructureMapping[] mapping = ssm.getMapping(files[pdbfnum]); + attName += "_"; + } - if (mapping == null || mapping.length < 1) - { - continue; - } + return attName; + } - int startPos = -1, lastPos = -1; - String lastChain = ""; - for (int s = 0; s < sequence[pdbfnum].length; s++) + @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() + { + // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/focus.html + return new StructureCommand("focus"); + } + + @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 = al.findIndex(seq)) > -1) - { - SequenceI asp = al.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 colour = sr.getResidueColour(seq, r, finder); - - /* - * darker colour for hidden regions - */ - if (!cs.isVisible(r)) - { - colour = Color.GRAY; - } - - final String chain = mapping[m].getChain(); - - /* - * 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 = !colour.equals(lastColour); - final boolean nonContig = lastPos + 1 != pos; - final boolean newChain = !chain.equals(lastChain); - if (newColour || nonContig || newChain) - { - if (startPos != -1) - { - addColourRange(colourMap, lastColour, pdbfnum, startPos, - lastPos, lastChain); - } - startPos = pos; - } - lastColour = colour; - lastPos = pos; - lastChain = chain; - } - // final colour range - if (lastColour != null) - { - addColourRange(colourMap, lastColour, pdbfnum, startPos, lastPos, - lastChain); - } - // break; - } + cmd.append(","); } + cmd.append(showChainCmd); + first = false; } } - return colourMap; + + /* + * 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)); } - /** - * Helper method to add one contiguous colour range to the colour map. - * - * @param map - * @param key - * @param model - * @param startPos - * @param endPos - * @param chain - */ - protected static void addColourRange(Map map, - Object key, int model, int startPos, int endPos, String chain) + @Override + public List superposeStructures(AtomSpecModel ref, + AtomSpecModel spec) { /* - * Get/initialize map of data for the colour + * Form Chimera match command to match spec to ref + * (the first set of atoms are moved on to the second) + * + * 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 */ - AtomSpecModel atomSpec = map.get(key); - if (atomSpec == null) - { - atomSpec = new AtomSpecModel(); - map.put(key, atomSpec); - } + StringBuilder cmd = new StringBuilder(); + String atomSpecAlphaOnly = getAtomSpec(spec, true); + String refSpecAlphaOnly = getAtomSpec(ref, true); + cmd.append("match ").append(atomSpecAlphaOnly).append(" ").append(refSpecAlphaOnly); + + /* + * show superposed residues as ribbon + */ + String atomSpec = getAtomSpec(spec, false); + String refSpec = getAtomSpec(ref, false); + cmd.append("; ribbon "); + cmd.append(atomSpec).append("|").append(refSpec).append("; focus"); - atomSpec.addRange(model, startPos, endPos, chain); + return Arrays.asList(new StructureCommand(cmd.toString())); } - /** - * Constructs and returns Chimera commands to set attributes on residues - * corresponding to features in Jalview. Attribute names are the Jalview - * feature type, with a "jv_" prefix. - * - * @param ssm - * @param files - * @param seqs - * @param viewPanel - * @return - */ - public static StructureMappingcommandSet getSetAttributeCommandsForFeatures( - StructureSelectionManager ssm, String[] files, - SequenceI[][] seqs, AlignmentViewPanel viewPanel) + @Override + public StructureCommandI openCommandFile(String path) { - Map> featureMap = buildFeaturesMap( - ssm, files, seqs, viewPanel); - - List commands = buildSetAttributeCommands(featureMap); - - StructureMappingcommandSet cs = new StructureMappingcommandSet( - ChimeraCommands.class, null, - commands.toArray(new String[commands.size()])); + // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/filetypes.html + return new StructureCommand("open cmd:" + path); + } - return cs; + @Override + public StructureCommandI saveSession(String filepath) + { + // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/save.html + return new StructureCommand("save " + filepath); } /** + * Returns the range(s) modelled by {@code atomSpec} formatted as a Chimera + * atomspec string, e.g. + * * 
-   * Helper method to build a map of 
-   *   { featureType, { feature value, AtomSpecModel } }
+   * #0:15.A,28.A,54.A,70-72.A|#1:2.A,6.A,11.A,13-14.A
    *
* - * @param ssm - * @param files - * @param seqs - * @param viewPanel + * 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 model
+   * @param alphaOnly
    * @return
+   * @see https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/frameatom_spec.html
    */
-  protected static Map> buildFeaturesMap(
-          StructureSelectionManager ssm, String[] files,
-          SequenceI[][] seqs, AlignmentViewPanel viewPanel)
+  @Override
+  public String getAtomSpec(AtomSpecModel atomSpec, boolean alphaOnly)
   {
-    Map> theMap = new LinkedHashMap>();
-
-    FeatureRenderer fr = viewPanel.getFeatureRenderer();
-    if (fr == null)
-    {
-      return theMap;
-    }
-
-    List visibleFeatures = fr.getDisplayedFeatureTypes();
-    if (visibleFeatures.isEmpty())
-    {
-      return theMap;
-    }
-
-    AlignmentI alignment = viewPanel.getAlignment();
-    for (int pdbfnum = 0; pdbfnum < files.length; pdbfnum++)
+    StringBuilder sb = new StringBuilder(128);
+    boolean firstModel = true;
+    for (String model : atomSpec.getModels())
     {
-      StructureMapping[] mapping = ssm.getMapping(files[pdbfnum]);
-
-      if (mapping == null || mapping.length < 1)
-      {
-        continue;
-      }
-
-      for (int seqNo = 0; seqNo < seqs[pdbfnum].length; seqNo++)
+      if (!firstModel)
       {
-        for (int m = 0; m < mapping.length; m++)
-        {
-          final SequenceI seq = seqs[pdbfnum][seqNo];
-          int sp = alignment.findIndex(seq);
-          if (mapping[m].getSequence() == seq && sp > -1)
-          {
-            /*
-             * found a sequence with a mapping to a structure;
-             * now scan its features
-             */
-            SequenceI asp = alignment.getSequenceAt(sp);
-
-            scanSequenceFeatures(visibleFeatures, mapping[m], asp, theMap,
-                    pdbfnum);
-          }
-        }
+        sb.append("|");
       }
+      firstModel = false;
+      appendModel(sb, model, atomSpec, alphaOnly);
     }
-    return theMap;
+    return sb.toString();
   }
 
   /**
-   * Inspect features on the sequence; for each feature that is visible,
-   * determine its mapped ranges in the structure (if any) according to the
-   * given mapping, and add them to the map
+   * A helper method to append an atomSpec string for atoms in the given model
    * 
-   * @param visibleFeatures
-   * @param mapping
-   * @param seq
-   * @param theMap
-   * @param modelNumber
+   * @param sb
+   * @param model
+   * @param atomSpec
+   * @param alphaOnly
    */
-  protected static void scanSequenceFeatures(List visibleFeatures,
-          StructureMapping mapping, SequenceI seq,
-          Map> theMap, int modelNumber)
+  protected void appendModel(StringBuilder sb, String model,
+          AtomSpecModel atomSpec, boolean alphaOnly)
   {
-    SequenceFeature[] sfs = seq.getSequenceFeatures();
-    if (sfs == null)
-    {
-      return;
-    }
+    sb.append("#").append(model).append(":");
 
-    for (SequenceFeature sf : sfs)
-    {
-      String type = sf.getType();
+    boolean firstPositionForModel = true;
 
-      /*
-       * Only copy visible features, don't copy any which originated
-       * from Chimera, and suppress uninteresting ones (e.g. RESNUM)
-       */
-      boolean isFromViewer = JalviewChimeraBinding.CHIMERA_FEATURE_GROUP
-              .equals(sf.getFeatureGroup());
-      if (isFromViewer || !visibleFeatures.contains(type))
-      {
-        continue;
-      }
-      List mappedRanges = mapping.getPDBResNumRanges(sf.getBegin(),
-              sf.getEnd());
+    for (String chain : atomSpec.getChains(model))
+    {
+      chain = " ".equals(chain) ? chain : chain.trim();
 
-      if (!mappedRanges.isEmpty())
+      List rangeList = atomSpec.getRanges(model, chain);
+      for (int[] range : rangeList)
       {
-        String value = sf.getDescription();
-        if (value == null || value.length() == 0)
-        {
-          value = type;
-        }
-        float score = sf.getScore();
-        if (score != 0f && !Float.isNaN(score))
-        {
-          value = Float.toString(score);
-        }
-        Map featureValues = theMap.get(type);
-        if (featureValues == null)
-        {
-          featureValues = new HashMap();
-          theMap.put(type, featureValues);
-        }
-        for (int[] range : mappedRanges)
-        {
-          addColourRange(featureValues, value, modelNumber, range[0], range[1],
-                  mapping.getChain());
-        }
+        appendRange(sb, range[0], range[1], chain, firstPositionForModel,
+                false);
+        firstPositionForModel = false;
       }
     }
-  }
-
-  /**
-   * 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
-   * 
-   * 
-   * 
 setattr r  " " #modelnumber:range.chain 
-   * e.g. setattr r jv:chain  #0:2.B,4.B,9-12.B|#1:1.A,2-6.A,...
-   * 

-   * 

-   * 
-   * @param featureMap
-   * @return
-   */
-  protected static List buildSetAttributeCommands(
-          Map> featureMap)
-  {
-    List commands = new ArrayList();
-    for (String featureType : featureMap.keySet())
+    if (alphaOnly)
     {
-      String attributeName = makeAttributeName(featureType);
-
       /*
-       * clear down existing attributes for this feature
+       * restrict to alpha carbon, no alternative locations
+       * (needed to ensuring matching atom counts for superposition)
        */
-      // '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
-         */
-        StringBuilder sb = new StringBuilder(128);
-        String featureValue = value.toString();
-        featureValue = featureValue.replaceAll("\\'", "'");
-        sb.append("setattr r ").append(attributeName).append(" '")
-                .append(featureValue).append("' ");
-        sb.append(values.get(value).getAtomSpec());
-        commands.add(sb.toString());
-      }
+      // TODO @P instead if RNA - add nucleotide flag to AtomSpecModel?
+      sb.append("@CA").append(NO_ALTLOCS);
     }
+  }
 
-    return commands;
+  @Override
+  public List showBackbone()
+  {
+    return Arrays.asList(SHOW_BACKBONE);
+  }
+
+  @Override
+  public StructureCommandI loadFile(String file)
+  {
+    return new StructureCommand("open " + file);
   }
 
   /**
-   * 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
-   * 

+   * Overrides the default method to concatenate colour commands into one
    */
-  protected static String makeAttributeName(String featureType)
+  @Override
+  public List colourBySequence(
+          Map colourMap)
   {
-    StringBuilder sb = new StringBuilder();
-    if (featureType != null)
+    List commands = new ArrayList<>();
+    StringBuilder sb = new StringBuilder(colourMap.size() * 20);
+    boolean first = true;
+    for (Object key : colourMap.keySet())
     {
-      for (char c : featureType.toCharArray())
+      Color colour = (Color) key;
+      final AtomSpecModel colourData = colourMap.get(colour);
+      StructureCommandI command = getColourCommand(colourData, colour);
+      if (!first)
       {
-        sb.append(Character.isLetterOrDigit(c) ? c : '_');
+        sb.append(getCommandSeparator());
       }
+      first = false;
+      sb.append(command.getCommand());
     }
-    String attName = NAMESPACE_PREFIX + sb.toString();
 
-    /*
-     * Chimera treats an attribute name ending in 'color' as colour-valued;
-     * Jalview doesn't, so prevent this by appending an underscore
-     */
-    if (attName.toUpperCase().endsWith("COLOR"))
-    {
-      attName += "_";
-    }
+    commands.add(new StructureCommand(sb.toString()));
+    return commands;
+  }
 
-    return attName;
+  @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);
   }
 
 }