src/jalview/structure/StructureMapping.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.structure;
  22
  23 import jalview.datamodel.AlignmentAnnotation;
  24 import jalview.datamodel.SequenceI;
  25
  26 import java.util.ArrayList;
  27 import java.util.HashMap;
  28 import java.util.List;
  29 import java.util.Map.Entry;
  30
  31 public class StructureMapping
  32 {
  33   public static final int UNASSIGNED = -1;
  34
  35   public static final int PDB_RES_NUM_INDEX = 0;
  36
  37   public static final int PDB_ATOM_NUM_INDEX = 1;
  38
  39   /**
  40    * Space character constant, for consistent representation when no chain
  41    * specified
  42    */
  43   public static String NO_CHAIN = " ";
  44
  45   String mappingDetails;
  46
  47   SequenceI sequence;
  48
  49   String pdbfile;
  50
  51   String pdbid;
  52
  53   String pdbchain;
  54
  55   // Mapping key is residue index while value is an array containing PDB resNum,
  56   // and atomNo
  57   HashMap<Integer, int[]> mapping;
  58
  59   /**
  60    * Constructor
  61    *
  62    * @param seq
  63    * @param pdbfile
  64    * @param pdbid
  65    * @param chain
  66    * @param mapping
  67    *          a map from sequence to two values, { resNo, atomNo } in the
  68    *          structure
  69    * @param mappingDetails
  70    */
  71   public StructureMapping(SequenceI seq, String pdbfile, String pdbid,
  72           String chain, HashMap<Integer, int[]> mapping,
  73           String mappingDetails)
  74   {
  75     sequence = seq;
  76     this.pdbfile = pdbfile;
  77     this.pdbid = pdbid;
  78     this.pdbchain = chain;
  79     this.mapping = mapping;
  80     this.mappingDetails = mappingDetails;
  81   }
  82
  83   public SequenceI getSequence()
  84   {
  85     return sequence;
  86   }
  87
  88   public String getChain()
  89   {
  90     return pdbchain;
  91   }
  92
  93   public String getPdbId()
  94   {
  95     return pdbid;
  96   }
  97
  98   /**
  99    * Answers the structure atom number mapped to the given sequence position, or
 100    * -1 if no mapping
 101    *
 102    * @param seqpos
 103    * @return
 104    */
 105   public int getAtomNum(int seqpos)
 106   {
 107     int[] resNumAtomMap = mapping.get(seqpos);
 108     return (resNumAtomMap == null ? UNASSIGNED
 109             : resNumAtomMap[PDB_ATOM_NUM_INDEX]);
 110   }
 111
 112   /**
 113    * Answers the structure residue number mapped to the given sequence position,
 114    * or -1 if no mapping
 115    *
 116    * @param seqpos
 117    * @return
 118    */
 119   public int getPDBResNum(int seqpos)
 120   {
 121     int[] resNumAtomMap = mapping.get(seqpos);
 122     return (resNumAtomMap == null ? UNASSIGNED
 123             : resNumAtomMap[PDB_RES_NUM_INDEX]);
 124   }
 125
 126   /**
 127    * Returns a (possibly empty) list of [start, end] residue positions in the
 128    * mapped structure, corresponding to the given range of sequence positions
 129    *
 130    * @param fromSeqPos
 131    * @param toSeqPos
 132    * @return
 133    */
 134   public List<int[]> getPDBResNumRanges(int fromSeqPos, int toSeqPos)
 135   {
 136     List<int[]> result = new ArrayList<int[]>();
 137     int startRes = -1;
 138     int endRes = -1;
 139
 140     for (int i = fromSeqPos; i <= toSeqPos; i++)
 141     {
 142       int resNo = getPDBResNum(i);
 143       if (resNo == UNASSIGNED)
 144       {
 145         continue; // no mapping from this sequence position
 146       }
 147       if (startRes == -1)
 148       {
 149         startRes = resNo;
 150         endRes = resNo;
 151       }
 152       if (resNo >= startRes && resNo <= endRes)
 153       {
 154         // within the current range - no change
 155         continue;
 156       }
 157       if (resNo == startRes - 1)
 158       {
 159         // extend beginning of current range
 160         startRes--;
 161         continue;
 162       }
 163       if (resNo == endRes + 1)
 164       {
 165         // extend end of current range
 166         endRes++;
 167         continue;
 168       }
 169
 170       /*
 171        * resNo is not within or contiguous with last range,
 172        * so write out the last range
 173        */
 174       result.add(new int[] { startRes, endRes });
 175       startRes = resNo;
 176       endRes = resNo;
 177     }
 178
 179     /*
 180      * and add the last range
 181      */
 182     if (startRes != -1)
 183     {
 184       result.add(new int[] { startRes, endRes });
 185     }
 186
 187     return result;
 188   }
 189
 190   /**
 191    * Answers the sequence position mapped to the given structure residue number,
 192    * or -1 if no mapping is found
 193    *
 194    * @param pdbResNum
 195    * @return
 196    */
 197   public int getSeqPos(int pdbResNum)
 198   {
 199     for (Entry<Integer, int[]> map : mapping.entrySet())
 200     {
 201       if (pdbResNum == map.getValue()[PDB_RES_NUM_INDEX])
 202       {
 203         return map.getKey();
 204       }
 205     }
 206     return UNASSIGNED;
 207   }
 208
 209   /**
 210    * transfer a copy of an alignment annotation row in the PDB chain coordinate
 211    * system onto the mapped sequence
 212    *
 213    * @param ana
 214    * @return the copy that was remapped to the mapped sequence
 215    * @note this method will create a copy and add it to the dataset sequence for
 216    *       the mapped sequence as well as the mapped sequence (if it is not a
 217    *       dataset sequence).
 218    */
 219   public AlignmentAnnotation transfer(AlignmentAnnotation ana)
 220   {
 221     AlignmentAnnotation ala_copy = new AlignmentAnnotation(ana);
 222     SequenceI ds = sequence;
 223     while (ds.getDatasetSequence() != null)
 224     {
 225       ds = ds.getDatasetSequence();
 226     }
 227     // need to relocate annotation from pdb coordinates to local sequence
 228     // -1,-1 doesn't look at pdbresnum but fails to remap sequence positions...
 229
 230     ala_copy.remap(ds, mapping, -1, -1, 0);
 231     ds.addAlignmentAnnotation(ala_copy);
 232     if (ds != sequence)
 233     {
 234       // mapping wasn't to an original dataset sequence, so we make a copy on
 235       // the mapped sequence too
 236       ala_copy = new AlignmentAnnotation(ala_copy);
 237       sequence.addAlignmentAnnotation(ala_copy);
 238     }
 239     return ala_copy;
 240   }
 241
 242   public String getMappingDetailsOutput()
 243   {
 244     return mappingDetails;
 245   }
 246
 247 }