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.AlignmentUtils;
  24 import jalview.analysis.SequenceIdMatcher;
  25 import jalview.api.AlignViewportI;
  26 import jalview.api.FeaturesSourceI;
  27 import jalview.datamodel.AlignedCodonFrame;
  28 import jalview.datamodel.Alignment;
  29 import jalview.datamodel.AlignmentI;
  30 import jalview.datamodel.SequenceDummy;
  31 import jalview.datamodel.SequenceFeature;
  32 import jalview.datamodel.SequenceI;
  33 import jalview.io.gff.GffHelperBase;
  34 import jalview.io.gff.GffHelperFactory;
  35 import jalview.io.gff.GffHelperI;
  36 import jalview.schemes.AnnotationColourGradient;
  37 import jalview.schemes.GraduatedColor;
  38 import jalview.schemes.UserColourScheme;
  39 import jalview.util.Format;
  40 import jalview.util.MapList;
  41 import jalview.util.ParseHtmlBodyAndLinks;
  42 import jalview.util.StringUtils;
  43
  44 import java.awt.Color;
  45 import java.io.IOException;
  46 import java.util.ArrayList;
  47 import java.util.Arrays;
  48 import java.util.HashMap;
  49 import java.util.Iterator;
  50 import java.util.List;
  51 import java.util.Map;
  52 import java.util.Map.Entry;
  53 import java.util.StringTokenizer;
  54
  55 /**
  56  * Parses and writes features files, which may be in Jalview, GFF2 or GFF3
  57  * format. These are tab-delimited formats but with differences in the use of
  58  * columns.
  59  *
  60  * A Jalview feature file may define feature colours and then declare that the
  61  * remainder of the file is in GFF format with the line 'GFF'.
  62  *
  63  * GFF3 files may include alignment mappings for features, which Jalview will
  64  * attempt to model, and may include sequence data following a ##FASTA line.
  65  *
  66  *
  67  * @author AMW
  68  * @author jbprocter
  69  * @author gmcarstairs
  70  */
  71 public class FeaturesFile extends AlignFile implements FeaturesSourceI
  72 {
  73   private static final String ID_NOT_SPECIFIED = "ID_NOT_SPECIFIED";
  74
  75   private static final String NOTE = "Note";
  76
  77   protected static final String FRAME = "FRAME";
  78
  79   protected static final String TAB = "\t";
  80
  81   protected static final String GFF_VERSION = "##gff-version";
  82
  83   private AlignmentI lastmatchedAl = null;
  84
  85   private SequenceIdMatcher matcher = null;
  86
  87   protected AlignmentI dataset;
  88
  89   protected int gffVersion;
  90
  91   /**
  92    * Creates a new FeaturesFile object.
  93    */
  94   public FeaturesFile()
  95   {
  96   }
  97
  98   /**
  99    * Constructor which does not parse the file immediately
 100    *
 101    * @param inFile
 102    * @param type
 103    * @throws IOException
 104    */
 105   public FeaturesFile(String inFile, String type) throws IOException
 106   {
 107     super(false, inFile, type);
 108   }
 109
 110   /**
 111    * @param source
 112    * @throws IOException
 113    */
 114   public FeaturesFile(FileParse source) throws IOException
 115   {
 116     super(source);
 117   }
 118
 119   /**
 120    * Constructor that optionally parses the file immediately
 121    *
 122    * @param parseImmediately
 123    * @param inFile
 124    * @param type
 125    * @throws IOException
 126    */
 127   public FeaturesFile(boolean parseImmediately, String inFile, String type)
 128           throws IOException
 129   {
 130     super(parseImmediately, inFile, type);
 131   }
 132
 133   /**
 134    * Parse GFF or sequence features file using case-independent matching,
 135    * discarding URLs
 136    *
 137    * @param align
 138    *          - alignment/dataset containing sequences that are to be annotated
 139    * @param colours
 140    *          - hashtable to store feature colour definitions
 141    * @param removeHTML
 142    *          - process html strings into plain text
 143    * @return true if features were added
 144    */
 145   public boolean parse(AlignmentI align, Map<String, Object> colours,
 146           boolean removeHTML)
 147   {
 148     return parse(align, colours, removeHTML, false);
 149   }
 150
 151   /**
 152    * Extends the default addProperties by also adding peptide-to-cDNA mappings
 153    * (if any) derived while parsing a GFF file
 154    */
 155   @Override
 156   public void addProperties(AlignmentI al)
 157   {
 158     super.addProperties(al);
 159     if (dataset != null && dataset.getCodonFrames() != null)
 160     {
 161       AlignmentI ds = (al.getDataset() == null) ? al : al.getDataset();
 162       for (AlignedCodonFrame codons : dataset.getCodonFrames())
 163       {
 164         ds.addCodonFrame(codons);
 165       }
 166     }
 167   }
 168
 169   /**
 170    * Parse GFF or Jalview format sequence features file
 171    *
 172    * @param align
 173    *          - alignment/dataset containing sequences that are to be annotated
 174    * @param colours
 175    *          - hashtable to store feature colour definitions
 176    * @param removeHTML
 177    *          - process html strings into plain text
 178    * @param relaxedIdmatching
 179    *          - when true, ID matches to compound sequence IDs are allowed
 180    * @return true if features were added
 181    */
 182   public boolean parse(AlignmentI align, Map<String, Object> colours,
 183           boolean removeHTML, boolean relaxedIdmatching)
 184   {
 185     Map<String, String> gffProps = new HashMap<String, String>();
 186     /*
 187      * keep track of any sequences we try to create from the data
 188      */
 189     List<SequenceI> newseqs = new ArrayList<SequenceI>();
 190
 191     String line = null;
 192     try
 193     {
 194       String[] gffColumns;
 195       String featureGroup = null;
 196
 197       while ((line = nextLine()) != null)
 198       {
 199         // skip comments/process pragmas
 200         if (line.length() == 0 || line.startsWith("#"))
 201         {
 202           if (line.toLowerCase().startsWith("##"))
 203           {
 204             processGffPragma(line, gffProps, align, newseqs);
 205           }
 206           continue;
 207         }
 208
 209         gffColumns = line.split("\\t"); // tab as regex
 210         if (gffColumns.length == 1)
 211         {
 212           if (line.trim().equalsIgnoreCase("GFF"))
 213           {
 214             /*
 215              * Jalview features file with appended GFF
 216              * assume GFF2 (though it may declare ##gff-version 3)
 217              */
 218             gffVersion = 2;
 219             continue;
 220           }
 221         }
 222
 223         if (gffColumns.length > 1 && gffColumns.length < 4)
 224         {
 225           /*
 226            * if 2 or 3 tokens, we anticipate either 'startgroup', 'endgroup' or
 227            * a feature type colour specification
 228            */
 229           String ft = gffColumns[0];
 230           if (ft.equalsIgnoreCase("startgroup"))
 231           {
 232             featureGroup = gffColumns[1];
 233           }
 234           else if (ft.equalsIgnoreCase("endgroup"))
 235           {
 236             // We should check whether this is the current group,
 237             // but at present theres no way of showing more than 1 group
 238             featureGroup = null;
 239           }
 240           else
 241           {
 242             parseFeatureColour(line, ft, gffColumns, colours);
 243           }
 244           continue;
 245         }
 246
 247         /*
 248          * if not a comment, GFF pragma, startgroup, endgroup or feature
 249          * colour specification, that just leaves a feature details line
 250          * in either Jalview or GFF format
 251          */
 252         if (gffVersion == 0)
 253         {
 254           parseJalviewFeature(line, gffColumns, align, colours, removeHTML,
 255                   relaxedIdmatching, featureGroup);
 256         }
 257         else
 258         {
 259           parseGff(gffColumns, align, relaxedIdmatching, newseqs);
 260         }
 261       }
 262       resetMatcher();
 263     } catch (Exception ex)
 264     {
 265       // should report somewhere useful for UI if necessary
 266       warningMessage = ((warningMessage == null) ? "" : warningMessage)
 267               + "Parsing error at\n" + line;
 268       System.out.println("Error parsing feature file: " + ex + "\n" + line);
 269       ex.printStackTrace(System.err);
 270       resetMatcher();
 271       return false;
 272     }
 273
 274     /*
 275      * experimental - add any dummy sequences with features to the alignment
 276      * - we need them for Ensembl feature extraction - though maybe not otherwise
 277      */
 278     for (SequenceI newseq : newseqs)
 279     {
 280       if (newseq.getSequenceFeatures() != null)
 281       {
 282         align.addSequence(newseq);
 283       }
 284     }
 285     return true;
 286   }
 287
 288   /**
 289    * Try to parse a Jalview format feature specification and add it as a
 290    * sequence feature to any matching sequences in the alignment. Returns true
 291    * if successful (a feature was added), or false if not.
 292    *
 293    * @param line
 294    * @param gffColumns
 295    * @param alignment
 296    * @param featureColours
 297    * @param removeHTML
 298    * @param relaxedIdmatching
 299    * @param featureGroup
 300    */
 301   protected boolean parseJalviewFeature(String line, String[] gffColumns,
 302           AlignmentI alignment, Map<String, Object> featureColours,
 303           boolean removeHTML, boolean relaxedIdMatching, String featureGroup)
 304   {
 305     /*
 306      * tokens: description seqid seqIndex start end type [score]
 307      */
 308     if (gffColumns.length < 6)
 309     {
 310       System.err.println("Ignoring feature line '" + line
 311               + "' with too few columns (" + gffColumns.length + ")");
 312       return false;
 313     }
 314     String desc = gffColumns[0];
 315     String seqId = gffColumns[1];
 316     SequenceI seq = findSequence(seqId, alignment, null, relaxedIdMatching);
 317
 318     if (!ID_NOT_SPECIFIED.equals(seqId))
 319     {
 320       seq = findSequence(seqId, alignment, null, relaxedIdMatching);
 321     }
 322     else
 323     {
 324       seqId = null;
 325       seq = null;
 326       String seqIndex = gffColumns[2];
 327       try
 328       {
 329         int idx = Integer.parseInt(seqIndex);
 330         seq = alignment.getSequenceAt(idx);
 331       } catch (NumberFormatException ex)
 332       {
 333         System.err.println("Invalid sequence index: " + seqIndex);
 334       }
 335     }
 336
 337     if (seq == null)
 338     {
 339       System.out.println("Sequence not found: " + line);
 340       return false;
 341     }
 342
 343     int startPos = Integer.parseInt(gffColumns[3]);
 344     int endPos = Integer.parseInt(gffColumns[4]);
 345
 346     String ft = gffColumns[5];
 347
 348     if (!featureColours.containsKey(ft))
 349     {
 350       /*
 351        * Perhaps an old style groups file with no colours -
 352        * synthesize a colour from the feature type
 353        */
 354       UserColourScheme ucs = new UserColourScheme(ft);
 355       featureColours.put(ft, ucs.findColour('A'));
 356     }
 357     SequenceFeature sf = new SequenceFeature(ft, desc, "", startPos,
 358             endPos, featureGroup);
 359     if (gffColumns.length > 6)
 360     {
 361       float score = Float.NaN;
 362       try
 363       {
 364         score = new Float(gffColumns[6]).floatValue();
 365         // update colourgradient bounds if allowed to
 366       } catch (NumberFormatException ex)
 367       {
 368         // leave as NaN
 369       }
 370       sf.setScore(score);
 371     }
 372
 373     parseDescriptionHTML(sf, removeHTML);
 374
 375     seq.addSequenceFeature(sf);
 376
 377     while (seqId != null
 378             && (seq = alignment.findName(seq, seqId, false)) != null)
 379     {
 380       seq.addSequenceFeature(new SequenceFeature(sf));
 381     }
 382     return true;
 383   }
 384
 385   /**
 386    * Process a feature type colour specification
 387    *
 388    * @param line
 389    *          the current input line (for error messages only)
 390    * @param featureType
 391    *          the first token on the line
 392    * @param gffColumns
 393    *          holds tokens on the line
 394    * @param colours
 395    *          map to which to add derived colour specification
 396    */
 397   protected void parseFeatureColour(String line, String featureType,
 398           String[] gffColumns, Map<String, Object> colours)
 399   {
 400     Object colour = null;
 401     String colscheme = gffColumns[1];
 402     if (colscheme.indexOf("|") > -1
 403             || colscheme.trim().equalsIgnoreCase("label"))
 404     {
 405       colour = parseGraduatedColourScheme(line, colscheme);
 406     }
 407     else
 408     {
 409       UserColourScheme ucs = new UserColourScheme(colscheme);
 410       colour = ucs.findColour('A');
 411     }
 412     if (colour != null)
 413     {
 414       colours.put(featureType, colour);
 415     }
 416   }
 417
 418   /**
 419    * Parse a Jalview graduated colour descriptor
 420    *
 421    * @param line
 422    * @param colourDescriptor
 423    * @return
 424    */
 425   protected GraduatedColor parseGraduatedColourScheme(String line,
 426           String colourDescriptor)
 427   {
 428     // Parse '|' separated graduated colourscheme fields:
 429     // [label|][mincolour|maxcolour|[absolute|]minvalue|maxvalue|thresholdtype|thresholdvalue]
 430     // can either provide 'label' only, first is optional, next two
 431     // colors are required (but may be
 432     // left blank), next is optional, nxt two min/max are required.
 433     // first is either 'label'
 434     // first/second and third are both hexadecimal or word equivalent
 435     // colour.
 436     // next two are values parsed as floats.
 437     // fifth is either 'above','below', or 'none'.
 438     // sixth is a float value and only required when fifth is either
 439     // 'above' or 'below'.
 440     StringTokenizer gcol = new StringTokenizer(colourDescriptor, "|", true);
 441     // set defaults
 442     float min = Float.MIN_VALUE, max = Float.MAX_VALUE;
 443     boolean labelCol = false;
 444     // Parse spec line
 445     String mincol = gcol.nextToken();
 446     if (mincol == "|")
 447     {
 448       System.err
 449               .println("Expected either 'label' or a colour specification in the line: "
 450                       + line);
 451       return null;
 452     }
 453     String maxcol = null;
 454     if (mincol.toLowerCase().indexOf("label") == 0)
 455     {
 456       labelCol = true;
 457       mincol = (gcol.hasMoreTokens() ? gcol.nextToken() : null); // skip '|'
 458       mincol = (gcol.hasMoreTokens() ? gcol.nextToken() : null);
 459     }
 460     String abso = null, minval, maxval;
 461     if (mincol != null)
 462     {
 463       // at least four more tokens
 464       if (mincol.equals("|"))
 465       {
 466         mincol = "";
 467       }
 468       else
 469       {
 470         gcol.nextToken(); // skip next '|'
 471       }
 472       // continue parsing rest of line
 473       maxcol = gcol.nextToken();
 474       if (maxcol.equals("|"))
 475       {
 476         maxcol = "";
 477       }
 478       else
 479       {
 480         gcol.nextToken(); // skip next '|'
 481       }
 482       abso = gcol.nextToken();
 483       gcol.nextToken(); // skip next '|'
 484       if (abso.toLowerCase().indexOf("abso") != 0)
 485       {
 486         minval = abso;
 487         abso = null;
 488       }
 489       else
 490       {
 491         minval = gcol.nextToken();
 492         gcol.nextToken(); // skip next '|'
 493       }
 494       maxval = gcol.nextToken();
 495       if (gcol.hasMoreTokens())
 496       {
 497         gcol.nextToken(); // skip next '|'
 498       }
 499       try
 500       {
 501         if (minval.length() > 0)
 502         {
 503           min = Float.valueOf(minval);
 504         }
 505       } catch (Exception e)
 506       {
 507         System.err
 508                 .println("Couldn't parse the minimum value for graduated colour for type ("
 509                         + colourDescriptor
 510                         + ") - did you misspell 'auto' for the optional automatic colour switch ?");
 511         e.printStackTrace();
 512       }
 513       try
 514       {
 515         if (maxval.length() > 0)
 516         {
 517           max = Float.valueOf(maxval);
 518         }
 519       } catch (Exception e)
 520       {
 521         System.err
 522                 .println("Couldn't parse the maximum value for graduated colour for type ("
 523                         + colourDescriptor + ")");
 524         e.printStackTrace();
 525       }
 526     }
 527     else
 528     {
 529       // add in some dummy min/max colours for the label-only
 530       // colourscheme.
 531       mincol = "FFFFFF";
 532       maxcol = "000000";
 533     }
 534
 535     GraduatedColor colour = null;
 536     try
 537     {
 538       colour = new GraduatedColor(
 539               new UserColourScheme(mincol).findColour('A'),
 540               new UserColourScheme(maxcol).findColour('A'), min, max);
 541     } catch (Exception e)
 542     {
 543       System.err.println("Couldn't parse the graduated colour scheme ("
 544               + colourDescriptor + ")");
 545       e.printStackTrace();
 546     }
 547     if (colour != null)
 548     {
 549       colour.setColourByLabel(labelCol);
 550       colour.setAutoScaled(abso == null);
 551       // add in any additional parameters
 552       String ttype = null, tval = null;
 553       if (gcol.hasMoreTokens())
 554       {
 555         // threshold type and possibly a threshold value
 556         ttype = gcol.nextToken();
 557         if (ttype.toLowerCase().startsWith("below"))
 558         {
 559           colour.setThreshType(AnnotationColourGradient.BELOW_THRESHOLD);
 560         }
 561         else if (ttype.toLowerCase().startsWith("above"))
 562         {
 563           colour.setThreshType(AnnotationColourGradient.ABOVE_THRESHOLD);
 564         }
 565         else
 566         {
 567           colour.setThreshType(AnnotationColourGradient.NO_THRESHOLD);
 568           if (!ttype.toLowerCase().startsWith("no"))
 569           {
 570             System.err.println("Ignoring unrecognised threshold type : "
 571                     + ttype);
 572           }
 573         }
 574       }
 575       if (colour.getThreshType() != AnnotationColourGradient.NO_THRESHOLD)
 576       {
 577         try
 578         {
 579           gcol.nextToken();
 580           tval = gcol.nextToken();
 581           colour.setThresh(new Float(tval).floatValue());
 582         } catch (Exception e)
 583         {
 584           System.err.println("Couldn't parse threshold value as a float: ("
 585                   + tval + ")");
 586           e.printStackTrace();
 587         }
 588       }
 589       // parse the thresh-is-min token ?
 590       if (gcol.hasMoreTokens())
 591       {
 592         System.err
 593                 .println("Ignoring additional tokens in parameters in graduated colour specification\n");
 594         while (gcol.hasMoreTokens())
 595         {
 596           System.err.println("|" + gcol.nextToken());
 597         }
 598         System.err.println("\n");
 599       }
 600     }
 601     return colour;
 602   }
 603
 604   /**
 605    * clear any temporary handles used to speed up ID matching
 606    */
 607   protected void resetMatcher()
 608   {
 609     lastmatchedAl = null;
 610     matcher = null;
 611   }
 612
 613   /**
 614    * Returns a sequence matching the given id, as follows
 615    * <ul>
 616    * <li>strict matching is on exact sequence name</li>
 617    * <li>relaxed matching allows matching on a token within the sequence name,
 618    * or a dbxref</li>
 619    * <li>first tries to find a match in the alignment sequences</li>
 620    * <li>else tries to find a match in the new sequences already generated while
 621    * parsing the features file</li>
 622    * <li>else creates a new placeholder sequence, adds it to the new sequences
 623    * list, and returns it</li>
 624    * </ul>
 625    *
 626    * @param seqId
 627    * @param align
 628    * @param newseqs
 629    * @param relaxedIdMatching
 630    *
 631    * @return
 632    */
 633   protected SequenceI findSequence(String seqId, AlignmentI align,
 634           List<SequenceI> newseqs, boolean relaxedIdMatching)
 635   {
 636     // TODO encapsulate in SequenceIdMatcher, share the matcher
 637     // with the GffHelper (removing code duplication)
 638     SequenceI match = null;
 639     if (relaxedIdMatching)
 640     {
 641       if (lastmatchedAl != align)
 642       {
 643         lastmatchedAl = align;
 644         matcher = new SequenceIdMatcher(align.getSequencesArray());
 645         if (newseqs != null)
 646         {
 647           matcher.addAll(newseqs);
 648         }
 649       }
 650       match = matcher.findIdMatch(seqId);
 651     }
 652     else
 653     {
 654       match = align.findName(seqId, true);
 655       if (match == null && newseqs != null)
 656       {
 657         for (SequenceI m : newseqs)
 658         {
 659           if (seqId.equals(m.getName()))
 660           {
 661             return m;
 662           }
 663         }
 664       }
 665
 666     }
 667     if (match == null && newseqs != null)
 668     {
 669       match = new SequenceDummy(seqId);
 670       if (relaxedIdMatching)
 671       {
 672         matcher.addAll(Arrays.asList(new SequenceI[] { match }));
 673       }
 674       // add dummy sequence to the newseqs list
 675       newseqs.add(match);
 676     }
 677     return match;
 678   }
 679
 680   public void parseDescriptionHTML(SequenceFeature sf, boolean removeHTML)
 681   {
 682     if (sf.getDescription() == null)
 683     {
 684       return;
 685     }
 686     ParseHtmlBodyAndLinks parsed = new ParseHtmlBodyAndLinks(
 687             sf.getDescription(), removeHTML, newline);
 688
 689     sf.description = (removeHTML) ? parsed.getNonHtmlContent()
 690             : sf.description;
 691     for (String link : parsed.getLinks())
 692     {
 693       sf.addLink(link);
 694     }
 695
 696   }
 697
 698   /**
 699    * generate a features file for seqs includes non-pos features by default.
 700    *
 701    * @param sequences
 702    *          source of sequence features
 703    * @param visible
 704    *          hash of feature types and colours
 705    * @return features file contents
 706    */
 707   public String printJalviewFormat(SequenceI[] sequences,
 708           Map<String, Object> visible)
 709   {
 710     return printJalviewFormat(sequences, visible, true, true);
 711   }
 712
 713   /**
 714    * generate a features file for seqs with colours from visible (if any)
 715    *
 716    * @param sequences
 717    *          source of features
 718    * @param visible
 719    *          hash of Colours for each feature type
 720    * @param visOnly
 721    *          when true only feature types in 'visible' will be output
 722    * @param nonpos
 723    *          indicates if non-positional features should be output (regardless
 724    *          of group or type)
 725    * @return features file contents
 726    */
 727   public String printJalviewFormat(SequenceI[] sequences,
 728           Map<String, Object> visible, boolean visOnly, boolean nonpos)
 729   {
 730     StringBuilder out = new StringBuilder(256);
 731     boolean featuresGen = false;
 732     if (visOnly && !nonpos && (visible == null || visible.size() < 1))
 733     {
 734       // no point continuing.
 735       return "No Features Visible";
 736     }
 737
 738     if (visible != null && visOnly)
 739     {
 740       // write feature colours only if we're given them and we are generating
 741       // viewed features
 742       // TODO: decide if feature links should also be written here ?
 743       Iterator<String> en = visible.keySet().iterator();
 744       String featureType, color;
 745       while (en.hasNext())
 746       {
 747         featureType = en.next().toString();
 748
 749         if (visible.get(featureType) instanceof GraduatedColor)
 750         {
 751           GraduatedColor gc = (GraduatedColor) visible.get(featureType);
 752           color = (gc.isColourByLabel() ? "label|" : "")
 753                   + Format.getHexString(gc.getMinColor()) + "|"
 754                   + Format.getHexString(gc.getMaxColor())
 755                   + (gc.isAutoScale() ? "|" : "|abso|") + gc.getMin() + "|"
 756                   + gc.getMax() + "|";
 757           if (gc.getThreshType() != AnnotationColourGradient.NO_THRESHOLD)
 758           {
 759             if (gc.getThreshType() == AnnotationColourGradient.BELOW_THRESHOLD)
 760             {
 761               color += "below";
 762             }
 763             else
 764             {
 765               if (gc.getThreshType() != AnnotationColourGradient.ABOVE_THRESHOLD)
 766               {
 767                 System.err.println("WARNING: Unsupported threshold type ("
 768                         + gc.getThreshType() + ") : Assuming 'above'");
 769               }
 770               color += "above";
 771             }
 772             // add the value
 773             color += "|" + gc.getThresh();
 774           }
 775           else
 776           {
 777             color += "none";
 778           }
 779         }
 780         else if (visible.get(featureType) instanceof Color)
 781         {
 782           color = Format.getHexString((Color) visible.get(featureType));
 783         }
 784         else
 785         {
 786           // legacy support for integer objects containing colour triplet values
 787           color = Format.getHexString(new Color(Integer.parseInt(visible
 788                   .get(featureType).toString())));
 789         }
 790         out.append(featureType);
 791         out.append(TAB);
 792         out.append(color);
 793         out.append(newline);
 794       }
 795     }
 796     // Work out which groups are both present and visible
 797     List<String> groups = new ArrayList<String>();
 798     int groupIndex = 0;
 799     boolean isnonpos = false;
 800
 801     SequenceFeature[] features;
 802     for (int i = 0; i < sequences.length; i++)
 803     {
 804       features = sequences[i].getSequenceFeatures();
 805       if (features != null)
 806       {
 807         for (int j = 0; j < features.length; j++)
 808         {
 809           isnonpos = features[j].begin == 0 && features[j].end == 0;
 810           if ((!nonpos && isnonpos)
 811                   || (!isnonpos && visOnly && !visible
 812                           .containsKey(features[j].type)))
 813           {
 814             continue;
 815           }
 816
 817           if (features[j].featureGroup != null
 818                   && !groups.contains(features[j].featureGroup))
 819           {
 820             groups.add(features[j].featureGroup);
 821           }
 822         }
 823       }
 824     }
 825
 826     String group = null;
 827     do
 828     {
 829       if (groups.size() > 0 && groupIndex < groups.size())
 830       {
 831         group = groups.get(groupIndex);
 832         out.append(newline);
 833         out.append("STARTGROUP").append(TAB);
 834         out.append(group);
 835         out.append(newline);
 836       }
 837       else
 838       {
 839         group = null;
 840       }
 841
 842       for (int i = 0; i < sequences.length; i++)
 843       {
 844         features = sequences[i].getSequenceFeatures();
 845         if (features != null)
 846         {
 847           for (int j = 0; j < features.length; j++)
 848           {
 849             isnonpos = features[j].begin == 0 && features[j].end == 0;
 850             if ((!nonpos && isnonpos)
 851                     || (!isnonpos && visOnly && !visible
 852                             .containsKey(features[j].type)))
 853             {
 854               // skip if feature is nonpos and we ignore them or if we only
 855               // output visible and it isn't non-pos and it's not visible
 856               continue;
 857             }
 858
 859             if (group != null
 860                     && (features[j].featureGroup == null || !features[j].featureGroup
 861                             .equals(group)))
 862             {
 863               continue;
 864             }
 865
 866             if (group == null && features[j].featureGroup != null)
 867             {
 868               continue;
 869             }
 870             // we have features to output
 871             featuresGen = true;
 872             if (features[j].description == null
 873                     || features[j].description.equals(""))
 874             {
 875               out.append(features[j].type).append(TAB);
 876             }
 877             else
 878             {
 879               if (features[j].links != null
 880                       && features[j].getDescription().indexOf("<html>") == -1)
 881               {
 882                 out.append("<html>");
 883               }
 884
 885               out.append(features[j].description + " ");
 886               if (features[j].links != null)
 887               {
 888                 for (int l = 0; l < features[j].links.size(); l++)
 889                 {
 890                   String label = features[j].links.elementAt(l).toString();
 891                   String href = label.substring(label.indexOf("|") + 1);
 892                   label = label.substring(0, label.indexOf("|"));
 893
 894                   if (features[j].description.indexOf(href) == -1)
 895                   {
 896                     out.append("<a href=\"" + href + "\">" + label + "</a>");
 897                   }
 898                 }
 899
 900                 if (features[j].getDescription().indexOf("</html>") == -1)
 901                 {
 902                   out.append("</html>");
 903                 }
 904               }
 905
 906               out.append(TAB);
 907             }
 908             out.append(sequences[i].getName());
 909             out.append("\t-1\t");
 910             out.append(features[j].begin);
 911             out.append(TAB);
 912             out.append(features[j].end);
 913             out.append(TAB);
 914             out.append(features[j].type);
 915             if (!Float.isNaN(features[j].score))
 916             {
 917               out.append(TAB);
 918               out.append(features[j].score);
 919             }
 920             out.append(newline);
 921           }
 922         }
 923       }
 924
 925       if (group != null)
 926       {
 927         out.append("ENDGROUP").append(TAB);
 928         out.append(group);
 929         out.append(newline);
 930         groupIndex++;
 931       }
 932       else
 933       {
 934         break;
 935       }
 936
 937     } while (groupIndex < groups.size() + 1);
 938
 939     if (!featuresGen)
 940     {
 941       return "No Features Visible";
 942     }
 943
 944     return out.toString();
 945   }
 946
 947   /**
 948    * Parse method that is called when a GFF file is dragged to the desktop
 949    */
 950   @Override
 951   public void parse()
 952   {
 953     AlignViewportI av = getViewport();
 954     if (av != null)
 955     {
 956       if (av.getAlignment() != null)
 957       {
 958         dataset = av.getAlignment().getDataset();
 959       }
 960       if (dataset == null)
 961       {
 962         // working in the applet context ?
 963         dataset = av.getAlignment();
 964       }
 965     }
 966     else
 967     {
 968       dataset = new Alignment(new SequenceI[] {});
 969     }
 970
 971     boolean parseResult = parse(dataset, null, false, true);
 972     if (!parseResult)
 973     {
 974       // pass error up somehow
 975     }
 976     if (av != null)
 977     {
 978       // update viewport with the dataset data ?
 979     }
 980     else
 981     {
 982       setSeqs(dataset.getSequencesArray());
 983     }
 984   }
 985
 986   /**
 987    * Implementation of unused abstract method
 988    *
 989    * @return error message
 990    */
 991   @Override
 992   public String print()
 993   {
 994     return "Use printGffFormat() or printJalviewFormat()";
 995   }
 996
 997   /**
 998    * Returns features output in GFF2 format, including hidden and non-positional
 999    * features
1000    *
1001    * @param sequences
1002    *          the sequences whose features are to be output
1003    * @param visible
1004    *          a map whose keys are the type names of visible features
1005    * @return
1006    */
1007   public String printGffFormat(SequenceI[] sequences,
1008           Map<String, Object> visible)
1009   {
1010     return printGffFormat(sequences, visible, true, true);
1011   }
1012
1013   /**
1014    * Returns features output in GFF2 format
1015    *
1016    * @param sequences
1017    *          the sequences whose features are to be output
1018    * @param visible
1019    *          a map whose keys are the type names of visible features
1020    * @param outputVisibleOnly
1021    * @param includeNonPositionalFeatures
1022    * @return
1023    */
1024   public String printGffFormat(SequenceI[] sequences,
1025           Map<String, Object> visible, boolean outputVisibleOnly,
1026           boolean includeNonPositionalFeatures)
1027   {
1028     StringBuilder out = new StringBuilder(256);
1029     out.append(String.format("%s %d\n", GFF_VERSION, gffVersion));
1030     String source;
1031     boolean isnonpos;
1032     for (SequenceI seq : sequences)
1033     {
1034       SequenceFeature[] features = seq.getSequenceFeatures();
1035       if (features != null)
1036       {
1037         for (SequenceFeature sf : features)
1038         {
1039           isnonpos = sf.begin == 0 && sf.end == 0;
1040           if (!includeNonPositionalFeatures && isnonpos)
1041           {
1042             /*
1043              * ignore non-positional features if not wanted
1044              */
1045             continue;
1046           }
1047           // TODO why the test !isnonpos here?
1048           // what about not visible non-positional features?
1049           if (!isnonpos && outputVisibleOnly
1050                   && !visible.containsKey(sf.type))
1051           {
1052             /*
1053              * ignore not visible features if not wanted
1054              */
1055             continue;
1056           }
1057
1058           source = sf.featureGroup;
1059           if (source == null)
1060           {
1061             source = sf.getDescription();
1062           }
1063
1064           out.append(seq.getName());
1065           out.append(TAB);
1066           out.append(source);
1067           out.append(TAB);
1068           out.append(sf.type);
1069           out.append(TAB);
1070           out.append(sf.begin);
1071           out.append(TAB);
1072           out.append(sf.end);
1073           out.append(TAB);
1074           out.append(sf.score);
1075           out.append(TAB);
1076
1077           int strand = sf.getStrand();
1078           out.append(strand == 1 ? "+" : (strand == -1 ? "-" : "."));
1079           out.append(TAB);
1080
1081           out.append(sf.getValue(FRAME, "."));
1082
1083           // miscellaneous key-values (GFF column 9)
1084           String attributes = sf.getAttributes();
1085           if (attributes != null)
1086           {
1087             out.append(TAB).append(attributes);
1088           }
1089
1090           out.append(newline);
1091         }
1092       }
1093     }
1094
1095     return out.toString();
1096   }
1097
1098   /**
1099    * Returns a mapping given list of one or more Align descriptors (exonerate
1100    * format)
1101    *
1102    * @param alignedRegions
1103    *          a list of "Align fromStart toStart fromCount"
1104    * @param mapIsFromCdna
1105    *          if true, 'from' is dna, else 'from' is protein
1106    * @param strand
1107    *          either 1 (forward) or -1 (reverse)
1108    * @return
1109    * @throws IOException
1110    */
1111   protected MapList constructCodonMappingFromAlign(
1112           List<String> alignedRegions, boolean mapIsFromCdna, int strand)
1113           throws IOException
1114   {
1115     if (strand == 0)
1116     {
1117       throw new IOException(
1118               "Invalid strand for a codon mapping (cannot be 0)");
1119     }
1120     int regions = alignedRegions.size();
1121     // arrays to hold [start, end] for each aligned region
1122     int[] fromRanges = new int[regions * 2]; // from dna
1123     int[] toRanges = new int[regions * 2]; // to protein
1124     int fromRangesIndex = 0;
1125     int toRangesIndex = 0;
1126
1127     for (String range : alignedRegions)
1128     {
1129       /*
1130        * Align mapFromStart mapToStart mapFromCount
1131        * e.g. if mapIsFromCdna
1132        *     Align 11270 143 120
1133        * means:
1134        *     120 bases from pos 11270 align to pos 143 in peptide
1135        * if !mapIsFromCdna this would instead be
1136        *     Align 143 11270 40
1137        */
1138       String[] tokens = range.split(" ");
1139       if (tokens.length != 3)
1140       {
1141         throw new IOException("Wrong number of fields for Align");
1142       }
1143       int fromStart = 0;
1144       int toStart = 0;
1145       int fromCount = 0;
1146       try
1147       {
1148         fromStart = Integer.parseInt(tokens[0]);
1149         toStart = Integer.parseInt(tokens[1]);
1150         fromCount = Integer.parseInt(tokens[2]);
1151       } catch (NumberFormatException nfe)
1152       {
1153         throw new IOException("Invalid number in Align field: "
1154                 + nfe.getMessage());
1155       }
1156
1157       /*
1158        * Jalview always models from dna to protein, so adjust values if the
1159        * GFF mapping is from protein to dna
1160        */
1161       if (!mapIsFromCdna)
1162       {
1163         fromCount *= 3;
1164         int temp = fromStart;
1165         fromStart = toStart;
1166         toStart = temp;
1167       }
1168       fromRanges[fromRangesIndex++] = fromStart;
1169       fromRanges[fromRangesIndex++] = fromStart + strand * (fromCount - 1);
1170
1171       /*
1172        * If a codon has an intron gap, there will be contiguous 'toRanges';
1173        * this is handled for us by the MapList constructor.
1174        * (It is not clear that exonerate ever generates this case)
1175        */
1176       toRanges[toRangesIndex++] = toStart;
1177       toRanges[toRangesIndex++] = toStart + (fromCount - 1) / 3;
1178     }
1179
1180     return new MapList(fromRanges, toRanges, 3, 1);
1181   }
1182
1183   /**
1184    * Parse a GFF format feature. This may include creating a 'dummy' sequence to
1185    * hold the feature, or for its mapped sequence, or both, to be resolved
1186    * either later in the GFF file (##FASTA section), or when the user loads
1187    * additional sequences.
1188    *
1189    * @param gffColumns
1190    * @param alignment
1191    * @param relaxedIdMatching
1192    * @param newseqs
1193    * @return
1194    */
1195   protected SequenceI parseGff(String[] gffColumns, AlignmentI alignment,
1196           boolean relaxedIdMatching, List<SequenceI> newseqs)
1197   {
1198     /*
1199      * GFF: seqid source type start end score strand phase [attributes]
1200      */
1201     if (gffColumns.length < 5)
1202     {
1203       System.err.println("Ignoring GFF feature line with too few columns ("
1204               + gffColumns.length + ")");
1205       return null;
1206     }
1207
1208     /*
1209      * locate referenced sequence in alignment _or_
1210      * as a forward or external reference (SequenceDummy)
1211      */
1212     String seqId = gffColumns[0];
1213     SequenceI seq = findSequence(seqId, alignment, newseqs,
1214             relaxedIdMatching);
1215
1216     SequenceFeature sf = null;
1217     GffHelperI helper = GffHelperFactory.getHelper(gffColumns);
1218     if (helper != null)
1219     {
1220       try
1221       {
1222         sf = helper.processGff(seq, gffColumns, alignment, newseqs,
1223                 relaxedIdMatching);
1224         if (sf != null)
1225         {
1226           seq.addSequenceFeature(sf);
1227           while ((seq = alignment.findName(seq, seqId, true)) != null)
1228           {
1229             seq.addSequenceFeature(new SequenceFeature(sf));
1230           }
1231         }
1232       } catch (IOException e)
1233       {
1234         System.err.println("GFF parsing failed with: " + e.getMessage());
1235         return null;
1236       }
1237     }
1238
1239     return seq;
1240   }
1241
1242   /**
1243    * Process the 'column 9' data of the GFF file. This is less formally defined,
1244    * and its interpretation will vary depending on the tool that has generated
1245    * it.
1246    *
1247    * @param attributes
1248    * @param sf
1249    */
1250   protected void processGffColumnNine(String attributes, SequenceFeature sf)
1251   {
1252     sf.setAttributes(attributes);
1253
1254     /*
1255      * Parse attributes in column 9 and add them to the sequence feature's
1256      * 'otherData' table; use Note as a best proxy for description
1257      */
1258     char nameValueSeparator = gffVersion == 3 ? '=' : ' ';
1259     // TODO check we don't break GFF2 values which include commas here
1260     Map<String, List<String>> nameValues = GffHelperBase
1261             .parseNameValuePairs(attributes, ";", nameValueSeparator, ",");
1262     for (Entry<String, List<String>> attr : nameValues.entrySet())
1263     {
1264       String values = StringUtils.listToDelimitedString(attr.getValue(),
1265               "; ");
1266       sf.setValue(attr.getKey(), values);
1267       if (NOTE.equals(attr.getKey()))
1268       {
1269         sf.setDescription(values);
1270       }
1271     }
1272   }
1273
1274   /**
1275    * After encountering ##fasta in a GFF3 file, process the remainder of the
1276    * file as FAST sequence data. Any placeholder sequences created during
1277    * feature parsing are updated with the actual sequences.
1278    *
1279    * @param align
1280    * @param newseqs
1281    * @throws IOException
1282    */
1283   protected void processAsFasta(AlignmentI align, List<SequenceI> newseqs)
1284           throws IOException
1285   {
1286     try
1287     {
1288       mark();
1289     } catch (IOException q)
1290     {
1291     }
1292     FastaFile parser = new FastaFile(this);
1293     List<SequenceI> includedseqs = parser.getSeqs();
1294
1295     SequenceIdMatcher smatcher = new SequenceIdMatcher(newseqs);
1296
1297     /*
1298      * iterate over includedseqs, and replacing matching ones with newseqs
1299      * sequences. Generic iterator not used here because we modify
1300      * includedseqs as we go
1301      */
1302     for (int p = 0, pSize = includedseqs.size(); p < pSize; p++)
1303     {
1304       // search for any dummy seqs that this sequence can be used to update
1305       SequenceI includedSeq = includedseqs.get(p);
1306       SequenceI dummyseq = smatcher.findIdMatch(includedSeq);
1307       if (dummyseq != null && dummyseq instanceof SequenceDummy)
1308       {
1309         // probably have the pattern wrong
1310         // idea is that a flyweight proxy for a sequence ID can be created for
1311         // 1. stable reference creation
1312         // 2. addition of annotation
1313         // 3. future replacement by a real sequence
1314         // current pattern is to create SequenceDummy objects - a convenience
1315         // constructor for a Sequence.
1316         // problem is that when promoted to a real sequence, all references
1317         // need to be updated somehow. We avoid that by keeping the same object.
1318         ((SequenceDummy) dummyseq).become(includedSeq);
1319         dummyseq.createDatasetSequence();
1320
1321         /*
1322          * Update mappings so they are now to the dataset sequence
1323          */
1324         for (AlignedCodonFrame mapping : align.getCodonFrames())
1325         {
1326           mapping.updateToDataset(dummyseq);
1327         }
1328
1329         /*
1330          * replace parsed sequence with the realised forward reference
1331          */
1332         includedseqs.set(p, dummyseq);
1333
1334         /*
1335          * and remove from the newseqs list
1336          */
1337         newseqs.remove(dummyseq);
1338       }
1339     }
1340
1341     /*
1342      * finally add sequences to the dataset
1343      */
1344     for (SequenceI seq : includedseqs)
1345     {
1346       // experimental: mapping-based 'alignment' to query sequence
1347       AlignmentUtils.alignSequenceAs(seq, align,
1348               String.valueOf(align.getGapCharacter()), false, true);
1349
1350       // rename sequences if GFF handler requested this
1351       // TODO a more elegant way e.g. gffHelper.postProcess(newseqs) ?
1352       SequenceFeature[] sfs = seq.getSequenceFeatures();
1353       if (sfs != null)
1354       {
1355         String newName = (String) sfs[0].getValue(GffHelperI.RENAME_TOKEN);
1356         if (newName != null)
1357         {
1358           seq.setName(newName);
1359         }
1360       }
1361       align.addSequence(seq);
1362     }
1363   }
1364
1365   /**
1366    * Process a ## directive
1367    *
1368    * @param line
1369    * @param gffProps
1370    * @param align
1371    * @param newseqs
1372    * @throws IOException
1373    */
1374   protected void processGffPragma(String line,
1375           Map<String, String> gffProps, AlignmentI align,
1376           List<SequenceI> newseqs) throws IOException
1377   {
1378     line = line.trim();
1379     if ("###".equals(line))
1380     {
1381       // close off any open 'forward references'
1382       return;
1383     }
1384
1385     String[] tokens = line.substring(2).split(" ");
1386     String pragma = tokens[0];
1387     String value = tokens.length == 1 ? null : tokens[1];
1388
1389     if ("gff-version".equalsIgnoreCase(pragma))
1390     {
1391       if (value != null)
1392       {
1393         try
1394         {
1395           // value may be e.g. "3.1.2"
1396           gffVersion = Integer.parseInt(value.split("\\.")[0]);
1397         } catch (NumberFormatException e)
1398         {
1399           // ignore
1400         }
1401       }
1402     }
1403     else if ("sequence-region".equalsIgnoreCase(pragma))
1404     {
1405       // could capture <seqid start end> if wanted here
1406     }
1407     else if ("feature-ontology".equalsIgnoreCase(pragma))
1408     {
1409       // should resolve against the specified feature ontology URI
1410     }
1411     else if ("attribute-ontology".equalsIgnoreCase(pragma))
1412     {
1413       // URI of attribute ontology - not currently used in GFF3
1414     }
1415     else if ("source-ontology".equalsIgnoreCase(pragma))
1416     {
1417       // URI of source ontology - not currently used in GFF3
1418     }
1419     else if ("species-build".equalsIgnoreCase(pragma))
1420     {
1421       // save URI of specific NCBI taxon version of annotations
1422       gffProps.put("species-build", value);
1423     }
1424     else if ("fasta".equalsIgnoreCase(pragma))
1425     {
1426       // process the rest of the file as a fasta file and replace any dummy
1427       // sequence IDs
1428       processAsFasta(align, newseqs);
1429     }
1430     else
1431     {
1432       System.err.println("Ignoring unknown pragma: " + line);
1433     }
1434   }
1435 }