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 jalview.analysis.scoremodels.PairwiseSeqScoreModel;
24 import jalview.analysis.scoremodels.ScoreModels;
25 import jalview.datamodel.AlignmentAnnotation;
26 import jalview.datamodel.Annotation;
27 import jalview.datamodel.ResidueCount;
28 import jalview.datamodel.ResidueCount.SymbolCounts;
29 import jalview.datamodel.Sequence;
30 import jalview.datamodel.SequenceI;
31 import jalview.schemes.ResidueProperties;
32 import jalview.util.Comparison;
34 import java.awt.Color;
35 import java.util.List;
37 import java.util.Map.Entry;
38 import java.util.SortedMap;
39 import java.util.TreeMap;
40 import java.util.Vector;
43 * Calculates conservation values for a given set of sequences
45 public class Conservation
48 * need to have a minimum of 3% of sequences with a residue
49 * for it to be included in the conservation calculation
51 private static final int THRESHOLD_PERCENT = 3;
53 private static final int TOUPPERCASE = 'a' - 'A';
55 SequenceI[] sequences;
61 Vector<int[]> seqNums; // vector of int vectors where first is sequence
64 int maxLength = 0; // used by quality calcs
66 boolean seqNumsChanged = false; // updated after any change via calcSeqNum;
69 * a map per column with {property, conservation} where conservation value is
70 * 1 (property is conserved), 0 (absence of property is conserved) or -1
71 * (property is not conserved i.e. column has residues with and without it)
73 Map<String, Integer>[] total;
75 boolean canonicaliseAa = true; // if true then conservation calculation will
77 // map all symbols to canonical aa numbering
78 // rather than consider conservation of that
81 /** Stores calculated quality values */
82 private Vector<Double> quality;
84 /** Stores maximum and minimum values of quality values */
85 private double[] qualityRange = new double[2];
87 private Sequence consSequence;
90 * percentage of residues in a column to qualify for counting conservation
92 private int threshold;
94 private String name = "";
96 private int[][] cons2;
98 private String[] consSymbs;
101 * Constructor using default threshold of 3%
104 * Name of conservation
106 * sequences to be used in calculation
108 * start residue position
110 * end residue position
112 public Conservation(String name, List<SequenceI> sequences, int start,
115 this(name, THRESHOLD_PERCENT, sequences, start, end);
122 * Name of conservation
124 * percentage of sequences at or below which property conservation is
127 * sequences to be used in calculation
129 * start column position
131 * end column position
133 public Conservation(String name, int threshold,
134 List<SequenceI> sequences, int start, int end)
137 this.threshold = threshold;
141 maxLength = end - start + 1; // default width includes bounds of
144 int s, sSize = sequences.size();
145 SequenceI[] sarray = new SequenceI[sSize];
146 this.sequences = sarray;
149 for (s = 0; s < sSize; s++)
151 sarray[s] = sequences.get(s);
152 if (sarray[s].getLength() > maxLength)
154 maxLength = sarray[s].getLength();
157 } catch (ArrayIndexOutOfBoundsException ex)
159 // bail - another thread has modified the sequence array, so the current
160 // calculation is probably invalid.
161 this.sequences = new SequenceI[0];
167 * Translate sequence i into a numerical representation and store it in the
168 * i'th position of the seqNums array.
172 private void calcSeqNum(int i)
174 String sq = null; // for dumb jbuilder not-inited exception warning
177 int sSize = sequences.length;
179 if ((i > -1) && (i < sSize))
181 sq = sequences[i].getSequenceAsString();
183 if (seqNums.size() <= i)
185 seqNums.addElement(new int[sq.length() + 1]);
188 if (sq.hashCode() != seqNums.elementAt(i)[0])
192 seqNumsChanged = true;
200 sqnum = new int[len + 1]; // better to always make a new array -
201 // sequence can change its length
202 sqnum[0] = sq.hashCode();
204 for (j = 1; j <= len; j++)
206 sqnum[j] = jalview.schemes.ResidueProperties.aaIndex[sq
210 seqNums.setElementAt(sqnum, i);
214 System.out.println("SEQUENCE HAS BEEN DELETED!!!");
219 // JBPNote INFO level debug
221 .println("ERROR: calcSeqNum called with out of range sequence index for Alignment\n");
226 * Calculates the conservation values for given set of sequences
228 public void calculate()
230 int height = sequences.length;
232 total = new Map[maxLength];
234 for (int column = start; column <= end; column++)
236 ResidueCount values = countResidues(column);
239 * percentage count at or below which we ignore residues
241 int thresh = (threshold * height) / 100;
244 * check observed residues in column and record whether each
245 * physico-chemical property is conserved (+1), absence conserved (0),
246 * or not conserved (-1)
247 * Using TreeMap means properties are displayed in alphabetical order
249 SortedMap<String, Integer> resultHash = new TreeMap<String, Integer>();
250 SymbolCounts symbolCounts = values.getSymbolCounts();
251 char[] symbols = symbolCounts.symbols;
252 int[] counts = symbolCounts.values;
253 for (int j = 0; j < symbols.length; j++)
256 if (counts[j] > thresh)
258 recordConservation(resultHash, String.valueOf(c));
261 if (values.getGapCount() > thresh)
263 recordConservation(resultHash, "-");
266 if (total.length > 0)
268 total[column - start] = resultHash;
274 * Updates the conservation results for an observed residue
277 * a map of {property, conservation} where conservation value is +1
278 * (all residues have the property), 0 (no residue has the property)
279 * or -1 (some do, some don't)
282 protected static void recordConservation(Map<String, Integer> resultMap,
285 res = res.toUpperCase();
286 for (Entry<String, Map<String, Integer>> property : ResidueProperties.propHash
289 String propertyName = property.getKey();
290 Integer residuePropertyValue = property.getValue().get(res);
292 if (!resultMap.containsKey(propertyName))
295 * first time we've seen this residue - note whether it has this property
297 if (residuePropertyValue != null)
299 resultMap.put(propertyName, residuePropertyValue);
304 * unrecognised residue - use default value for property
306 resultMap.put(propertyName, property.getValue().get("-"));
311 Integer currentResult = resultMap.get(propertyName);
312 if (currentResult.intValue() != -1
313 && !currentResult.equals(residuePropertyValue))
316 * property is unconserved - residues seen both with and without it
318 resultMap.put(propertyName, Integer.valueOf(-1));
325 * Counts residues (upper-cased) and gaps in the given column
330 protected ResidueCount countResidues(int column)
332 ResidueCount values = new ResidueCount(false);
334 for (int row = 0; row < sequences.length; row++)
336 if (sequences[row].getLength() > column)
338 char c = sequences[row].getCharAt(column);
341 int index = ResidueProperties.aaIndex[c];
342 c = index > 20 ? '-' : ResidueProperties.aa[index].charAt(0);
348 if (Comparison.isGap(c))
366 * Counts conservation and gaps for a column of the alignment
368 * @return { 1 if fully conserved, else 0, gap count }
370 public int[] countConservationAndGaps(int column)
373 boolean fullyConserved = true;
374 int iSize = sequences.length;
378 return new int[] { 0, 0 };
382 for (int i = 0; i < iSize; i++)
384 if (column >= sequences[i].getLength())
390 char c = sequences[i].getCharAt(column); // gaps do not have upper/lower case
392 if (Comparison.isGap((c)))
405 fullyConserved = false;
410 int[] r = new int[] { fullyConserved ? 1 : 0, gapCount };
415 * Returns the upper-cased character if between 'a' and 'z', else the
421 char toUpperCase(char c)
423 if ('a' <= c && c <= 'z')
431 * Calculates the conservation sequence
433 * @param positiveOnly
434 * if true, calculate positive conservation; else calculate both
435 * positive and negative conservation
436 * @param maxPercentageGaps
437 * the percentage of gaps in a column, at or above which no
438 * conservation is asserted
440 public void verdict(boolean positiveOnly, float maxPercentageGaps)
442 // TODO call this at the end of calculate(), should not be a public method
444 StringBuilder consString = new StringBuilder(end);
446 // NOTE THIS SHOULD CHECK IF THE CONSEQUENCE ALREADY
447 // EXISTS AND NOT OVERWRITE WITH '-', BUT THIS CASE
448 // DOES NOT EXIST IN JALVIEW 2.1.2
449 for (int i = 0; i < start; i++)
451 consString.append('-');
453 consSymbs = new String[end - start + 1];
454 for (int i = start; i <= end; i++)
456 int[] gapcons = countConservationAndGaps(i);
457 boolean fullyConserved = gapcons[0] == 1;
458 int totGaps = gapcons[1];
459 float pgaps = (totGaps * 100f) / sequences.length;
461 if (maxPercentageGaps > pgaps)
463 Map<String, Integer> resultHash = total[i - start];
465 StringBuilder positives = new StringBuilder(64);
466 StringBuilder negatives = new StringBuilder(32);
467 for (String type : resultHash.keySet())
469 int result = resultHash.get(type).intValue();
473 * not conserved (present or absent)
481 * positively conserved property (all residues have it)
483 positives.append(positives.length() == 0 ? "" : " ");
484 positives.append(type);
486 if (result == 0 && !positiveOnly)
489 * absense of property is conserved (all residues lack it)
491 negatives.append(negatives.length() == 0 ? "" : " ");
492 negatives.append("!").append(type);
495 if (negatives.length() > 0)
497 positives.append(" ").append(negatives);
499 consSymbs[i - start] = positives.toString();
503 consString.append(count); // Conserved props!=Identity
507 consString.append(fullyConserved ? "*" : "+");
512 consString.append('-');
516 consSequence = new Sequence(name, consString.toString(), start, end);
522 * @return Conservation sequence
524 public SequenceI getConsSequence()
529 // From Alignment.java in jalview118
530 public void findQuality()
532 findQuality(0, maxLength - 1);
538 private void percentIdentity2()
540 seqNums = new Vector<int[]>();
542 int i = 0, iSize = sequences.length;
543 // Do we need to calculate this again?
544 for (i = 0; i < iSize; i++)
549 if ((cons2 == null) || seqNumsChanged)
551 cons2 = new int[maxLength][24];
553 // Initialize the array
554 for (int j = 0; j < 24; j++)
556 for (i = 0; i < maxLength; i++)
565 while (j < sequences.length)
567 sqnum = seqNums.elementAt(j);
569 for (i = 1; i < sqnum.length; i++)
571 cons2[i - 1][sqnum[i]]++;
574 for (i = sqnum.length - 1; i < maxLength; i++)
576 cons2[i][23]++; // gap count
585 * for (int i=start; i <= end; i++) { int max = -1000; int maxi = -1; int
588 * for (int j=0;j<24;j++) { if (cons2[i][j] > max) { max = cons2[i][j];
589 * maxi = i; maxj = j; } } }
595 * Calculates the quality of the set of sequences
602 public void findQuality(int startRes, int endRes)
604 quality = new Vector<Double>();
607 float[][] BLOSUM62 = ((PairwiseSeqScoreModel) ScoreModels.getInstance()
608 .forName(ScoreModels.BLOSUM62)).getMatrix();
610 // Loop over columns // JBPNote Profiling info
611 // long ts = System.currentTimeMillis();
612 // long te = System.currentTimeMillis();
615 int size = seqNums.size();
616 int[] lengths = new int[size];
617 double tot, bigtot, sr, tmp;
619 int l, j, i, ii, i2, k, seqNum;
621 for (l = 0; l < size; l++)
623 lengths[l] = seqNums.elementAt(l).length - 1;
626 for (j = startRes; j <= endRes; j++)
630 // First Xr = depends on column only
633 for (ii = 0; ii < 24; ii++)
637 for (i2 = 0; i2 < 24; i2++)
639 x[ii] += (((double) cons2[j][i2] * BLOSUM62[ii][i2]) + 4);
645 // Now calculate D for each position and sum
646 for (k = 0; k < size; k++)
650 seqNum = (j < lengths[k]) ? seqNums.elementAt(k)[j + 1] : 23; // Sequence,
655 // This is a loop over r
656 for (i = 0; i < 23; i++)
660 sr = (double) BLOSUM62[i][seqNum] + 4;
662 // Calculate X with another loop over residues
663 // System.out.println("Xi " + i + " " + x[i] + " " + sr);
666 tot += (xx[i] * xx[i]);
669 bigtot += Math.sqrt(tot);
672 // This is the quality for one column
678 // bigtot = bigtot * (size-cons2[j][23])/size;
679 quality.addElement(new Double(bigtot));
681 // Need to normalize by gaps
684 double newmax = -10000;
686 for (j = startRes; j <= endRes; j++)
688 tmp = quality.elementAt(j).doubleValue();
689 tmp = ((max - tmp) * (size - cons2[j][23])) / size;
691 // System.out.println(tmp+ " " + j);
692 quality.setElementAt(new Double(tmp), j);
700 // System.out.println("Quality " + s);
701 qualityRange[0] = 0D;
702 qualityRange[1] = newmax;
706 * Complete the given consensus and quuality annotation rows. Note: currently
707 * this method will enlarge the given annotation row if it is too small,
708 * otherwise will leave its length unchanged.
710 * @param conservation
711 * conservation annotation row
713 * (optional - may be null)
715 * first column for conservation
717 * extent of conservation
719 public void completeAnnotations(AlignmentAnnotation conservation,
720 AlignmentAnnotation quality2, int istart, int alWidth)
722 char[] sequence = getConsSequence().getSequence();
734 maxB = 0f - minB; // scalable range for colouring both Conservation and
744 if (conservation != null && conservation.annotations != null
745 && conservation.annotations.length < alWidth)
747 conservation.annotations = new Annotation[alWidth];
750 if (quality2 != null)
752 quality2.graphMax = (float) qualityRange[1];
753 if (quality2.annotations != null
754 && quality2.annotations.length < alWidth)
756 quality2.annotations = new Annotation[alWidth];
758 qmin = (float) qualityRange[0];
759 qmax = (float) qualityRange[1];
762 for (int i = istart; i < alWidth; i++)
768 if (Character.isDigit(c))
781 if (conservation != null)
783 float vprop = value - min;
785 int consp = i - start;
786 String conssym = (value > 0 && consp > -1 && consp < consSymbs.length) ? consSymbs[consp]
788 conservation.annotations[i] = new Annotation(String.valueOf(c),
789 conssym, ' ', value, new Color(minR + (maxR * vprop), minG
790 + (maxG * vprop), minB + (maxB * vprop)));
794 if (quality2 != null)
796 value = quality.elementAt(i).floatValue();
797 float vprop = value - qmin;
799 quality2.annotations[i] = new Annotation(" ",
800 String.valueOf(value), ' ', value, new Color(minR
801 + (maxR * vprop), minG + (maxG * vprop), minB
808 * construct and call the calculation methods on a new Conservation object
811 * - name of conservation
814 * first column in calculation window
816 * last column in calculation window
817 * @param positiveOnly
818 * calculate positive (true) or positive and negative (false)
820 * @param maxPercentGaps
821 * percentage of gaps tolerated in column
823 * flag indicating if alignment quality should be calculated
824 * @return Conservation object ready for use in visualization
826 public static Conservation calculateConservation(String name,
827 List<SequenceI> seqs, int start, int end, boolean positiveOnly,
828 int maxPercentGaps, boolean calcQuality)
830 Conservation cons = new Conservation(name, seqs, start, end);
832 cons.verdict(positiveOnly, maxPercentGaps);
843 * Returns the computed tooltip (annotation description) for a given column.
844 * The tip is empty if the conservation score is zero, otherwise holds the
845 * conserved properties (and, optionally, properties whose absence is
851 String getTooltip(int column)
853 char[] sequence = getConsSequence().getSequence();
854 char val = column < sequence.length ? sequence[column] : '-';
855 boolean hasConservation = val != '-' && val != '0';
856 int consp = column - start;
857 String tip = (hasConservation && consp > -1 && consp < consSymbs.length) ? consSymbs[consp]