JAL-1759 corrected syntax for 'atom picked' callback (toggles label
[jalview.git] / src / jalview / io / FeaturesFile.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.io;
22
23 import jalview.analysis.SequenceIdMatcher;
24 import jalview.datamodel.AlignedCodonFrame;
25 import jalview.datamodel.AlignmentI;
26 import jalview.datamodel.SequenceDummy;
27 import jalview.datamodel.SequenceFeature;
28 import jalview.datamodel.SequenceI;
29 import jalview.schemes.AnnotationColourGradient;
30 import jalview.schemes.GraduatedColor;
31 import jalview.schemes.UserColourScheme;
32 import jalview.util.Format;
33 import jalview.util.MapList;
34
35 import java.io.IOException;
36 import java.util.ArrayList;
37 import java.util.Arrays;
38 import java.util.HashMap;
39 import java.util.Hashtable;
40 import java.util.Iterator;
41 import java.util.List;
42 import java.util.Map;
43 import java.util.StringTokenizer;
44 import java.util.Vector;
45
46 /**
47  * Parse and create Jalview Features files Detects GFF format features files and
48  * parses. Does not implement standard print() - call specific printFeatures or
49  * printGFF. Uses AlignmentI.findSequence(String id) to find the sequence object
50  * for the features annotation - this normally works on an exact match.
51  * 
52  * @author AMW
53  * @version $Revision$
54  */
55 public class FeaturesFile extends AlignFile
56 {
57   /**
58    * work around for GFF interpretation bug where source string becomes
59    * description rather than a group
60    */
61   private boolean doGffSource = true;
62
63   private int gffversion;
64
65   /**
66    * Creates a new FeaturesFile object.
67    */
68   public FeaturesFile()
69   {
70   }
71
72   /**
73    * @param inFile
74    * @param type
75    * @throws IOException
76    */
77   public FeaturesFile(String inFile, String type) throws IOException
78   {
79     super(inFile, type);
80   }
81
82   /**
83    * @param source
84    * @throws IOException
85    */
86   public FeaturesFile(FileParse source) throws IOException
87   {
88     super(source);
89   }
90
91   /**
92    * @param parseImmediately
93    * @param source
94    * @throws IOException
95    */
96   public FeaturesFile(boolean parseImmediately, FileParse source)
97           throws IOException
98   {
99     super(parseImmediately, source);
100   }
101
102   /**
103    * @param parseImmediately
104    * @param inFile
105    * @param type
106    * @throws IOException
107    */
108   public FeaturesFile(boolean parseImmediately, String inFile, String type)
109           throws IOException
110   {
111     super(parseImmediately, inFile, type);
112   }
113
114   /**
115    * Parse GFF or sequence features file using case-independent matching,
116    * discarding URLs
117    * 
118    * @param align
119    *          - alignment/dataset containing sequences that are to be annotated
120    * @param colours
121    *          - hashtable to store feature colour definitions
122    * @param removeHTML
123    *          - process html strings into plain text
124    * @return true if features were added
125    */
126   public boolean parse(AlignmentI align, Hashtable colours,
127           boolean removeHTML)
128   {
129     return parse(align, colours, null, removeHTML, false);
130   }
131
132   /**
133    * Parse GFF or sequence features file optionally using case-independent
134    * matching, discarding URLs
135    * 
136    * @param align
137    *          - alignment/dataset containing sequences that are to be annotated
138    * @param colours
139    *          - hashtable to store feature colour definitions
140    * @param removeHTML
141    *          - process html strings into plain text
142    * @param relaxedIdmatching
143    *          - when true, ID matches to compound sequence IDs are allowed
144    * @return true if features were added
145    */
146   public boolean parse(AlignmentI align, Map colours, boolean removeHTML,
147           boolean relaxedIdMatching)
148   {
149     return parse(align, colours, null, removeHTML, relaxedIdMatching);
150   }
151
152   /**
153    * Parse GFF or sequence features file optionally using case-independent
154    * matching
155    * 
156    * @param align
157    *          - alignment/dataset containing sequences that are to be annotated
158    * @param colours
159    *          - hashtable to store feature colour definitions
160    * @param featureLink
161    *          - hashtable to store associated URLs
162    * @param removeHTML
163    *          - process html strings into plain text
164    * @return true if features were added
165    */
166   public boolean parse(AlignmentI align, Map colours, Map featureLink,
167           boolean removeHTML)
168   {
169     return parse(align, colours, featureLink, removeHTML, false);
170   }
171
172   @Override
173   public void addAnnotations(AlignmentI al)
174   {
175     // TODO Auto-generated method stub
176     super.addAnnotations(al);
177   }
178
179   @Override
180   public void addProperties(AlignmentI al)
181   {
182     // TODO Auto-generated method stub
183     super.addProperties(al);
184   }
185
186   @Override
187   public void addSeqGroups(AlignmentI al)
188   {
189     // TODO Auto-generated method stub
190     super.addSeqGroups(al);
191   }
192
193   /**
194    * Parse GFF or sequence features file
195    * 
196    * @param align
197    *          - alignment/dataset containing sequences that are to be annotated
198    * @param colours
199    *          - hashtable to store feature colour definitions
200    * @param featureLink
201    *          - hashtable to store associated URLs
202    * @param removeHTML
203    *          - process html strings into plain text
204    * @param relaxedIdmatching
205    *          - when true, ID matches to compound sequence IDs are allowed
206    * @return true if features were added
207    */
208   public boolean parse(AlignmentI align, Map colours, Map featureLink,
209           boolean removeHTML, boolean relaxedIdmatching)
210   {
211
212     String line = null;
213     try
214     {
215       SequenceI seq = null;
216       /**
217        * keep track of any sequences we try to create from the data if it is a GFF3 file
218        */
219       ArrayList<SequenceI> newseqs = new ArrayList<SequenceI>();
220       String type, desc, token = null;
221
222       int index, start, end;
223       float score;
224       StringTokenizer st;
225       SequenceFeature sf;
226       String featureGroup = null, groupLink = null;
227       Map typeLink = new Hashtable();
228       /**
229        * when true, assume GFF style features rather than Jalview style.
230        */
231       boolean GFFFile = true;
232       Map<String, String> gffProps = new HashMap<String, String>();
233       while ((line = nextLine()) != null)
234       {
235         // skip comments/process pragmas
236         if (line.startsWith("#"))
237         {
238           if (line.startsWith("##"))
239           {
240             // possibly GFF2/3 version and metadata header
241             processGffPragma(line, gffProps, align, newseqs);
242             line = "";
243           }
244           continue;
245         }
246
247         st = new StringTokenizer(line, "\t");
248         if (st.countTokens() == 1)
249         {
250           if (line.trim().equalsIgnoreCase("GFF"))
251           {
252             // Start parsing file as if it might be GFF again.
253             GFFFile = true;
254             continue;
255           }
256         }
257         if (st.countTokens() > 1 && st.countTokens() < 4)
258         {
259           GFFFile = false;
260           type = st.nextToken();
261           if (type.equalsIgnoreCase("startgroup"))
262           {
263             featureGroup = st.nextToken();
264             if (st.hasMoreElements())
265             {
266               groupLink = st.nextToken();
267               featureLink.put(featureGroup, groupLink);
268             }
269           }
270           else if (type.equalsIgnoreCase("endgroup"))
271           {
272             // We should check whether this is the current group,
273             // but at present theres no way of showing more than 1 group
274             st.nextToken();
275             featureGroup = null;
276             groupLink = null;
277           }
278           else
279           {
280             Object colour = null;
281             String colscheme = st.nextToken();
282             if (colscheme.indexOf("|") > -1
283                     || colscheme.trim().equalsIgnoreCase("label"))
284             {
285               // Parse '|' separated graduated colourscheme fields:
286               // [label|][mincolour|maxcolour|[absolute|]minvalue|maxvalue|thresholdtype|thresholdvalue]
287               // can either provide 'label' only, first is optional, next two
288               // colors are required (but may be
289               // left blank), next is optional, nxt two min/max are required.
290               // first is either 'label'
291               // first/second and third are both hexadecimal or word equivalent
292               // colour.
293               // next two are values parsed as floats.
294               // fifth is either 'above','below', or 'none'.
295               // sixth is a float value and only required when fifth is either
296               // 'above' or 'below'.
297               StringTokenizer gcol = new StringTokenizer(colscheme, "|",
298                       true);
299               // set defaults
300               int threshtype = AnnotationColourGradient.NO_THRESHOLD;
301               float min = Float.MIN_VALUE, max = Float.MAX_VALUE, threshval = Float.NaN;
302               boolean labelCol = false;
303               // Parse spec line
304               String mincol = gcol.nextToken();
305               if (mincol == "|")
306               {
307                 System.err
308                         .println("Expected either 'label' or a colour specification in the line: "
309                                 + line);
310                 continue;
311               }
312               String maxcol = null;
313               if (mincol.toLowerCase().indexOf("label") == 0)
314               {
315                 labelCol = true;
316                 mincol = (gcol.hasMoreTokens() ? gcol.nextToken() : null); // skip
317                                                                            // '|'
318                 mincol = (gcol.hasMoreTokens() ? gcol.nextToken() : null);
319               }
320               String abso = null, minval, maxval;
321               if (mincol != null)
322               {
323                 // at least four more tokens
324                 if (mincol.equals("|"))
325                 {
326                   mincol = "";
327                 }
328                 else
329                 {
330                   gcol.nextToken(); // skip next '|'
331                 }
332                 // continue parsing rest of line
333                 maxcol = gcol.nextToken();
334                 if (maxcol.equals("|"))
335                 {
336                   maxcol = "";
337                 }
338                 else
339                 {
340                   gcol.nextToken(); // skip next '|'
341                 }
342                 abso = gcol.nextToken();
343                 gcol.nextToken(); // skip next '|'
344                 if (abso.toLowerCase().indexOf("abso") != 0)
345                 {
346                   minval = abso;
347                   abso = null;
348                 }
349                 else
350                 {
351                   minval = gcol.nextToken();
352                   gcol.nextToken(); // skip next '|'
353                 }
354                 maxval = gcol.nextToken();
355                 if (gcol.hasMoreTokens())
356                 {
357                   gcol.nextToken(); // skip next '|'
358                 }
359                 try
360                 {
361                   if (minval.length() > 0)
362                   {
363                     min = new Float(minval).floatValue();
364                   }
365                 } catch (Exception e)
366                 {
367                   System.err
368                           .println("Couldn't parse the minimum value for graduated colour for type ("
369                                   + colscheme
370                                   + ") - did you misspell 'auto' for the optional automatic colour switch ?");
371                   e.printStackTrace();
372                 }
373                 try
374                 {
375                   if (maxval.length() > 0)
376                   {
377                     max = new Float(maxval).floatValue();
378                   }
379                 } catch (Exception e)
380                 {
381                   System.err
382                           .println("Couldn't parse the maximum value for graduated colour for type ("
383                                   + colscheme + ")");
384                   e.printStackTrace();
385                 }
386               }
387               else
388               {
389                 // add in some dummy min/max colours for the label-only
390                 // colourscheme.
391                 mincol = "FFFFFF";
392                 maxcol = "000000";
393               }
394               try
395               {
396                 colour = new jalview.schemes.GraduatedColor(
397                         new UserColourScheme(mincol).findColour('A'),
398                         new UserColourScheme(maxcol).findColour('A'), min,
399                         max);
400               } catch (Exception e)
401               {
402                 System.err
403                         .println("Couldn't parse the graduated colour scheme ("
404                                 + colscheme + ")");
405                 e.printStackTrace();
406               }
407               if (colour != null)
408               {
409                 ((jalview.schemes.GraduatedColor) colour)
410                         .setColourByLabel(labelCol);
411                 ((jalview.schemes.GraduatedColor) colour)
412                         .setAutoScaled(abso == null);
413                 // add in any additional parameters
414                 String ttype = null, tval = null;
415                 if (gcol.hasMoreTokens())
416                 {
417                   // threshold type and possibly a threshold value
418                   ttype = gcol.nextToken();
419                   if (ttype.toLowerCase().startsWith("below"))
420                   {
421                     ((jalview.schemes.GraduatedColor) colour)
422                             .setThreshType(AnnotationColourGradient.BELOW_THRESHOLD);
423                   }
424                   else if (ttype.toLowerCase().startsWith("above"))
425                   {
426                     ((jalview.schemes.GraduatedColor) colour)
427                             .setThreshType(AnnotationColourGradient.ABOVE_THRESHOLD);
428                   }
429                   else
430                   {
431                     ((jalview.schemes.GraduatedColor) colour)
432                             .setThreshType(AnnotationColourGradient.NO_THRESHOLD);
433                     if (!ttype.toLowerCase().startsWith("no"))
434                     {
435                       System.err
436                               .println("Ignoring unrecognised threshold type : "
437                                       + ttype);
438                     }
439                   }
440                 }
441                 if (((GraduatedColor) colour).getThreshType() != AnnotationColourGradient.NO_THRESHOLD)
442                 {
443                   try
444                   {
445                     gcol.nextToken();
446                     tval = gcol.nextToken();
447                     ((jalview.schemes.GraduatedColor) colour)
448                             .setThresh(new Float(tval).floatValue());
449                   } catch (Exception e)
450                   {
451                     System.err
452                             .println("Couldn't parse threshold value as a float: ("
453                                     + tval + ")");
454                     e.printStackTrace();
455                   }
456                 }
457                 // parse the thresh-is-min token ?
458                 if (gcol.hasMoreTokens())
459                 {
460                   System.err
461                           .println("Ignoring additional tokens in parameters in graduated colour specification\n");
462                   while (gcol.hasMoreTokens())
463                   {
464                     System.err.println("|" + gcol.nextToken());
465                   }
466                   System.err.println("\n");
467                 }
468               }
469             }
470             else
471             {
472               UserColourScheme ucs = new UserColourScheme(colscheme);
473               colour = ucs.findColour('A');
474             }
475             if (colour != null)
476             {
477               colours.put(type, colour);
478             }
479             if (st.hasMoreElements())
480             {
481               String link = st.nextToken();
482               typeLink.put(type, link);
483               if (featureLink == null)
484               {
485                 featureLink = new Hashtable();
486               }
487               featureLink.put(type, link);
488             }
489           }
490           continue;
491         }
492         String seqId = "";
493         while (st.hasMoreElements())
494         {
495
496           if (GFFFile)
497           {
498             // Still possible this is an old Jalview file,
499             // which does not have type colours at the beginning
500             seqId = token = st.nextToken();
501             seq = findName(align, seqId, relaxedIdmatching, newseqs);
502             if (seq != null)
503             {
504               desc = st.nextToken();
505               String group = null;
506               if (doGffSource && desc.indexOf(' ') == -1)
507               {
508                 // could also be a source term rather than description line
509                 group = new String(desc);
510               }
511               type = st.nextToken();
512               try
513               {
514                 String stt = st.nextToken();
515                 if (stt.length() == 0 || stt.equals("-"))
516                 {
517                   start = 0;
518                 }
519                 else
520                 {
521                   start = Integer.parseInt(stt);
522                 }
523               } catch (NumberFormatException ex)
524               {
525                 start = 0;
526               }
527               try
528               {
529                 String stt = st.nextToken();
530                 if (stt.length() == 0 || stt.equals("-"))
531                 {
532                   end = 0;
533                 }
534                 else
535                 {
536                   end = Integer.parseInt(stt);
537                 }
538               } catch (NumberFormatException ex)
539               {
540                 end = 0;
541               }
542               // TODO: decide if non positional feature assertion for input data
543               // where end==0 is generally valid
544               if (end == 0)
545               {
546                 // treat as non-positional feature, regardless.
547                 start = 0;
548               }
549               try
550               {
551                 score = new Float(st.nextToken()).floatValue();
552               } catch (NumberFormatException ex)
553               {
554                 score = 0;
555               }
556
557               sf = new SequenceFeature(type, desc, start, end, score, group);
558
559               try
560               {
561                 sf.setValue("STRAND", st.nextToken());
562                 sf.setValue("FRAME", st.nextToken());
563               } catch (Exception ex)
564               {
565               }
566
567               if (st.hasMoreTokens())
568               {
569                 StringBuffer attributes = new StringBuffer();
570                 boolean sep = false;
571                 while (st.hasMoreTokens())
572                 {
573                   attributes.append((sep ? "\t" : "") + st.nextElement());
574                   sep = true;
575                 }
576                 // TODO validate and split GFF2 attributes field ? parse out
577                 // ([A-Za-z][A-Za-z0-9_]*) <value> ; and add as
578                 // sf.setValue(attrib, val);
579                 sf.setValue("ATTRIBUTES", attributes.toString());
580               }
581
582               if (processOrAddSeqFeature(align, newseqs, seq, sf, GFFFile,
583                       relaxedIdmatching))
584               {
585                 // check whether we should add the sequence feature to any other
586                 // sequences in the alignment with the same or similar
587                 while ((seq = align.findName(seq, seqId, true)) != null)
588                 {
589                   seq.addSequenceFeature(new SequenceFeature(sf));
590                 }
591               }
592               break;
593             }
594           }
595
596           if (GFFFile && seq == null)
597           {
598             desc = token;
599           }
600           else
601           {
602             desc = st.nextToken();
603           }
604           if (!st.hasMoreTokens())
605           {
606             System.err
607                     .println("DEBUG: Run out of tokens when trying to identify the destination for the feature.. giving up.");
608             // in all probability, this isn't a file we understand, so bail
609             // quietly.
610             return false;
611           }
612
613           token = st.nextToken();
614
615           if (!token.equals("ID_NOT_SPECIFIED"))
616           {
617             seq = findName(align, seqId = token, relaxedIdmatching, null);
618             st.nextToken();
619           }
620           else
621           {
622             seqId = null;
623             try
624             {
625               index = Integer.parseInt(st.nextToken());
626               seq = align.getSequenceAt(index);
627             } catch (NumberFormatException ex)
628             {
629               seq = null;
630             }
631           }
632
633           if (seq == null)
634           {
635             System.out.println("Sequence not found: " + line);
636             break;
637           }
638
639           start = Integer.parseInt(st.nextToken());
640           end = Integer.parseInt(st.nextToken());
641
642           type = st.nextToken();
643
644           if (!colours.containsKey(type))
645           {
646             // Probably the old style groups file
647             UserColourScheme ucs = new UserColourScheme(type);
648             colours.put(type, ucs.findColour('A'));
649           }
650           sf = new SequenceFeature(type, desc, "", start, end, featureGroup);
651           if (st.hasMoreTokens())
652           {
653             try
654             {
655               score = new Float(st.nextToken()).floatValue();
656               // update colourgradient bounds if allowed to
657             } catch (NumberFormatException ex)
658             {
659               score = 0;
660             }
661             sf.setScore(score);
662           }
663           if (groupLink != null && removeHTML)
664           {
665             sf.addLink(groupLink);
666             sf.description += "%LINK%";
667           }
668           if (typeLink.containsKey(type) && removeHTML)
669           {
670             sf.addLink(typeLink.get(type).toString());
671             sf.description += "%LINK%";
672           }
673
674           parseDescriptionHTML(sf, removeHTML);
675
676           seq.addSequenceFeature(sf);
677
678           while (seqId != null
679                   && (seq = align.findName(seq, seqId, false)) != null)
680           {
681             seq.addSequenceFeature(new SequenceFeature(sf));
682           }
683           // If we got here, its not a GFFFile
684           GFFFile = false;
685         }
686       }
687       resetMatcher();
688     } catch (Exception ex)
689     {
690       // should report somewhere useful for UI if necessary
691       warningMessage = ((warningMessage == null) ? "" : warningMessage)
692               + "Parsing error at\n" + line;
693       System.out.println("Error parsing feature file: " + ex + "\n" + line);
694       ex.printStackTrace(System.err);
695       resetMatcher();
696       return false;
697     }
698
699     return true;
700   }
701
702   private enum GffPragmas
703   {
704     gff_version, sequence_region, feature_ontology, attribute_ontology, source_ontology, species_build, fasta, hash
705   };
706
707   private static Map<String, GffPragmas> GFFPRAGMA;
708   static
709   {
710     GFFPRAGMA = new HashMap<String, GffPragmas>();
711     GFFPRAGMA.put("sequence-region", GffPragmas.sequence_region);
712     GFFPRAGMA.put("feature-ontology", GffPragmas.feature_ontology);
713     GFFPRAGMA.put("#", GffPragmas.hash);
714     GFFPRAGMA.put("fasta", GffPragmas.fasta);
715     GFFPRAGMA.put("species-build", GffPragmas.species_build);
716     GFFPRAGMA.put("source-ontology", GffPragmas.source_ontology);
717     GFFPRAGMA.put("attribute-ontology", GffPragmas.attribute_ontology);
718   }
719
720   private void processGffPragma(String line, Map<String, String> gffProps,
721           AlignmentI align, ArrayList<SequenceI> newseqs)
722           throws IOException
723   {
724     // line starts with ##
725     int spacepos = line.indexOf(' ');
726     String pragma = spacepos == -1 ? line.substring(2).trim() : line
727             .substring(2, spacepos);
728     GffPragmas gffpragma = GFFPRAGMA.get(pragma.toLowerCase());
729     if (gffpragma == null)
730     {
731       return;
732     }
733     switch (gffpragma)
734     {
735     case gff_version:
736       try
737       {
738         gffversion = Integer.parseInt(line.substring(spacepos + 1));
739       } finally
740       {
741
742       }
743       break;
744     case feature_ontology:
745       // resolve against specific feature ontology
746       break;
747     case attribute_ontology:
748       // resolve against specific attribute ontology
749       break;
750     case source_ontology:
751       // resolve against specific source ontology
752       break;
753     case species_build:
754       // resolve against specific NCBI taxon version
755       break;
756     case hash:
757       // close off any open feature hierarchies
758       break;
759     case fasta:
760       // process the rest of the file as a fasta file and replace any dummy
761       // sequence IDs
762       process_as_fasta(align, newseqs);
763       break;
764     default:
765       // we do nothing ?
766       System.err.println("Ignoring unknown pragma:\n" + line);
767     }
768   }
769
770   private void process_as_fasta(AlignmentI align, List<SequenceI> newseqs)
771           throws IOException
772   {
773     try
774     {
775       mark();
776     } catch (IOException q)
777     {
778     }
779     FastaFile parser = new FastaFile(this);
780     List<SequenceI> includedseqs = parser.getSeqs();
781     SequenceIdMatcher smatcher = new SequenceIdMatcher(newseqs);
782     // iterate over includedseqs, and replacing matching ones with newseqs
783     // sequences. Generic iterator not used here because we modify includedseqs
784     // as we go
785     for (int p = 0, pSize = includedseqs.size(); p < pSize; p++)
786     {
787       // search for any dummy seqs that this sequence can be used to update
788       SequenceI dummyseq = smatcher.findIdMatch(includedseqs.get(p));
789       if (dummyseq != null)
790       {
791         // dummyseq was created so it could be annotated and referred to in
792         // alignments/codon mappings
793
794         SequenceI mseq = includedseqs.get(p);
795         // mseq is the 'template' imported from the FASTA file which we'll use
796         // to coomplete dummyseq
797         if (dummyseq instanceof SequenceDummy)
798         {
799           // probably have the pattern wrong
800           // idea is that a flyweight proxy for a sequence ID can be created for
801           // 1. stable reference creation
802           // 2. addition of annotation
803           // 3. future replacement by a real sequence
804           // current pattern is to create SequenceDummy objects - a convenience
805           // constructor for a Sequence.
806           // problem is that when promoted to a real sequence, all references
807           // need
808           // to be updated somehow.
809           ((SequenceDummy) dummyseq).become(mseq);
810           includedseqs.set(p, dummyseq); // template is no longer needed
811         }
812       }
813     }
814     // finally add sequences to the dataset
815     for (SequenceI seq : includedseqs)
816     {
817       align.addSequence(seq);
818     }
819   }
820
821   /**
822    * take a sequence feature and examine its attributes to decide how it should
823    * be added to a sequence
824    * 
825    * @param seq
826    *          - the destination sequence constructed or discovered in the
827    *          current context
828    * @param sf
829    *          - the base feature with ATTRIBUTES property containing any
830    *          additional attributes
831    * @param gFFFile
832    *          - true if we are processing a GFF annotation file
833    * @return true if sf was actually added to the sequence, false if it was
834    *         processed in another way
835    */
836   public boolean processOrAddSeqFeature(AlignmentI align, List<SequenceI> newseqs, SequenceI seq, SequenceFeature sf,
837           boolean gFFFile, boolean relaxedIdMatching)
838   {
839     String attr = (String) sf.getValue("ATTRIBUTES");
840     boolean add = true;
841     if (gFFFile && attr != null)
842     {
843       int nattr=8;
844
845       for (String attset : attr.split("\t"))
846       {
847         if (attset==null || attset.trim().length()==0)
848         {
849           continue;
850         }
851         nattr++;
852         Map<String, List<String>> set = new HashMap<String, List<String>>();
853         // normally, only expect one column - 9 - in this field
854         // the attributes (Gff3) or groups (gff2) field
855         for (String pair : attset.trim().split(";"))
856         {
857           pair = pair.trim();
858           if (pair.length() == 0)
859           {
860             continue;
861           }
862
863           // expect either space seperated (gff2) or '=' separated (gff3) 
864           // key/value pairs here
865
866           int eqpos = pair.indexOf('='),sppos = pair.indexOf(' ');
867           String key = null, value = null;
868
869           if (sppos > -1 && (eqpos == -1 || sppos < eqpos))
870           {
871             key = pair.substring(0, sppos);
872             value = pair.substring(sppos + 1);
873           } else {
874             if (eqpos > -1 && (sppos == -1 || eqpos < sppos))
875             {
876               key = pair.substring(0, eqpos);
877               value = pair.substring(eqpos + 1);
878             } else
879             {
880               key = pair;
881             }
882           }
883           if (key != null)
884           {
885             List<String> vals = set.get(key);
886             if (vals == null)
887             {
888               vals = new ArrayList<String>();
889               set.put(key, vals);
890             }
891             if (value != null)
892             {
893               vals.add(value.trim());
894             }
895           }
896         }
897         try
898         {
899           add &= processGffKey(set, nattr, seq, sf, align, newseqs,
900                   relaxedIdMatching); // process decides if
901                                                      // feature is actually
902                                                      // added
903         } catch (InvalidGFF3FieldException ivfe)
904         {
905           System.err.println(ivfe);
906         }
907       }
908     }
909     if (add)
910     {
911       seq.addSequenceFeature(sf);
912     }
913     return add;
914   }
915
916   public class InvalidGFF3FieldException extends Exception
917   {
918     String field, value;
919
920     public InvalidGFF3FieldException(String field,
921             Map<String, List<String>> set, String message)
922     {
923       super(message + " (Field was " + field + " and value was "
924               + set.get(field).toString());
925       this.field = field;
926       this.value = set.get(field).toString();
927     }
928
929   }
930
931   /**
932    * take a set of keys for a feature and interpret them
933    * 
934    * @param set
935    * @param nattr
936    * @param seq
937    * @param sf
938    * @return
939    */
940   public boolean processGffKey(Map<String, List<String>> set, int nattr,
941           SequenceI seq, SequenceFeature sf, AlignmentI align,
942           List<SequenceI> newseqs, boolean relaxedIdMatching)
943           throws InvalidGFF3FieldException
944   {
945     String attr;
946     // decide how to interpret according to type
947     if (sf.getType().equals("similarity"))
948     {
949       int strand = sf.getStrand();
950       // exonerate cdna/protein map
951       // look for fields 
952       List<SequenceI> querySeq = findNames(align, newseqs,
953               relaxedIdMatching, set.get(attr="Query"));
954       if (querySeq==null || querySeq.size()!=1)
955       {
956         throw new InvalidGFF3FieldException( attr, set,
957                 "Expecting exactly one sequence in Query field (got "
958                         + set.get(attr) + ")");
959       }
960       if (set.containsKey(attr="Align"))
961       {
962         // process the align maps and create cdna/protein maps
963         // ideally, the query sequences are in the alignment, but maybe not...
964         
965         AlignedCodonFrame alco = new AlignedCodonFrame();
966         MapList codonmapping = constructCodonMappingFromAlign(set, attr,
967                 strand);
968
969         // add codon mapping, and hope!
970         alco.addMap(seq, querySeq.get(0), codonmapping);
971         align.addCodonFrame(alco);
972         // everything that's needed to be done is done
973         // no features to create here !
974         return false;
975       }
976
977     }
978     return true;
979   }
980
981   private MapList constructCodonMappingFromAlign(
982           Map<String, List<String>> set,
983           String attr, int strand) throws InvalidGFF3FieldException
984   {
985     if (strand == 0)
986     {
987       throw new InvalidGFF3FieldException(attr, set,
988               "Invalid strand for a codon mapping (cannot be 0)");
989     }
990     List<Integer> fromrange = new ArrayList<Integer>(), torange = new ArrayList<Integer>();
991     int lastppos = 0, lastpframe = 0;
992     for (String range : set.get(attr))
993     {
994       List<Integer> ints = new ArrayList<Integer>();
995       StringTokenizer st = new StringTokenizer(range, " ");
996       while (st.hasMoreTokens())
997       {
998         String num = st.nextToken();
999         try
1000         {
1001           ints.add(new Integer(num));
1002         } catch (NumberFormatException nfe)
1003         {
1004           throw new InvalidGFF3FieldException(attr, set,
1005                   "Invalid number in field " + num);
1006         }
1007       }
1008       // Align positionInRef positionInQuery LengthInRef
1009       // contig_1146 exonerate:protein2genome:local similarity 8534 11269
1010       // 3652 - . alignment_id 0 ;
1011       // Query DDB_G0269124
1012       // Align 11270 143 120
1013       // corresponds to : 120 bases align at pos 143 in protein to 11270 on
1014       // dna in strand direction
1015       // Align 11150 187 282
1016       // corresponds to : 282 bases align at pos 187 in protein to 11150 on
1017       // dna in strand direction
1018       //
1019       // Align 10865 281 888
1020       // Align 9977 578 1068
1021       // Align 8909 935 375
1022       //
1023       if (ints.size() != 3)
1024       {
1025         throw new InvalidGFF3FieldException(attr, set,
1026                 "Invalid number of fields for this attribute ("
1027                         + ints.size() + ")");
1028       }
1029       fromrange.add(new Integer(ints.get(0).intValue()));
1030       fromrange.add(new Integer(ints.get(0).intValue() + strand
1031               * ints.get(2).intValue()));
1032       // how are intron/exon boundaries that do not align in codons
1033       // represented
1034       if (ints.get(1).equals(lastppos) && lastpframe > 0)
1035       {
1036         // extend existing to map
1037         lastppos += ints.get(2) / 3;
1038         lastpframe = ints.get(2) % 3;
1039         torange.set(torange.size() - 1, new Integer(lastppos));
1040       }
1041       else
1042       {
1043         // new to map range
1044         torange.add(ints.get(1));
1045         lastppos = ints.get(1) + ints.get(2) / 3;
1046         lastpframe = ints.get(2) % 3;
1047         torange.add(new Integer(lastppos));
1048       }
1049     }
1050     // from and to ranges must end up being a series of start/end intervals
1051     if (fromrange.size() % 2 == 1)
1052     {
1053       throw new InvalidGFF3FieldException(attr, set,
1054               "Couldn't parse the DNA alignment range correctly");
1055     }
1056     if (torange.size() % 2 == 1)
1057     {
1058       throw new InvalidGFF3FieldException(attr, set,
1059               "Couldn't parse the protein alignment range correctly");
1060     }
1061     // finally, build the map
1062     int[] frommap = new int[fromrange.size()], tomap = new int[torange
1063             .size()];
1064     int p = 0;
1065     for (Integer ip : fromrange)
1066     {
1067       frommap[p++] = ip.intValue();
1068     }
1069     p = 0;
1070     for (Integer ip : torange)
1071     {
1072       tomap[p++] = ip.intValue();
1073     }
1074
1075     return new MapList(frommap, tomap, 3, 1);
1076   }
1077
1078   private List<SequenceI> findNames(AlignmentI align,
1079           List<SequenceI> newseqs, boolean relaxedIdMatching,
1080           List<String> list)
1081   {
1082     List<SequenceI> found = new ArrayList<SequenceI>();
1083     for (String seqId : list)
1084     {
1085       SequenceI seq = findName(align, seqId, relaxedIdMatching, newseqs);
1086       if (seq != null)
1087       {
1088         found.add(seq);
1089       }
1090     }
1091     return found;
1092   }
1093
1094   private AlignmentI lastmatchedAl = null;
1095
1096   private SequenceIdMatcher matcher = null;
1097
1098   /**
1099    * clear any temporary handles used to speed up ID matching
1100    */
1101   private void resetMatcher()
1102   {
1103     lastmatchedAl = null;
1104     matcher = null;
1105   }
1106
1107   private SequenceI findName(AlignmentI align, String seqId,
1108           boolean relaxedIdMatching, List<SequenceI> newseqs)
1109   {
1110     SequenceI match = null;
1111     if (relaxedIdMatching)
1112     {
1113       if (lastmatchedAl != align)
1114       {
1115         matcher = new SequenceIdMatcher(
1116                 (lastmatchedAl = align).getSequencesArray());
1117         if (newseqs != null)
1118         {
1119           matcher.addAll(newseqs);
1120         }
1121       }
1122       match = matcher.findIdMatch(seqId);
1123     }
1124     else
1125     {
1126       match = align.findName(seqId, true);
1127       if (match == null && newseqs != null)
1128       {
1129         for (SequenceI m : newseqs)
1130         {
1131           if (seqId.equals(m.getName()))
1132           {
1133             return m;
1134           }
1135         }
1136       }
1137       
1138     }
1139     if (match==null && newseqs!=null)
1140     {
1141       match = new SequenceDummy(seqId);
1142       if (relaxedIdMatching)
1143       {
1144         matcher.addAll(Arrays.asList(new SequenceI[]
1145         { match }));
1146       }
1147       // add dummy sequence to the newseqs list
1148       newseqs.add(match);
1149     }
1150     return match;
1151   }
1152   public void parseDescriptionHTML(SequenceFeature sf, boolean removeHTML)
1153   {
1154     if (sf.getDescription() == null)
1155     {
1156       return;
1157     }
1158     jalview.util.ParseHtmlBodyAndLinks parsed = new jalview.util.ParseHtmlBodyAndLinks(
1159             sf.getDescription(), removeHTML, newline);
1160
1161     sf.description = (removeHTML) ? parsed.getNonHtmlContent()
1162             : sf.description;
1163     for (String link : parsed.getLinks())
1164     {
1165       sf.addLink(link);
1166     }
1167
1168   }
1169
1170   /**
1171    * generate a features file for seqs includes non-pos features by default.
1172    * 
1173    * @param seqs
1174    *          source of sequence features
1175    * @param visible
1176    *          hash of feature types and colours
1177    * @return features file contents
1178    */
1179   public String printJalviewFormat(SequenceI[] seqs, Map<String,Object> visible)
1180   {
1181     return printJalviewFormat(seqs, visible, true, true);
1182   }
1183
1184   /**
1185    * generate a features file for seqs with colours from visible (if any)
1186    * 
1187    * @param seqs
1188    *          source of features
1189    * @param visible
1190    *          hash of Colours for each feature type
1191    * @param visOnly
1192    *          when true only feature types in 'visible' will be output
1193    * @param nonpos
1194    *          indicates if non-positional features should be output (regardless
1195    *          of group or type)
1196    * @return features file contents
1197    */
1198   public String printJalviewFormat(SequenceI[] seqs, Map visible,
1199           boolean visOnly, boolean nonpos)
1200   {
1201     StringBuffer out = new StringBuffer();
1202     SequenceFeature[] next;
1203     boolean featuresGen = false;
1204     if (visOnly && !nonpos && (visible == null || visible.size() < 1))
1205     {
1206       // no point continuing.
1207       return "No Features Visible";
1208     }
1209
1210     if (visible != null && visOnly)
1211     {
1212       // write feature colours only if we're given them and we are generating
1213       // viewed features
1214       // TODO: decide if feature links should also be written here ?
1215       Iterator en = visible.keySet().iterator();
1216       String type, color;
1217       while (en.hasNext())
1218       {
1219         type = en.next().toString();
1220
1221         if (visible.get(type) instanceof GraduatedColor)
1222         {
1223           GraduatedColor gc = (GraduatedColor) visible.get(type);
1224           color = (gc.isColourByLabel() ? "label|" : "")
1225                   + Format.getHexString(gc.getMinColor()) + "|"
1226                   + Format.getHexString(gc.getMaxColor())
1227                   + (gc.isAutoScale() ? "|" : "|abso|") + gc.getMin() + "|"
1228                   + gc.getMax() + "|";
1229           if (gc.getThreshType() != AnnotationColourGradient.NO_THRESHOLD)
1230           {
1231             if (gc.getThreshType() == AnnotationColourGradient.BELOW_THRESHOLD)
1232             {
1233               color += "below";
1234             }
1235             else
1236             {
1237               if (gc.getThreshType() != AnnotationColourGradient.ABOVE_THRESHOLD)
1238               {
1239                 System.err.println("WARNING: Unsupported threshold type ("
1240                         + gc.getThreshType() + ") : Assuming 'above'");
1241               }
1242               color += "above";
1243             }
1244             // add the value
1245             color += "|" + gc.getThresh();
1246           }
1247           else
1248           {
1249             color += "none";
1250           }
1251         }
1252         else if (visible.get(type) instanceof java.awt.Color)
1253         {
1254           color = Format.getHexString((java.awt.Color) visible.get(type));
1255         }
1256         else
1257         {
1258           // legacy support for integer objects containing colour triplet values
1259           color = Format.getHexString(new java.awt.Color(Integer
1260                   .parseInt(visible.get(type).toString())));
1261         }
1262         out.append(type);
1263         out.append("\t");
1264         out.append(color);
1265         out.append(newline);
1266       }
1267     }
1268     // Work out which groups are both present and visible
1269     Vector groups = new Vector();
1270     int groupIndex = 0;
1271     boolean isnonpos = false;
1272
1273     for (int i = 0; i < seqs.length; i++)
1274     {
1275       next = seqs[i].getSequenceFeatures();
1276       if (next != null)
1277       {
1278         for (int j = 0; j < next.length; j++)
1279         {
1280           isnonpos = next[j].begin == 0 && next[j].end == 0;
1281           if ((!nonpos && isnonpos)
1282                   || (!isnonpos && visOnly && !visible
1283                           .containsKey(next[j].type)))
1284           {
1285             continue;
1286           }
1287
1288           if (next[j].featureGroup != null
1289                   && !groups.contains(next[j].featureGroup))
1290           {
1291             groups.addElement(next[j].featureGroup);
1292           }
1293         }
1294       }
1295     }
1296
1297     String group = null;
1298     do
1299     {
1300
1301       if (groups.size() > 0 && groupIndex < groups.size())
1302       {
1303         group = groups.elementAt(groupIndex).toString();
1304         out.append(newline);
1305         out.append("STARTGROUP\t");
1306         out.append(group);
1307         out.append(newline);
1308       }
1309       else
1310       {
1311         group = null;
1312       }
1313
1314       for (int i = 0; i < seqs.length; i++)
1315       {
1316         next = seqs[i].getSequenceFeatures();
1317         if (next != null)
1318         {
1319           for (int j = 0; j < next.length; j++)
1320           {
1321             isnonpos = next[j].begin == 0 && next[j].end == 0;
1322             if ((!nonpos && isnonpos)
1323                     || (!isnonpos && visOnly && !visible
1324                             .containsKey(next[j].type)))
1325             {
1326               // skip if feature is nonpos and we ignore them or if we only
1327               // output visible and it isn't non-pos and it's not visible
1328               continue;
1329             }
1330
1331             if (group != null
1332                     && (next[j].featureGroup == null || !next[j].featureGroup
1333                             .equals(group)))
1334             {
1335               continue;
1336             }
1337
1338             if (group == null && next[j].featureGroup != null)
1339             {
1340               continue;
1341             }
1342             // we have features to output
1343             featuresGen = true;
1344             if (next[j].description == null
1345                     || next[j].description.equals(""))
1346             {
1347               out.append(next[j].type + "\t");
1348             }
1349             else
1350             {
1351               if (next[j].links != null
1352                       && next[j].getDescription().indexOf("<html>") == -1)
1353               {
1354                 out.append("<html>");
1355               }
1356
1357               out.append(next[j].description + " ");
1358               if (next[j].links != null)
1359               {
1360                 for (int l = 0; l < next[j].links.size(); l++)
1361                 {
1362                   String label = next[j].links.elementAt(l).toString();
1363                   String href = label.substring(label.indexOf("|") + 1);
1364                   label = label.substring(0, label.indexOf("|"));
1365
1366                   if (next[j].description.indexOf(href) == -1)
1367                   {
1368                     out.append("<a href=\"" + href + "\">" + label + "</a>");
1369                   }
1370                 }
1371
1372                 if (next[j].getDescription().indexOf("</html>") == -1)
1373                 {
1374                   out.append("</html>");
1375                 }
1376               }
1377
1378               out.append("\t");
1379             }
1380             out.append(seqs[i].getName());
1381             out.append("\t-1\t");
1382             out.append(next[j].begin);
1383             out.append("\t");
1384             out.append(next[j].end);
1385             out.append("\t");
1386             out.append(next[j].type);
1387             if (!Float.isNaN(next[j].score))
1388             {
1389               out.append("\t");
1390               out.append(next[j].score);
1391             }
1392             out.append(newline);
1393           }
1394         }
1395       }
1396
1397       if (group != null)
1398       {
1399         out.append("ENDGROUP\t");
1400         out.append(group);
1401         out.append(newline);
1402         groupIndex++;
1403       }
1404       else
1405       {
1406         break;
1407       }
1408
1409     } while (groupIndex < groups.size() + 1);
1410
1411     if (!featuresGen)
1412     {
1413       return "No Features Visible";
1414     }
1415
1416     return out.toString();
1417   }
1418
1419   /**
1420    * generate a gff file for sequence features includes non-pos features by
1421    * default.
1422    * 
1423    * @param seqs
1424    * @param visible
1425    * @return
1426    */
1427   public String printGFFFormat(SequenceI[] seqs, Map<String,Object> visible)
1428   {
1429     return printGFFFormat(seqs, visible, true, true);
1430   }
1431
1432   public String printGFFFormat(SequenceI[] seqs, Map<String,Object> visible,
1433           boolean visOnly, boolean nonpos)
1434   {
1435     StringBuffer out = new StringBuffer();
1436     SequenceFeature[] next;
1437     String source;
1438     boolean isnonpos;
1439     for (int i = 0; i < seqs.length; i++)
1440     {
1441       if (seqs[i].getSequenceFeatures() != null)
1442       {
1443         next = seqs[i].getSequenceFeatures();
1444         for (int j = 0; j < next.length; j++)
1445         {
1446           isnonpos = next[j].begin == 0 && next[j].end == 0;
1447           if ((!nonpos && isnonpos)
1448                   || (!isnonpos && visOnly && !visible
1449                           .containsKey(next[j].type)))
1450           {
1451             continue;
1452           }
1453
1454           source = next[j].featureGroup;
1455           if (source == null)
1456           {
1457             source = next[j].getDescription();
1458           }
1459
1460           out.append(seqs[i].getName());
1461           out.append("\t");
1462           out.append(source);
1463           out.append("\t");
1464           out.append(next[j].type);
1465           out.append("\t");
1466           out.append(next[j].begin);
1467           out.append("\t");
1468           out.append(next[j].end);
1469           out.append("\t");
1470           out.append(next[j].score);
1471           out.append("\t");
1472
1473           if (next[j].getValue("STRAND") != null)
1474           {
1475             out.append(next[j].getValue("STRAND"));
1476             out.append("\t");
1477           }
1478           else
1479           {
1480             out.append(".\t");
1481           }
1482
1483           if (next[j].getValue("FRAME") != null)
1484           {
1485             out.append(next[j].getValue("FRAME"));
1486           }
1487           else
1488           {
1489             out.append(".");
1490           }
1491           // TODO: verify/check GFF - should there be a /t here before attribute
1492           // output ?
1493
1494           if (next[j].getValue("ATTRIBUTES") != null)
1495           {
1496             out.append(next[j].getValue("ATTRIBUTES"));
1497           }
1498
1499           out.append(newline);
1500
1501         }
1502       }
1503     }
1504
1505     return out.toString();
1506   }
1507
1508   /**
1509    * this is only for the benefit of object polymorphism - method does nothing.
1510    */
1511   public void parse()
1512   {
1513     // IGNORED
1514   }
1515
1516   /**
1517    * this is only for the benefit of object polymorphism - method does nothing.
1518    * 
1519    * @return error message
1520    */
1521   public String print()
1522   {
1523     return "USE printGFFFormat() or printJalviewFormat()";
1524   }
1525
1526 }