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