1aa29e0f85885efa9223338770df8ec4154ac5c1
[jalview.git] / Conservation.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;
22
23 import java.awt.Color;
24 import java.util.*;
25
26 import jalview.datamodel.*;
27
28 /**
29  * Calculates conservation values for a given set of sequences
30  * 
31  * @author $author$
32  * @version $Revision$
33  */
34 public class Conservation
35 {
36   SequenceI[] sequences;
37
38   int start;
39
40   int end;
41
42   Vector seqNums; // vector of int vectors where first is sequence checksum
43
44   int maxLength = 0; // used by quality calcs
45
46   boolean seqNumsChanged = false; // updated after any change via calcSeqNum;
47
48   Hashtable[] total;
49
50   boolean canonicaliseAa = true; // if true then conservation calculation will
51
52   // map all symbols to canonical aa numbering
53   // rather than consider conservation of that
54   // symbol
55
56   /** Stores calculated quality values */
57   public Vector quality;
58
59   /** Stores maximum and minimum values of quality values */
60   public Double[] qualityRange = new Double[2];
61
62   String consString = "";
63
64   Sequence consSequence;
65
66   Hashtable propHash;
67
68   int threshold;
69
70   String name = "";
71
72   int[][] cons2;
73
74   private String[] consSymbs;
75
76   /**
77    * Creates a new Conservation object.
78    * 
79    * @param name
80    *          Name of conservation
81    * @param propHash
82    *          hash of properties for each symbol
83    * @param threshold
84    *          to count the residues in residueHash(). commonly used value is 3
85    * @param sequences
86    *          sequences to be used in calculation
87    * @param start
88    *          start residue position
89    * @param end
90    *          end residue position
91    */
92   public Conservation(String name, Hashtable propHash, int threshold,
93           List<SequenceI> sequences, int start, int end)
94   {
95     this.name = name;
96     this.propHash = propHash;
97     this.threshold = threshold;
98     this.start = start;
99     this.end = end;
100
101     maxLength = end - start + 1; // default width includes bounds of
102     // calculation
103
104     int s, sSize = sequences.size();
105     SequenceI[] sarray = new SequenceI[sSize];
106     this.sequences = sarray;
107     try
108     {
109       for (s = 0; s < sSize; s++)
110       {
111         sarray[s] = (SequenceI) sequences.get(s);
112         if (sarray[s].getLength() > maxLength)
113         {
114           maxLength = sarray[s].getLength();
115         }
116       }
117     } catch (ArrayIndexOutOfBoundsException ex)
118     {
119       // bail - another thread has modified the sequence array, so the current
120       // calculation is probably invalid.
121       this.sequences = new SequenceI[0];
122       maxLength = 0;
123     }
124   }
125
126   /**
127    * Translate sequence i into a numerical representation and store it in the
128    * i'th position of the seqNums array.
129    * 
130    * @param i
131    */
132   private void calcSeqNum(int i)
133   {
134     String sq = null; // for dumb jbuilder not-inited exception warning
135     int[] sqnum = null;
136
137     int sSize = sequences.length;
138
139     if ((i > -1) && (i < sSize))
140     {
141       sq = sequences[i].getSequenceAsString();
142
143       if (seqNums.size() <= i)
144       {
145         seqNums.addElement(new int[sq.length() + 1]);
146       }
147
148       if (sq.hashCode() != ((int[]) seqNums.elementAt(i))[0])
149       {
150         int j;
151         int len;
152         seqNumsChanged = true;
153         len = sq.length();
154
155         if (maxLength < len)
156         {
157           maxLength = len;
158         }
159
160         sqnum = new int[len + 1]; // better to always make a new array -
161         // sequence can change its length
162         sqnum[0] = sq.hashCode();
163
164         for (j = 1; j <= len; j++)
165         {
166           sqnum[j] = jalview.schemes.ResidueProperties.aaIndex[sq
167                   .charAt(j - 1)];
168         }
169
170         seqNums.setElementAt(sqnum, i);
171       }
172       else
173       {
174         System.out.println("SEQUENCE HAS BEEN DELETED!!!");
175       }
176     }
177     else
178     {
179       // JBPNote INFO level debug
180       System.err
181               .println("ERROR: calcSeqNum called with out of range sequence index for Alignment\n");
182     }
183   }
184
185   /**
186    * Calculates the conservation values for given set of sequences
187    */
188   public void calculate()
189   {
190     Hashtable resultHash, ht;
191     int thresh, j, jSize = sequences.length;
192     int[] values; // Replaces residueHash
193     String type, res = null;
194     char c;
195     Enumeration enumeration2;
196
197     total = new Hashtable[maxLength];
198
199     for (int i = start; i <= end; i++)
200     {
201       values = new int[255];
202
203       for (j = 0; j < jSize; j++)
204       {
205         if (sequences[j].getLength() > i)
206         {
207           c = sequences[j].getCharAt(i);
208
209           if (canonicaliseAa)
210           { // lookup the base aa code symbol
211             c = (char) jalview.schemes.ResidueProperties.aaIndex[sequences[j]
212                     .getCharAt(i)];
213             if (c > 20)
214             {
215               c = '-';
216             }
217             else
218             {
219               // recover canonical aa symbol
220               c = jalview.schemes.ResidueProperties.aa[c].charAt(0);
221             }
222           }
223           else
224           {
225             // original behaviour - operate on ascii symbols directly
226             // No need to check if its a '-'
227             if (c == '.' || c == ' ')
228             {
229               c = '-';
230             }
231
232             if (!canonicaliseAa && 'a' <= c && c <= 'z')
233             {
234               c -= (32); // 32 = 'a' - 'A'
235             }
236           }
237           values[c]++;
238         }
239         else
240         {
241           values['-']++;
242         }
243       }
244
245       // What is the count threshold to count the residues in residueHash()
246       thresh = (threshold * (jSize)) / 100;
247
248       // loop over all the found residues
249       resultHash = new Hashtable();
250       for (char v = '-'; v < 'Z'; v++)
251       {
252
253         if (values[v] > thresh)
254         {
255           res = String.valueOf(v);
256
257           // Now loop over the properties
258           enumeration2 = propHash.keys();
259
260           while (enumeration2.hasMoreElements())
261           {
262             type = (String) enumeration2.nextElement();
263             ht = (Hashtable) propHash.get(type);
264
265             // Have we ticked this before?
266             if (!resultHash.containsKey(type))
267             {
268               if (ht.containsKey(res))
269               {
270                 resultHash.put(type, ht.get(res));
271               }
272               else
273               {
274                 resultHash.put(type, ht.get("-"));
275               }
276             }
277             else if (((Integer) resultHash.get(type)).equals((Integer) ht
278                     .get(res)) == false)
279             {
280               resultHash.put(type, new Integer(-1));
281             }
282           }
283         }
284       }
285
286       if (total.length > 0)
287       {
288         total[i - start] = resultHash;
289       }
290     }
291   }
292
293   /*****************************************************************************
294    * count conservation for the j'th column of the alignment
295    * 
296    * @return { gap count, conserved residue count}
297    */
298   public int[] countConsNGaps(int j)
299   {
300     int count = 0;
301     int cons = 0;
302     int nres = 0;
303     int[] r = new int[2];
304     char f = '$';
305     int i, iSize = sequences.length;
306     char c;
307
308     for (i = 0; i < iSize; i++)
309     {
310       if (j >= sequences[i].getLength())
311       {
312         count++;
313         continue;
314       }
315
316       c = sequences[i].getCharAt(j); // gaps do not have upper/lower case
317
318       if (jalview.util.Comparison.isGap((c)))
319       {
320         count++;
321       }
322       else
323       {
324         nres++;
325
326         if (nres == 1)
327         {
328           f = c;
329           cons++;
330         }
331         else if (f == c)
332         {
333           cons++;
334         }
335       }
336     }
337
338     r[0] = (nres == cons) ? 1 : 0;
339     r[1] = count;
340
341     return r;
342   }
343
344   /**
345    * Calculates the conservation sequence
346    * 
347    * @param consflag
348    *          if true, poitiveve conservation; false calculates negative
349    *          conservation
350    * @param percentageGaps
351    *          commonly used value is 25
352    */
353   public void verdict(boolean consflag, float percentageGaps)
354   {
355     StringBuffer consString = new StringBuffer();
356     String type;
357     Integer result;
358     int[] gapcons;
359     int totGaps, count;
360     float pgaps;
361     Hashtable resultHash;
362     Enumeration enumeration;
363
364     // NOTE THIS SHOULD CHECK IF THE CONSEQUENCE ALREADY
365     // EXISTS AND NOT OVERWRITE WITH '-', BUT THIS CASE
366     // DOES NOT EXIST IN JALVIEW 2.1.2
367     for (int i = 0; i < start; i++)
368     {
369       consString.append('-');
370     }
371     consSymbs = new String[end-start+1];
372     for (int i = start; i <= end; i++)
373     {
374       gapcons = countConsNGaps(i);
375       totGaps = gapcons[1];
376       pgaps = ((float) totGaps * 100) / (float) sequences.length;
377       consSymbs[i-start]=new String();
378       
379       if (percentageGaps > pgaps)
380       {
381         resultHash = total[i - start];
382         // Now find the verdict
383         count = 0;
384         enumeration = resultHash.keys();
385
386         while (enumeration.hasMoreElements())
387         {
388           type = (String) enumeration.nextElement();
389           result = (Integer) resultHash.get(type);
390           // Do we want to count +ve conservation or +ve and -ve cons.?
391           if (consflag)
392           {
393             if (result.intValue() == 1)
394             {
395               consSymbs[i-start] = type+" "+consSymbs[i-start];
396               count++;
397             }
398           }
399           else
400           {
401             if (result.intValue() != -1)
402             {
403               { 
404                  if (result.intValue()==0) {
405                    consSymbs[i-start] = consSymbs[i-start]+ " !"+type;
406                  } else {
407                    consSymbs[i-start] = type+" "+consSymbs[i-start];
408                  }
409               }
410               
411               count++;
412             }
413           }
414         }
415
416         if (count < 10)
417         {
418           consString.append(count); // Conserved props!=Identity
419         }
420         else
421         {
422           consString.append((gapcons[0] == 1) ? "*" : "+");
423         }
424       }
425       else
426       {
427         consString.append('-');
428       }
429     }
430
431     consSequence = new Sequence(name, consString.toString(), start, end);
432   }
433
434   /**
435    * 
436    * 
437    * @return Conservation sequence
438    */
439   public Sequence getConsSequence()
440   {
441     return consSequence;
442   }
443
444   // From Alignment.java in jalview118
445   public void findQuality()
446   {
447     findQuality(0, maxLength - 1);
448   }
449
450   /**
451    * DOCUMENT ME!
452    */
453   private void percentIdentity2()
454   {
455     seqNums = new Vector();
456     // calcSeqNum(s);
457     int i = 0, iSize = sequences.length;
458     // Do we need to calculate this again?
459     for (i = 0; i < iSize; i++)
460     {
461       calcSeqNum(i);
462     }
463
464     if ((cons2 == null) || seqNumsChanged)
465     {
466       cons2 = new int[maxLength][24];
467
468       // Initialize the array
469       for (int j = 0; j < 24; j++)
470       {
471         for (i = 0; i < maxLength; i++)
472         {
473           cons2[i][j] = 0;
474         }
475       }
476
477       int[] sqnum;
478       int j = 0;
479
480       while (j < sequences.length)
481       {
482         sqnum = (int[]) seqNums.elementAt(j);
483
484         for (i = 1; i < sqnum.length; i++)
485         {
486           cons2[i - 1][sqnum[i]]++;
487         }
488
489         for (i = sqnum.length - 1; i < maxLength; i++)
490         {
491           cons2[i][23]++; // gap count
492         }
493
494         j++;
495       }
496
497       // unnecessary ?
498
499       /*
500        * for (int i=start; i <= end; i++) { int max = -1000; int maxi = -1; int
501        * maxj = -1;
502        * 
503        * for (int j=0;j<24;j++) { if (cons2[i][j] > max) { max = cons2[i][j];
504        * maxi = i; maxj = j; } } }
505        */
506     }
507   }
508
509   /**
510    * Calculates the quality of the set of sequences
511    * 
512    * @param start
513    *          Start residue
514    * @param end
515    *          End residue
516    */
517   public void findQuality(int start, int end)
518   {
519     quality = new Vector();
520
521     double max = -10000;
522     int[][] BLOSUM62 = jalview.schemes.ResidueProperties.getBLOSUM62();
523
524     // Loop over columns // JBPNote Profiling info
525     // long ts = System.currentTimeMillis();
526     // long te = System.currentTimeMillis();
527     percentIdentity2();
528
529     int size = seqNums.size();
530     int[] lengths = new int[size];
531     double tot, bigtot, sr, tmp;
532     double[] x, xx;
533     int l, j, i, ii, i2, k, seqNum;
534
535     for (l = 0; l < size; l++)
536     {
537       lengths[l] = ((int[]) seqNums.elementAt(l)).length - 1;
538     }
539
540     for (j = start; j <= end; j++)
541     {
542       bigtot = 0;
543
544       // First Xr = depends on column only
545       x = new double[24];
546
547       for (ii = 0; ii < 24; ii++)
548       {
549         x[ii] = 0;
550
551         for (i2 = 0; i2 < 24; i2++)
552         {
553           x[ii] += (((double) cons2[j][i2] * BLOSUM62[ii][i2]) + 4);
554         }
555
556         x[ii] /= size;
557       }
558
559       // Now calculate D for each position and sum
560       for (k = 0; k < size; k++)
561       {
562         tot = 0;
563         xx = new double[24];
564         seqNum = (j < lengths[k]) ? ((int[]) seqNums.elementAt(k))[j + 1]
565                 : 23; // Sequence, or gap at the end
566
567         // This is a loop over r
568         for (i = 0; i < 23; i++)
569         {
570           sr = 0;
571
572           sr = (double) BLOSUM62[i][seqNum] + 4;
573
574           // Calculate X with another loop over residues
575           // System.out.println("Xi " + i + " " + x[i] + " " + sr);
576           xx[i] = x[i] - sr;
577
578           tot += (xx[i] * xx[i]);
579         }
580
581         bigtot += Math.sqrt(tot);
582       }
583
584       // This is the quality for one column
585       if (max < bigtot)
586       {
587         max = bigtot;
588       }
589
590       // bigtot = bigtot * (size-cons2[j][23])/size;
591       quality.addElement(new Double(bigtot));
592
593       // Need to normalize by gaps
594     }
595
596     double newmax = -10000;
597
598     for (j = start; j <= end; j++)
599     {
600       tmp = ((Double) quality.elementAt(j)).doubleValue();
601       tmp = ((max - tmp) * (size - cons2[j][23])) / size;
602
603       // System.out.println(tmp+ " " + j);
604       quality.setElementAt(new Double(tmp), j);
605
606       if (tmp > newmax)
607       {
608         newmax = tmp;
609       }
610     }
611
612     // System.out.println("Quality " + s);
613     qualityRange[0] = new Double(0);
614     qualityRange[1] = new Double(newmax);
615   }
616
617   /**
618    * complete the given consensus and quuality annotation rows. Note: currently
619    * this method will enlarge the given annotation row if it is too small,
620    * otherwise will leave its length unchanged.
621    * 
622    * @param conservation
623    *          conservation annotation row
624    * @param quality2
625    *          (optional - may be null)
626    * @param istart
627    *          first column for conservation
628    * @param alWidth
629    *          extent of conservation
630    */
631   public void completeAnnotations(AlignmentAnnotation conservation,
632           AlignmentAnnotation quality2, int istart, int alWidth)
633   {
634     char[] sequence = getConsSequence().getSequence();
635     float minR;
636     float minG;
637     float minB;
638     float maxR;
639     float maxG;
640     float maxB;
641     minR = 0.3f;
642     minG = 0.0f;
643     minB = 0f;
644     maxR = 1.0f - minR;
645     maxG = 0.9f - minG;
646     maxB = 0f - minB; // scalable range for colouring both Conservation and
647     // Quality
648
649     float min = 0f;
650     float max = 11f;
651     float qmin = 0f;
652     float qmax = 0f;
653
654     char c;
655
656     if (conservation.annotations != null
657             && conservation.annotations.length < alWidth)
658     {
659       conservation.annotations = new Annotation[alWidth];
660     }
661
662     if (quality2 != null)
663     {
664       quality2.graphMax = qualityRange[1].floatValue();
665       if (quality2.annotations != null
666               && quality2.annotations.length < alWidth)
667       {
668         quality2.annotations = new Annotation[alWidth];
669       }
670       qmin = qualityRange[0].floatValue();
671       qmax = qualityRange[1].floatValue();
672     }
673
674     for (int i = 0; i < alWidth; i++)
675     {
676       float value = 0;
677
678       c = sequence[i];
679
680       if (Character.isDigit(c))
681       {
682         value = (int) (c - '0');
683       }
684       else if (c == '*')
685       {
686         value = 11;
687       }
688       else if (c == '+')
689       {
690         value = 10;
691       }
692
693       float vprop = value - min;
694       vprop /= max;
695       conservation.annotations[i] = new Annotation(String.valueOf(c),
696               consSymbs[i-start], ' ', value, new Color(minR
697                       + (maxR * vprop), minG + (maxG * vprop), minB
698                       + (maxB * vprop)));
699
700       // Quality calc
701       if (quality2 != null)
702       {
703         value = ((Double) quality.elementAt(i)).floatValue();
704         vprop = value - qmin;
705         vprop /= qmax;
706         quality2.annotations[i] = new Annotation(" ",
707                 String.valueOf(value), ' ', value, new Color(minR
708                         + (maxR * vprop), minG + (maxG * vprop), minB
709                         + (maxB * vprop)));
710       }
711     }
712   }
713
714   /**
715    * construct and call the calculation methods on a new Conservation object
716    * 
717    * @param name
718    *          - name of conservation
719    * @param consHash
720    *          - hash table of properties for each amino acid (normally
721    *          ResidueProperties.propHash)
722    * @param threshold
723    *          - minimum number of conserved residues needed to indicate
724    *          conservation (typically 3)
725    * @param seqs
726    * @param start
727    *          first column in calculation window
728    * @param end
729    *          last column in calculation window
730    * @param posOrNeg
731    *          positive (true) or negative (false) conservation
732    * @param consPercGaps
733    *          percentage of gaps tolerated in column
734    * @param calcQuality
735    *          flag indicating if alignment quality should be calculated
736    * @return Conservation object ready for use in visualization
737    */
738   public static Conservation calculateConservation(String name,
739           Hashtable consHash, int threshold, List<SequenceI> seqs,
740           int start, int end, boolean posOrNeg, int consPercGaps,
741           boolean calcQuality)
742   {
743     Conservation cons = new Conservation(name, consHash, threshold, seqs,
744             start, end);
745     return calculateConservation(cons, posOrNeg, consPercGaps, calcQuality);
746   }
747
748   /**
749    * @param b
750    *          positive (true) or negative (false) conservation
751    * @param consPercGaps
752    *          percentage of gaps tolerated in column
753    * @param calcQuality
754    *          flag indicating if alignment quality should be calculated
755    * @return Conservation object ready for use in visualization
756    */
757   public static Conservation calculateConservation(Conservation cons,
758           boolean b, int consPercGaps, boolean calcQuality)
759   {
760     cons.calculate();
761     cons.verdict(b, consPercGaps);
762
763     if (calcQuality)
764     {
765       cons.findQuality();
766     }
767
768     return cons;
769   }
770 }