src/jalview/structure/StructureCommandsI.java

   1 package jalview.structure;
   2
   3 import jalview.api.AlignmentViewPanel;
   4 import jalview.datamodel.SequenceI;
   5
   6 import java.awt.Color;
   7 import java.util.List;
   8 import java.util.Map;
   9
  10 /**
  11  * Methods that generate commands that can be sent to a molecular structure
  12  * viewer program (e.g. Jmol, Chimera, ChimeraX)
  13  *
  14  * @author gmcarstairs
  15  *
  16  */
  17 public interface StructureCommandsI
  18 {
  19   /**
  20    * Data bean class to simplify parameterisation in superposeStructures
  21    */
  22   public class SuperposeData
  23   {
  24     public String filename;
  25
  26     public String pdbId;
  27
  28     public String chain = "";
  29
  30     public boolean isRna;
  31
  32     /*
  33      * The pdb residue number (if any) mapped to columns of the alignment
  34      */
  35     public int[] pdbResNo; // or use SparseIntArray?
  36
  37     public int modelNo;
  38
  39     /**
  40      * Constructor
  41      *
  42      * @param width
  43      *          width of alignment (number of columns that may potentially
  44      *          participate in superposition)
  45      * @param model
  46      *          structure viewer model number
  47      */
  48     public SuperposeData(int width, int model)
  49     {
  50       pdbResNo = new int[width];
  51       modelNo = model;
  52     }
  53   }
  54
  55   /**
  56    * Returns the command to colour by chain
  57    *
  58    * @return
  59    */
  60   String colourByChain();
  61
  62   /**
  63    * Returns the command to colour residues using a charge-based scheme:
  64    * <ul>
  65    * <li>Aspartic acid and Glutamic acid (negative charge) red</li>
  66    * <li>Lysine and Arginine (positive charge) blue</li>
  67    * <li>Cysteine - yellow</li>
  68    * <li>all others - white</li>
  69    * </ul>
  70    *
  71    * @return
  72    */
  73   String colourByCharge();
  74
  75   /**
  76    * Returns the command to colour residues with the colours provided in the
  77    * map, one per three letter residue code
  78    *
  79    * @param colours
  80    * @return
  81    */
  82   String colourByResidues(Map<String, Color> colours);
  83
  84   /**
  85    * Returns the command to set the background colour of the structure viewer
  86    *
  87    * @param col
  88    * @return
  89    */
  90   String setBackgroundColour(Color col);
  91
  92   /**
  93    * Returns commands to colour mapped residues of structures according to
  94    * Jalview's colouring (including feature colouring if applied). Parameter is
  95    * a map from Color to a model of all residues assigned that colour.
  96    *
  97    * @param colourMap
  98    * @return
  99    */
 100
 101   String[] colourBySequence(Map<Object, AtomSpecModel> colourMap);
 102
 103   /**
 104    * Returns a command to centre the display in the structure viewer
 105    *
 106    * @return
 107    */
 108   String focusView();
 109
 110   /**
 111    * Returns a command to show only the selected chains. The items in the input
 112    * list should be formatted as "modelno:chainid".
 113    *
 114    * @param toShow
 115    * @return
 116    */
 117   String showChains(List<String> toShow);
 118
 119   /**
 120    * Returns zero, one or more commands to set attributes on mapped residues in
 121    * the structure viewer for any features present and displayed in Jalview
 122    *
 123    * @param ssm
 124    * @param files
 125    * @param sequence
 126    * @param avp
 127    * @return
 128    */
 129   String[] setAttributesForFeatures(StructureSelectionManager ssm,
 130           String[] files, SequenceI[][] sequence, AlignmentViewPanel avp);
 131
 132   /**
 133    * Returns a command to superpose structures by closest positioning of
 134    * residues in {@code atomSpec} to the corresponding residues in {@ refAtoms}.
 135    * If wanted, this may include commands to visually highlight the residues
 136    * that were used for the superposition.
 137    *
 138    * @param refAtoms
 139    * @param atomSpec
 140    * @return
 141    */
 142   String superposeStructures(AtomSpecModel refAtoms,
 143           AtomSpecModel atomSpec);
 144
 145   /**
 146    * Returns a command to open a file of commands at the given path
 147    *
 148    * @param path
 149    * @return
 150    */
 151   String openCommandFile(String path);
 152
 153   /**
 154    * Returns a command to save the current viewer session state to the given
 155    * file
 156    *
 157    * @param filepath
 158    * @return
 159    */
 160   String saveSession(String filepath);
 161
 162   /**
 163    * Returns a representation of the atom set represented by the model, in
 164    * viewer syntax format. If {@code alphaOnly} is true, this is restricted to
 165    * Alpha Carbon (peptide) or Phosphorous (rna) only
 166    *
 167    * @param model
 168    * @param alphaOnly
 169    * @return
 170    */
 171   String getAtomSpec(AtomSpecModel model, boolean alphaOnly);
 172
 173   /**
 174    * Returns the lowest model number used by the structure viewer (likely 0 or
 175    * 1)
 176    *
 177    * @return
 178    */
 179   // TODO remove by refactoring so command generation is purely driven by
 180   // AtomSpecModel objects derived in the binding classes?
 181   int getModelStartNo();
 182
 183   /**
 184    * Show only the backbone of the peptide (cartoons in Jmol, chain in Chimera)
 185    *
 186    * @return
 187    */
 188   String showBackbone();
 189 }