src/jalview/io/SequenceAnnotationReport.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 java.util.Locale;
  24
  25 import java.util.Collection;
  26 import java.util.Comparator;
  27 import java.util.LinkedHashMap;
  28 import java.util.List;
  29 import java.util.Map;
  30
  31 import jalview.api.FeatureColourI;
  32 import jalview.datamodel.DBRefEntry;
  33 import jalview.datamodel.DBRefSource;
  34 import jalview.datamodel.GeneLociI;
  35 import jalview.datamodel.MappedFeatures;
  36 import jalview.datamodel.SequenceFeature;
  37 import jalview.datamodel.SequenceI;
  38 import jalview.util.MessageManager;
  39 import jalview.util.StringUtils;
  40 import jalview.util.UrlLink;
  41 import jalview.viewmodel.seqfeatures.FeatureRendererModel;
  42
  43 /**
  44  * generate HTML reports for a sequence
  45  *
  46  * @author jimp
  47  */
  48 public class SequenceAnnotationReport
  49 {
  50   private static final int MAX_DESCRIPTION_LENGTH = 40;
  51
  52   private static final String COMMA = ",";
  53
  54   private static final String ELLIPSIS = "...";
  55
  56   private static final int MAX_REFS_PER_SOURCE = 4;
  57
  58   private static final int MAX_SOURCES = 40;
  59
  60   private static String linkImageURL;
  61
  62  // public static final String[][] PRIMARY_SOURCES  moved to DBRefSource.java
  63
  64   /*
  65    * Comparator to order DBRefEntry by Source + accession id (case-insensitive),
  66    * with 'Primary' sources placed before others, and 'chromosome' first of all
  67    */
  68   private static Comparator<DBRefEntry> comparator = new Comparator<DBRefEntry>()
  69   {
  70
  71     @Override
  72     public int compare(DBRefEntry ref1, DBRefEntry ref2)
  73     {
  74       if (ref1 instanceof GeneLociI)
  75       {
  76         return -1;
  77       }
  78       if (ref2 instanceof GeneLociI)
  79       {
  80         return 1;
  81       }
  82       String s1 = ref1.getSource();
  83       String s2 = ref2.getSource();
  84       boolean s1Primary = DBRefSource.isPrimarySource(s1);
  85       boolean s2Primary = DBRefSource.isPrimarySource(s2);
  86       if (s1Primary && !s2Primary)
  87       {
  88         return -1;
  89       }
  90       if (!s1Primary && s2Primary)
  91       {
  92         return 1;
  93       }
  94       int comp = s1 == null ? -1 : (s2 == null ? 1 : s1
  95               .compareToIgnoreCase(s2));
  96       if (comp == 0)
  97       {
  98         String a1 = ref1.getAccessionId();
  99         String a2 = ref2.getAccessionId();
 100         comp = a1 == null ? -1 : (a2 == null ? 1 : a1
 101                 .compareToIgnoreCase(a2));
 102       }
 103       return comp;
 104     }
 105
 106 //    private boolean isPrimarySource(String source)
 107 //    {
 108 //      for (String[] primary : DBRefSource.PRIMARY_SOURCES)
 109 //      {
 110 //        for (String s : primary)
 111 //        {
 112 //          if (source.equals(s))
 113 //          {
 114 //            return true;
 115 //          }
 116 //        }
 117 //      }
 118 //      return false;
 119 //    }
 120   };
 121
 122   private boolean forTooltip;
 123
 124   /**
 125    * Constructor given a flag which affects behaviour
 126    * <ul>
 127    * <li>if true, generates feature details suitable to show in a tooltip</li>
 128    * <li>if false, generates feature details in a form suitable for the sequence
 129    * details report</li>
 130    * </ul>
 131    *
 132    * @param isForTooltip
 133    */
 134   public SequenceAnnotationReport(boolean isForTooltip)
 135   {
 136     this.forTooltip = isForTooltip;
 137     if (linkImageURL == null)
 138     {
 139       linkImageURL = getClass().getResource("/images/link.gif").toString();
 140     }
 141   }
 142
 143   /**
 144    * Append text for the list of features to the tooltip. Returns the number of
 145    * features not added if maxlength limit is (or would have been) reached.
 146    *
 147    * @param sb
 148    * @param residuePos
 149    * @param features
 150    * @param minmax
 151    * @param maxlength
 152    */
 153   public int appendFeatures(final StringBuilder sb,
 154           int residuePos, List<SequenceFeature> features,
 155           FeatureRendererModel fr, int maxlength)
 156   {
 157     for (int i = 0; i < features.size(); i++)
 158     {
 159       SequenceFeature feature = features.get(i);
 160       if (appendFeature(sb, residuePos, fr, feature, null, maxlength))
 161       {
 162         return features.size() - i;
 163       }
 164     }
 165     return 0;
 166   }
 167
 168   /**
 169    * Appends text for mapped features (e.g. CDS feature for peptide or vice
 170    * versa) Returns number of features left if maxlength limit is (or would have
 171    * been) reached.
 172    *
 173    * @param sb
 174    * @param residuePos
 175    * @param mf
 176    * @param fr
 177    * @param maxlength
 178    */
 179   public int appendFeatures(StringBuilder sb, int residuePos,
 180           MappedFeatures mf, FeatureRendererModel fr, int maxlength)
 181   {
 182     for (int i = 0; i < mf.features.size(); i++)
 183     {
 184       SequenceFeature feature = mf.features.get(i);
 185       if (appendFeature(sb, residuePos, fr, feature, mf, maxlength))
 186       {
 187         return mf.features.size() - i;
 188       }
 189     }
 190     return 0;
 191   }
 192
 193   /**
 194    * Appends the feature at rpos to the given buffer
 195    *
 196    * @param sb
 197    * @param rpos
 198    * @param minmax
 199    * @param feature
 200    */
 201   boolean appendFeature(final StringBuilder sb0, int rpos,
 202           FeatureRendererModel fr, SequenceFeature feature,
 203           MappedFeatures mf, int maxlength)
 204   {
 205     int begin = feature.getBegin();
 206     int end = feature.getEnd();
 207
 208     /*
 209      * if this is a virtual features, convert begin/end to the
 210      * coordinates of the sequence it is mapped to
 211      */
 212     int[] beginRange = null; // feature start in local coordinates
 213     int[] endRange = null; // feature end in local coordinates
 214     if (mf != null)
 215     {
 216       if (feature.isContactFeature())
 217       {
 218         /*
 219          * map start and end points individually
 220          */
 221         beginRange = mf.getMappedPositions(begin, begin);
 222         endRange = begin == end ? beginRange
 223                 : mf.getMappedPositions(end, end);
 224       }
 225       else
 226       {
 227         /*
 228          * map the feature extent
 229          */
 230         beginRange = mf.getMappedPositions(begin, end);
 231         endRange = beginRange;
 232       }
 233       if (beginRange == null || endRange == null)
 234       {
 235         // something went wrong
 236         return false;
 237       }
 238       begin = beginRange[0];
 239       end = endRange[endRange.length - 1];
 240     }
 241
 242     StringBuilder sb = new StringBuilder();
 243     if (feature.isContactFeature())
 244     {
 245       /*
 246        * include if rpos is at start or end position of [mapped] feature
 247        */
 248       boolean showContact = (mf == null) && (rpos == begin || rpos == end);
 249       boolean showMappedContact = (mf != null) && ((rpos >= beginRange[0]
 250               && rpos <= beginRange[beginRange.length - 1])
 251               || (rpos >= endRange[0]
 252                       && rpos <= endRange[endRange.length - 1]));
 253       if (showContact || showMappedContact)
 254       {
 255         if (sb0.length() > 6)
 256         {
 257           sb.append("<br/>");
 258         }
 259         sb.append(feature.getType()).append(" ").append(begin).append(":")
 260                 .append(end);
 261       }
 262       return appendText(sb0, sb, maxlength);
 263     }
 264
 265     if (sb0.length() > 6)
 266     {
 267       sb.append("<br/>");
 268     }
 269     // TODO: remove this hack to display link only features
 270     boolean linkOnly = feature.getValue("linkonly") != null;
 271     if (!linkOnly)
 272     {
 273       sb.append(feature.getType()).append(" ");
 274       if (rpos != 0)
 275       {
 276         // we are marking a positional feature
 277         sb.append(begin);
 278         if (begin != end)
 279         {
 280           sb.append(" ").append(end);
 281         }
 282       }
 283
 284       String description = feature.getDescription();
 285       if (description != null && !description.equals(feature.getType()))
 286       {
 287         description = StringUtils.stripHtmlTags(description);
 288
 289         /*
 290          * truncate overlong descriptions unless they contain an href
 291          * before the truncation point (as truncation could leave corrupted html)
 292          */
 293         int linkindex = description.toLowerCase(Locale.ROOT).indexOf("<a ");
 294         boolean hasLink = linkindex > -1
 295                 && linkindex < MAX_DESCRIPTION_LENGTH;
 296         if (description.length() > MAX_DESCRIPTION_LENGTH && !hasLink)
 297         {
 298           description = description.substring(0, MAX_DESCRIPTION_LENGTH)
 299                   + ELLIPSIS;
 300         }
 301
 302         sb.append("; ").append(description);
 303       }
 304
 305       if (showScore(feature, fr))
 306       {
 307         sb.append(" Score=").append(String.valueOf(feature.getScore()));
 308       }
 309       String status = (String) feature.getValue("status");
 310       if (status != null && status.length() > 0)
 311       {
 312         sb.append("; (").append(status).append(")");
 313       }
 314
 315       /*
 316        * add attribute value if coloured by attribute
 317        */
 318       if (fr != null)
 319       {
 320         FeatureColourI fc = fr.getFeatureColours().get(feature.getType());
 321         if (fc != null && fc.isColourByAttribute())
 322         {
 323           String[] attName = fc.getAttributeName();
 324           String attVal = feature.getValueAsString(attName);
 325           if (attVal != null)
 326           {
 327             sb.append("; ").append(String.join(":", attName)).append("=")
 328                     .append(attVal);
 329           }
 330         }
 331       }
 332
 333       if (mf != null)
 334       {
 335         String variants = mf.findProteinVariants(feature);
 336         if (!variants.isEmpty())
 337         {
 338           sb.append(" ").append(variants);
 339         }
 340       }
 341     }
 342     return appendText(sb0, sb, maxlength);
 343   }
 344
 345   /**
 346    * Appends sb to sb0, and returns false, unless maxlength is not zero and
 347    * appending would make the result longer than or equal to maxlength, in which
 348    * case the append is not done and returns true
 349    *
 350    * @param sb0
 351    * @param sb
 352    * @param maxlength
 353    * @return
 354    */
 355   private static boolean appendText(StringBuilder sb0, StringBuilder sb,
 356           int maxlength)
 357   {
 358     if (maxlength == 0 || sb0.length() + sb.length() < maxlength)
 359     {
 360       sb0.append(sb);
 361       return false;
 362     }
 363     return true;
 364   }
 365
 366   /**
 367    * Answers true if score should be shown, else false. Score is shown if it is
 368    * not NaN, and the feature type has a non-trivial min-max score range
 369    */
 370   boolean showScore(SequenceFeature feature, FeatureRendererModel fr)
 371   {
 372     if (Float.isNaN(feature.getScore()))
 373     {
 374       return false;
 375     }
 376     if (fr == null)
 377     {
 378       return true;
 379     }
 380     float[][] minMax = fr.getMinMax().get(feature.getType());
 381
 382     /*
 383      * minMax[0] is the [min, max] score range for positional features
 384      */
 385     if (minMax == null || minMax[0] == null || minMax[0][0] == minMax[0][1])
 386     {
 387       return false;
 388     }
 389     return true;
 390   }
 391
 392   /**
 393    * Format and appends any hyperlinks for the sequence feature to the string
 394    * buffer
 395    *
 396    * @param sb
 397    * @param feature
 398    */
 399   void appendLinks(final StringBuffer sb, SequenceFeature feature)
 400   {
 401     if (feature.links != null)
 402     {
 403       if (linkImageURL != null)
 404       {
 405         sb.append(" <img src=\"" + linkImageURL + "\">");
 406       }
 407       else
 408       {
 409         for (String urlstring : feature.links)
 410         {
 411           try
 412           {
 413             for (List<String> urllink : createLinksFrom(null, urlstring))
 414             {
 415               sb.append("<br/> <a href=\""
 416                       + urllink.get(3)
 417                       + "\" target=\""
 418                       + urllink.get(0)
 419                       + "\">"
 420                       + (urllink.get(0).toLowerCase(Locale.ROOT)
 421                               .equals(urllink.get(1).toLowerCase(Locale.ROOT)) ? urllink
 422                               .get(0) : (urllink.get(0) + ":" + urllink
 423                                               .get(1)))
 424                       + "</a><br/>");
 425             }
 426           } catch (Exception x)
 427           {
 428             System.err.println("problem when creating links from "
 429                     + urlstring);
 430             x.printStackTrace();
 431           }
 432         }
 433       }
 434
 435     }
 436   }
 437
 438   /**
 439    *
 440    * @param seq
 441    * @param link
 442    * @return Collection< List<String> > { List<String> { link target, link
 443    *         label, dynamic component inserted (if any), url }}
 444    */
 445   Collection<List<String>> createLinksFrom(SequenceI seq, String link)
 446   {
 447     Map<String, List<String>> urlSets = new LinkedHashMap<>();
 448     UrlLink urlLink = new UrlLink(link);
 449     if (!urlLink.isValid())
 450     {
 451       System.err.println(urlLink.getInvalidMessage());
 452       return null;
 453     }
 454
 455     urlLink.createLinksFromSeq(seq, urlSets);
 456
 457     return urlSets.values();
 458   }
 459
 460   public void createSequenceAnnotationReport(final StringBuilder tip,
 461           SequenceI sequence, boolean showDbRefs, boolean showNpFeats,
 462           FeatureRendererModel fr)
 463   {
 464     createSequenceAnnotationReport(tip, sequence, showDbRefs, showNpFeats,
 465             fr, false);
 466   }
 467
 468   /**
 469    * Builds an html formatted report of sequence details and appends it to the
 470    * provided buffer.
 471    *
 472    * @param sb
 473    *          buffer to append report to
 474    * @param sequence
 475    *          the sequence the report is for
 476    * @param showDbRefs
 477    *          whether to include database references for the sequence
 478    * @param showNpFeats
 479    *          whether to include non-positional sequence features
 480    * @param fr
 481    * @param summary
 482    * @return
 483    */
 484   int createSequenceAnnotationReport(final StringBuilder sb,
 485           SequenceI sequence, boolean showDbRefs, boolean showNpFeats,
 486           FeatureRendererModel fr, boolean summary)
 487   {
 488     String tmp;
 489     sb.append("<i>");
 490
 491     int maxWidth = 0;
 492     if (sequence.getDescription() != null)
 493     {
 494       tmp = sequence.getDescription();
 495       sb.append(tmp);
 496       maxWidth = Math.max(maxWidth, tmp.length());
 497     }
 498     SequenceI ds = sequence;
 499     while (ds.getDatasetSequence() != null)
 500     {
 501       ds = ds.getDatasetSequence();
 502     }
 503
 504     if (showDbRefs)
 505     {
 506       maxWidth = Math.max(maxWidth, appendDbRefs(sb, ds, summary));
 507     }
 508
 509     /*
 510      * add non-positional features if wanted
 511      */
 512     if (showNpFeats)
 513     {
 514       for (SequenceFeature sf : sequence.getFeatures()
 515               .getNonPositionalFeatures())
 516       {
 517         int sz = -sb.length();
 518         appendFeature(sb, 0, fr, sf, null, 0);
 519         sz += sb.length();
 520         maxWidth = Math.max(maxWidth, sz);
 521       }
 522     }
 523     sb.append("</i>");
 524     return maxWidth;
 525   }
 526
 527   /**
 528    * A helper method that appends any DBRefs, returning the maximum line length
 529    * added
 530    *
 531    * @param sb
 532    * @param ds
 533    * @param summary
 534    * @return
 535    */
 536   protected int appendDbRefs(final StringBuilder sb, SequenceI ds,
 537           boolean summary)
 538   {
 539     List<DBRefEntry> dbrefs = ds.getDBRefs();
 540     if (dbrefs == null)
 541     {
 542       return 0;
 543     }
 544
 545     // note this sorts the refs held on the sequence!
 546     dbrefs.sort(comparator);
 547     boolean ellipsis = false;
 548     String source = null;
 549     String lastSource = null;
 550     int countForSource = 0;
 551     int sourceCount = 0;
 552     boolean moreSources = false;
 553     int maxLineLength = 0;
 554     int lineLength = 0;
 555
 556     for (DBRefEntry ref : dbrefs)
 557     {
 558       source = ref.getSource();
 559       if (source == null)
 560       {
 561         // shouldn't happen
 562         continue;
 563       }
 564       boolean sourceChanged = !source.equals(lastSource);
 565       if (sourceChanged)
 566       {
 567         lineLength = 0;
 568         countForSource = 0;
 569         sourceCount++;
 570       }
 571       if (sourceCount > MAX_SOURCES && summary)
 572       {
 573         ellipsis = true;
 574         moreSources = true;
 575         break;
 576       }
 577       lastSource = source;
 578       countForSource++;
 579       if (countForSource == 1 || !summary)
 580       {
 581         sb.append("<br/>");
 582       }
 583       if (countForSource <= MAX_REFS_PER_SOURCE || !summary)
 584       {
 585         String accessionId = ref.getAccessionId();
 586         lineLength += accessionId.length() + 1;
 587         if (countForSource > 1 && summary)
 588         {
 589           sb.append(", ").append(accessionId);
 590           lineLength++;
 591         }
 592         else
 593         {
 594           sb.append(source).append(" ").append(accessionId);
 595           lineLength += source.length();
 596         }
 597         maxLineLength = Math.max(maxLineLength, lineLength);
 598       }
 599       if (countForSource == MAX_REFS_PER_SOURCE && summary)
 600       {
 601         sb.append(COMMA).append(ELLIPSIS);
 602         ellipsis = true;
 603       }
 604     }
 605     if (moreSources)
 606     {
 607       sb.append("<br/>").append(source).append(COMMA).append(ELLIPSIS);
 608     }
 609     if (ellipsis)
 610     {
 611       sb.append("<br/>(");
 612       sb.append(MessageManager.getString("label.output_seq_details"));
 613       sb.append(")");
 614     }
 615
 616     return maxLineLength;
 617   }
 618
 619   public void createTooltipAnnotationReport(final StringBuilder tip,
 620           SequenceI sequence, boolean showDbRefs, boolean showNpFeats,
 621           FeatureRendererModel fr)
 622   {
 623     int maxWidth = createSequenceAnnotationReport(tip, sequence,
 624             showDbRefs, showNpFeats, fr, true);
 625
 626     if (maxWidth > 60)
 627     {
 628       // ? not sure this serves any useful purpose
 629       // tip.insert(0, "<table width=350 border=0><tr><td>");
 630       // tip.append("</td></tr></table>");
 631     }
 632   }
 633 }