src/jalview/analysis/scoremodels/PIDModel.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.analysis.scoremodels;
  22
  23 import jalview.api.AlignmentViewPanel;
  24 import jalview.api.analysis.PairwiseScoreModelI;
  25 import jalview.api.analysis.ScoreModelI;
  26 import jalview.api.analysis.SimilarityParamsI;
  27 import jalview.datamodel.AlignmentView;
  28 import jalview.math.Matrix;
  29 import jalview.math.MatrixI;
  30 import jalview.util.Comparison;
  31
  32 /**
  33  * A class to provide sequence pairwise similarity based on residue identity.
  34  * Instances of this class are immutable and thread-safe, so the same object is
  35  * returned from calls to getInstance().
  36  */
  37 public class PIDModel extends SimilarityScoreModel
  38         implements PairwiseScoreModelI
  39 {
  40   private static final String NAME = "PID";
  41
  42   /**
  43    * Constructor
  44    */
  45   public PIDModel()
  46   {
  47   }
  48
  49   @Override
  50   public String getName()
  51   {
  52     return NAME;
  53   }
  54
  55   /**
  56    * Answers null for description. If a display name is needed, use getName() or
  57    * an internationalized string built from the name.
  58    */
  59   @Override
  60   public String getDescription()
  61   {
  62     return null;
  63   }
  64
  65   @Override
  66   public boolean isDNA()
  67   {
  68     return true;
  69   }
  70
  71   @Override
  72   public boolean isProtein()
  73   {
  74     return true;
  75   }
  76
  77   /**
  78    * Answers 1 if c and d are the same residue (ignoring case), and not gap
  79    * characters. Answers 0 for non-matching or gap characters.
  80    */
  81   @Override
  82   public float getPairwiseScore(char c, char d)
  83   {
  84     c = toUpper(c);
  85     d = toUpper(d);
  86     if (c == d && !Comparison.isGap(c))
  87     {
  88       return 1f;
  89     }
  90     return 0f;
  91   }
  92
  93   /**
  94    * @param c
  95    */
  96   protected static char toUpper(char c)
  97   {
  98     if ('a' <= c && c <= 'z')
  99     {
 100       c += 'A' - 'a';
 101     }
 102     return c;
 103   }
 104
 105   /**
 106    * Computes similarity scores based on pairwise percentage identity of
 107    * sequences. For consistency with Jalview 2.10.1's SeqSpace mode PCA
 108    * calculation, the percentage scores are rescaled to the width of the
 109    * sequences (as if counts of identical residues). This method is thread-safe.
 110    */
 111   @Override
 112   public MatrixI findSimilarities(AlignmentView seqData,
 113           SimilarityParamsI options)
 114   {
 115     String[] seqs = seqData.getSequenceStrings(Comparison.GAP_DASH);
 116
 117     MatrixI result = findSimilarities(seqs, options);
 118
 119     result.multiply(seqData.getWidth() / 100d);
 120
 121     return result;
 122   }
 123
 124   /**
 125    * A distance score is computed in the usual way (by reversing the range of
 126    * the similarity score results), and then rescaled to percentage values
 127    * (reversing the rescaling to count values done in findSimilarities). This
 128    * method is thread-safe.
 129    */
 130   @Override
 131   public MatrixI findDistances(AlignmentView seqData,
 132           SimilarityParamsI options)
 133   {
 134     MatrixI result = super.findDistances(seqData, options);
 135
 136     if (seqData.getWidth() != 0)
 137     {
 138       result.multiply(100d / seqData.getWidth());
 139     }
 140
 141     return result;
 142   }
 143
 144   /**
 145    * Compute percentage identity scores, using the gap treatment and
 146    * normalisation specified by the options parameter
 147    *
 148    * @param seqs
 149    * @param options
 150    * @return
 151    */
 152   protected MatrixI findSimilarities(String[] seqs,
 153           SimilarityParamsI options)
 154   {
 155     /*
 156      * calculation is symmetric so just compute lower diagonal
 157      */
 158     double[][] values = new double[seqs.length][seqs.length];
 159     for (int row = 0; row < seqs.length; row++)
 160     {
 161       for (int col = row; col < seqs.length; col++)
 162       {
 163         double total = computePID(seqs[row], seqs[col], options);
 164         values[row][col] = total;
 165         values[col][row] = total;
 166       }
 167     }
 168     return new Matrix(values);
 169   }
 170
 171   /**
 172    * Computes a percentage identity for two sequences, using the algorithm
 173    * choices specified by the options parameter
 174    *
 175    * @param seq1
 176    * @param seq2
 177    * @param options
 178    * @return
 179    */
 180   public static double computePID(String seq1, String seq2,
 181           SimilarityParamsI options)
 182   {
 183     int len1 = seq1.length();
 184     int len2 = seq2.length();
 185     int width = Math.max(len1, len2);
 186     int total = 0;
 187     int divideBy = 0;
 188
 189     for (int i = 0; i < width; i++)
 190     {
 191       if (i >= len1 || i >= len2)
 192       {
 193         /*
 194          * off the end of one sequence; stop if we are only matching
 195          * on the shorter sequence length, else treat as trailing gap
 196          */
 197         if (options.denominateByShortestLength())
 198         {
 199           break;
 200         }
 201         if (options.includeGaps())
 202         {
 203           divideBy++;
 204         }
 205         if (options.matchGaps())
 206         {
 207           total++;
 208         }
 209         continue;
 210       }
 211       char c1 = seq1.charAt(i);
 212       char c2 = seq2.charAt(i);
 213       boolean gap1 = Comparison.isGap(c1);
 214       boolean gap2 = Comparison.isGap(c2);
 215
 216       if (gap1 && gap2)
 217       {
 218         /*
 219          * gap-gap: include if options say so, if so
 220          * have to score as identity; else ignore
 221          */
 222         if (options.includeGappedColumns())
 223         {
 224           divideBy++;
 225           total++;
 226         }
 227         continue;
 228       }
 229
 230       if (gap1 || gap2)
 231       {
 232         /*
 233          * gap-residue: include if options say so,
 234          * count as match if options say so
 235          */
 236         if (options.includeGaps())
 237         {
 238           divideBy++;
 239         }
 240         if (options.matchGaps())
 241         {
 242           total++;
 243         }
 244         continue;
 245       }
 246
 247       /*
 248        * remaining case is gap-residue
 249        */
 250       if (toUpper(c1) == toUpper(c2))
 251       {
 252         total++;
 253       }
 254       divideBy++;
 255     }
 256
 257     return divideBy == 0 ? 0D : 100D * total / divideBy;
 258   }
 259
 260   @Override
 261   public ScoreModelI getInstance(AlignmentViewPanel avp)
 262   {
 263     return this;
 264   }
 265 }