2 * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3 * Copyright (C) $$Year-Rel$$ The Jalview Authors
5 * This file is part of Jalview.
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.
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.
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.
21 package jalview.analysis;
23 import java.util.Locale;
25 import jalview.analysis.scoremodels.ScoreMatrix;
26 import jalview.analysis.scoremodels.ScoreModels;
27 import jalview.api.analysis.ScoreModelI;
28 import jalview.datamodel.AlignmentAnnotation;
29 import jalview.datamodel.Annotation;
30 import jalview.datamodel.ResidueCount;
31 import jalview.datamodel.ResidueCount.SymbolCounts;
32 import jalview.datamodel.Sequence;
33 import jalview.datamodel.SequenceI;
34 import jalview.schemes.ResidueProperties;
35 import jalview.util.Comparison;
36 import jalview.util.Format;
38 import java.awt.Color;
39 import java.util.List;
41 import java.util.Map.Entry;
42 import java.util.SortedMap;
43 import java.util.TreeMap;
44 import java.util.Vector;
47 * Calculates conservation values for a given set of sequences
49 public class Conservation
52 * need to have a minimum of 3% of sequences with a residue
53 * for it to be included in the conservation calculation
55 private static final int THRESHOLD_PERCENT = 3;
57 private static final int TOUPPERCASE = 'a' - 'A';
59 private static final int GAP_INDEX = -1;
61 private static final Format FORMAT_3DP = new Format("%2.5f");
63 SequenceI[] sequences;
70 * a list whose i'th element is an array whose first entry is the checksum
71 * of the i'th sequence, followed by residues encoded to score matrix index
73 Vector<int[]> seqNums;
75 int maxLength = 0; // used by quality calcs
77 boolean seqNumsChanged = false; // updated after any change via calcSeqNum;
80 * a map per column with {property, conservation} where conservation value is
81 * 1 (property is conserved), 0 (absence of property is conserved) or -1
82 * (property is not conserved i.e. column has residues with and without it)
84 Map<String, Integer>[] total;
87 * if true then conservation calculation will map all symbols to canonical aa
88 * numbering rather than consider conservation of that symbol
90 boolean canonicaliseAa = true;
92 private Vector<Double> quality;
94 private double qualityMinimum;
96 private double qualityMaximum;
98 private Sequence consSequence;
101 * percentage of residues in a column to qualify for counting conservation
103 private int threshold;
105 private String name = "";
108 * an array, for each column, of counts of symbols (by score matrix index)
110 private int[][] cons2;
113 * gap counts for each column
115 private int[] cons2GapCounts;
117 private String[] consSymbs;
120 * Constructor using default threshold of 3%
123 * Name of conservation
125 * sequences to be used in calculation
127 * start residue position
129 * end residue position
131 public Conservation(String name, List<SequenceI> sequences, int start,
134 this(name, THRESHOLD_PERCENT, sequences, start, end);
141 * Name of conservation
143 * percentage of sequences at or below which property conservation is
146 * sequences to be used in calculation
148 * start column position
150 * end column position
152 public Conservation(String name, int threshold, List<SequenceI> sequences,
156 this.threshold = threshold;
160 maxLength = end - start + 1; // default width includes bounds of
163 int s, sSize = sequences.size();
164 SequenceI[] sarray = new SequenceI[sSize];
165 this.sequences = sarray;
168 for (s = 0; s < sSize; s++)
170 sarray[s] = sequences.get(s);
171 if (sarray[s].getLength() > maxLength)
173 maxLength = sarray[s].getLength();
176 } catch (ArrayIndexOutOfBoundsException ex)
178 // bail - another thread has modified the sequence array, so the current
179 // calculation is probably invalid.
180 this.sequences = new SequenceI[0];
186 * Translate sequence i into score matrix indices and store it in the i'th
187 * position of the seqNums array.
192 private void calcSeqNum(int i, ScoreMatrix sm)
194 int sSize = sequences.length;
196 if ((i > -1) && (i < sSize))
198 String sq = sequences[i].getSequenceAsString();
200 if (seqNums.size() <= i)
202 seqNums.addElement(new int[sq.length() + 1]);
206 * the first entry in the array is the sequence's hashcode,
207 * following entries are matrix indices of sequence characters
209 if (sq.hashCode() != seqNums.elementAt(i)[0])
213 seqNumsChanged = true;
221 int[] sqnum = new int[len + 1]; // better to always make a new array -
222 // sequence can change its length
223 sqnum[0] = sq.hashCode();
225 for (j = 1; j <= len; j++)
227 // sqnum[j] = ResidueProperties.aaIndex[sq.charAt(j - 1)];
228 char residue = sq.charAt(j - 1);
229 if (Comparison.isGap(residue))
231 sqnum[j] = GAP_INDEX;
235 sqnum[j] = sm.getMatrixIndex(residue);
238 sqnum[j] = GAP_INDEX;
243 seqNums.setElementAt(sqnum, i);
247 jalview.bin.Console.outPrintln("SEQUENCE HAS BEEN DELETED!!!");
252 // JBPNote INFO level debug
253 jalview.bin.Console.errPrintln(
254 "ERROR: calcSeqNum called with out of range sequence index for Alignment\n");
259 * Calculates the conservation values for given set of sequences
261 public void calculate()
263 int height = sequences.length;
265 total = new Map[maxLength];
267 for (int column = start; column <= end; column++)
269 ResidueCount values = countResidues(column);
272 * percentage count at or below which we ignore residues
274 int thresh = (threshold * height) / 100;
277 * check observed residues in column and record whether each
278 * physico-chemical property is conserved (+1), absence conserved (0),
279 * or not conserved (-1)
280 * Using TreeMap means properties are displayed in alphabetical order
282 SortedMap<String, Integer> resultHash = new TreeMap<>();
283 SymbolCounts symbolCounts = values.getSymbolCounts();
284 char[] symbols = symbolCounts.symbols;
285 int[] counts = symbolCounts.values;
286 for (int j = 0; j < symbols.length; j++)
289 if (counts[j] > thresh)
291 recordConservation(resultHash, String.valueOf(c));
294 if (values.getGapCount() > thresh)
296 recordConservation(resultHash, "-");
299 if (total.length > 0)
301 total[column - start] = resultHash;
307 * Updates the conservation results for an observed residue
310 * a map of {property, conservation} where conservation value is +1
311 * (all residues have the property), 0 (no residue has the property)
312 * or -1 (some do, some don't)
315 protected static void recordConservation(Map<String, Integer> resultMap,
318 res = res.toUpperCase(Locale.ROOT);
319 for (Entry<String, Map<String, Integer>> property : ResidueProperties.propHash
322 String propertyName = property.getKey();
323 Integer residuePropertyValue = property.getValue().get(res);
325 if (!resultMap.containsKey(propertyName))
328 * first time we've seen this residue - note whether it has this property
330 if (residuePropertyValue != null)
332 resultMap.put(propertyName, residuePropertyValue);
337 * unrecognised residue - use default value for property
339 resultMap.put(propertyName, property.getValue().get("-"));
344 Integer currentResult = resultMap.get(propertyName);
345 if (currentResult.intValue() != -1
346 && !currentResult.equals(residuePropertyValue))
349 * property is unconserved - residues seen both with and without it
351 resultMap.put(propertyName, Integer.valueOf(-1));
358 * Counts residues (upper-cased) and gaps in the given column
363 protected ResidueCount countResidues(int column)
365 ResidueCount values = new ResidueCount(false);
367 for (int row = 0; row < sequences.length; row++)
369 if (sequences[row].getLength() > column)
371 char c = sequences[row].getCharAt(column);
374 int index = ResidueProperties.aaIndex[c];
375 c = index > 20 ? '-' : ResidueProperties.aa[index].charAt(0);
381 if (Comparison.isGap(c))
399 * Counts conservation and gaps for a column of the alignment
401 * @return { 1 if fully conserved, else 0, gap count }
403 public int[] countConservationAndGaps(int column)
406 boolean fullyConserved = true;
407 int iSize = sequences.length;
411 return new int[] { 0, 0 };
415 for (int i = 0; i < iSize; i++)
417 if (column >= sequences[i].getLength())
423 char c = sequences[i].getCharAt(column); // gaps do not have upper/lower
426 if (Comparison.isGap((c)))
439 fullyConserved = false;
444 int[] r = new int[] { fullyConserved ? 1 : 0, gapCount };
449 * Returns the upper-cased character if between 'a' and 'z', else the
455 char toUpperCase(char c)
457 if ('a' <= c && c <= 'z')
465 * Calculates the conservation sequence
467 * @param positiveOnly
468 * if true, calculate positive conservation; else calculate both
469 * positive and negative conservation
470 * @param maxPercentageGaps
471 * the percentage of gaps in a column, at or above which no
472 * conservation is asserted
474 public void verdict(boolean positiveOnly, float maxPercentageGaps)
476 // TODO call this at the end of calculate(), should not be a public method
478 StringBuilder consString = new StringBuilder(end);
480 // NOTE THIS SHOULD CHECK IF THE CONSEQUENCE ALREADY
481 // EXISTS AND NOT OVERWRITE WITH '-', BUT THIS CASE
482 // DOES NOT EXIST IN JALVIEW 2.1.2
483 for (int i = 0; i < start; i++)
485 consString.append('-');
487 consSymbs = new String[end - start + 1];
488 for (int i = start; i <= end; i++)
490 int[] gapcons = countConservationAndGaps(i);
491 boolean fullyConserved = gapcons[0] == 1;
492 int totGaps = gapcons[1];
493 float pgaps = (totGaps * 100f) / sequences.length;
495 if (maxPercentageGaps > pgaps)
497 Map<String, Integer> resultHash = total[i - start];
499 StringBuilder positives = new StringBuilder(64);
500 StringBuilder negatives = new StringBuilder(32);
501 for (String type : resultHash.keySet())
503 int result = resultHash.get(type).intValue();
507 * not conserved (present or absent)
515 * positively conserved property (all residues have it)
517 positives.append(positives.length() == 0 ? "" : " ");
518 positives.append(type);
520 if (result == 0 && !positiveOnly)
523 * absense of property is conserved (all residues lack it)
525 negatives.append(negatives.length() == 0 ? "" : " ");
526 negatives.append("!").append(type);
529 if (negatives.length() > 0)
531 positives.append(" ").append(negatives);
533 consSymbs[i - start] = positives.toString();
537 consString.append(count); // Conserved props!=Identity
541 consString.append(fullyConserved ? "*" : "+");
546 consString.append('-');
550 consSequence = new Sequence(name, consString.toString(), start, end);
556 * @return Conservation sequence
558 public SequenceI getConsSequence()
563 // From Alignment.java in jalview118
564 public void findQuality()
566 findQuality(0, maxLength - 1, getQualitySubstMat());
569 public ScoreMatrix getQualitySubstMat()
575 * default for quality calc is BLOSUM
577 private ScoreMatrix sm = ScoreModels.getInstance().getBlosum62();
580 * set the matrix used for calculating quality scores
583 * - must be a valid score matrix able to evaluate all amino acid
586 public void setQualitySubstMat(ScoreMatrix scoreMatrix)
588 if (scoreMatrix != null && scoreMatrix.isProtein())
599 private void percentIdentity(ScoreMatrix sm)
601 seqNums = new Vector<>();
602 int i = 0, iSize = sequences.length;
603 // Do we need to calculate this again?
604 for (i = 0; i < iSize; i++)
609 if ((cons2 == null) || seqNumsChanged)
611 // FIXME remove magic number 24 without changing calc
612 // sm.getSize() returns 25 so doesn't quite do it...
613 cons2 = new int[maxLength][24];
614 cons2GapCounts = new int[maxLength];
618 while (j < sequences.length)
620 int[] sqnum = seqNums.elementAt(j);
622 for (i = 1; i < sqnum.length; i++)
624 int index = sqnum[i];
625 if (index == GAP_INDEX)
627 cons2GapCounts[i - 1]++;
631 cons2[i - 1][index]++;
635 // TODO should this start from sqnum.length?
636 for (i = sqnum.length - 1; i < maxLength; i++)
646 * Calculates the quality of the set of sequences over the given inclusive
647 * column range, using the specified substitution score matrix
653 protected void findQuality(int startCol, int endCol,
654 ScoreMatrix scoreMatrix)
656 quality = new Vector<>();
658 double max = -Double.MAX_VALUE;
659 float[][] scores = scoreMatrix.getMatrix();
661 percentIdentity(scoreMatrix);
663 int size = seqNums.size();
664 int[] lengths = new int[size];
666 for (int l = 0; l < size; l++)
668 lengths[l] = seqNums.elementAt(l).length - 1;
671 final int symbolCount = scoreMatrix.getSize();
673 for (int j = startCol; j <= endCol; j++)
677 // First Xr = depends on column only
678 double[] x = new double[symbolCount];
680 for (int ii = 0; ii < symbolCount; ii++)
685 * todo JAL-728 currently assuming last symbol in matrix is * for gap
686 * (which we ignore as counted separately); true for BLOSUM62 but may
687 * not be once alternative matrices are supported
689 for (int i2 = 0; i2 < symbolCount - 1; i2++)
691 x[ii] += (((double) cons2[j][i2] * scores[ii][i2]) + 4D);
693 x[ii] += 4D + cons2GapCounts[j] * scoreMatrix.getMinimumScore();
698 // Now calculate D for each position and sum
699 for (int k = 0; k < size; k++)
702 double[] xx = new double[symbolCount];
703 // sequence character index, or implied gap if sequence too short
704 int seqNum = (j < lengths[k]) ? seqNums.elementAt(k)[j + 1]
707 for (int i = 0; i < symbolCount - 1; i++)
710 if (seqNum == GAP_INDEX)
712 sr += scoreMatrix.getMinimumScore();
716 sr += scores[i][seqNum];
721 tot += (xx[i] * xx[i]);
724 bigtot += Math.sqrt(tot);
727 max = Math.max(max, bigtot);
729 quality.addElement(Double.valueOf(bigtot));
732 double newmax = -Double.MAX_VALUE;
734 for (int j = startCol; j <= endCol; j++)
736 double tmp = quality.elementAt(j).doubleValue();
737 // tmp = ((max - tmp) * (size - cons2[j][23])) / size;
738 tmp = ((max - tmp) * (size - cons2GapCounts[j])) / size;
740 // jalview.bin.Console.outPrintln(tmp+ " " + j);
741 quality.setElementAt(Double.valueOf(tmp), j);
750 qualityMaximum = newmax;
754 * Complete the given consensus and quuality annotation rows. Note: currently
755 * this method will reallocate the given annotation row if it is different to
756 * the calculated width, otherwise will leave its length unchanged.
758 * @param conservation
759 * conservation annotation row
761 * (optional - may be null)
763 * first column for conservation
765 * extent of conservation
767 public void completeAnnotations(AlignmentAnnotation conservation,
768 AlignmentAnnotation quality2, int istart, int alWidth)
770 SequenceI cons = getConsSequence();
773 * colour scale for Conservation and Quality;
778 float maxR = 1.0f - minR;
779 float maxG = 0.9f - minG;
780 float maxB = 0f - minB;
787 if (conservation != null && conservation.annotations != null
788 && conservation.annotations.length != alWidth)
790 conservation.annotations = new Annotation[alWidth];
793 if (quality2 != null)
795 quality2.graphMax = (float) qualityMaximum;
796 if (quality2.annotations != null
797 && quality2.annotations.length != alWidth)
799 quality2.annotations = new Annotation[alWidth];
801 qmin = (float) qualityMinimum;
802 qmax = (float) qualityMaximum;
805 for (int i = istart; i < alWidth; i++)
809 char c = cons.getCharAt(i);
811 if (Character.isDigit(c))
824 if (conservation != null)
826 float vprop = value - min;
828 int consp = i - start;
829 String conssym = (value > 0 && consp > -1
830 && consp < consSymbs.length) ? consSymbs[consp] : "";
831 conservation.annotations[i] = new Annotation(String.valueOf(c),
832 conssym, ' ', value, new Color(minR + (maxR * vprop),
833 minG + (maxG * vprop), minB + (maxB * vprop)));
837 if (quality2 != null)
839 value = quality.elementAt(i).floatValue();
840 float vprop = value - qmin;
842 String description = FORMAT_3DP.form(value);
843 quality2.annotations[i] = new Annotation(" ", description, ' ',
844 value, new Color(minR + (maxR * vprop),
845 minG + (maxG * vprop), minB + (maxB * vprop)));
851 * construct and call the calculation methods on a new Conservation object
854 * - name of conservation
857 * first column in calculation window
859 * last column in calculation window
860 * @param positiveOnly
861 * calculate positive (true) or positive and negative (false)
863 * @param maxPercentGaps
864 * percentage of gaps tolerated in column
866 * flag indicating if alignment quality should be calculated
867 * @return Conservation object ready for use in visualization
869 public static Conservation calculateConservation(String name,
870 List<SequenceI> seqs, int start, int end, boolean positiveOnly,
871 int maxPercentGaps, boolean calcQuality)
873 return calculateConservation(name, seqs, start, end, positiveOnly,
874 maxPercentGaps, calcQuality, null);
878 * construct and call the calculation methods on a new Conservation object
881 * - name of conservation
884 * first column in calculation window
886 * last column in calculation window
887 * @param positiveOnly
888 * calculate positive (true) or positive and negative (false)
890 * @param maxPercentGaps
891 * percentage of gaps tolerated in column
893 * flag indicating if alignment quality should be calculated
895 * - null or peptide score matrix used for quality calculation
896 * @return Conservation object ready for use in visualization
898 public static Conservation calculateConservation(String name,
899 List<SequenceI> seqs, int start, int end, boolean positiveOnly,
900 int maxPercentGaps, boolean calcQuality, ScoreMatrix scoreMatrix)
902 Conservation cons = new Conservation(name, seqs, start, end);
903 if (scoreMatrix != null)
905 cons.setQualitySubstMat(scoreMatrix);
908 cons.verdict(positiveOnly, maxPercentGaps);
919 * Returns the computed tooltip (annotation description) for a given column.
920 * The tip is empty if the conservation score is zero, otherwise holds the
921 * conserved properties (and, optionally, properties whose absence is
927 String getTooltip(int column)
929 SequenceI cons = getConsSequence();
930 char val = column < cons.getLength() ? cons.getCharAt(column) : '-';
931 boolean hasConservation = val != '-' && val != '0';
932 int consp = column - start;
933 String tip = (hasConservation && consp > -1 && consp < consSymbs.length)