src/jalview/datamodel/SequenceFeature.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.datamodel;
  22
  23 import jalview.datamodel.features.FeatureLocationI;
  24
  25 import java.util.HashMap;
  26 import java.util.Map;
  27 import java.util.Vector;
  28
  29 /**
  30  * DOCUMENT ME!
  31  *
  32  * @author $author$
  33  * @version $Revision$
  34  */
  35 public class SequenceFeature implements FeatureLocationI
  36 {
  37   private static final String STATUS = "status";
  38
  39   private static final String STRAND = "STRAND";
  40
  41   // private key for Phase designed not to conflict with real GFF data
  42   private static final String PHASE = "!Phase";
  43
  44   // private key for ENA location designed not to conflict with real GFF data
  45   private static final String LOCATION = "!Location";
  46
  47   /*
  48    * ATTRIBUTES is reserved for the GFF 'column 9' data, formatted as
  49    * name1=value1;name2=value2,value3;...etc
  50    */
  51   private static final String ATTRIBUTES = "ATTRIBUTES";
  52
  53   public int begin;
  54
  55   public int end;
  56
  57   public float score;
  58
  59   public String type;
  60
  61   public String description;
  62
  63   /*
  64    * a map of key-value pairs; may be populated from GFF 'column 9' data,
  65    * other data sources (e.g. GenBank file), or programmatically
  66    */
  67   public Map<String, Object> otherDetails;
  68
  69   public Vector<String> links;
  70
  71   // Feature group can be set from a features file
  72   // as a group of features between STARTGROUP and ENDGROUP markers
  73   public String featureGroup;
  74
  75   public SequenceFeature()
  76   {
  77   }
  78
  79   /**
  80    * Constructs a duplicate feature. Note: Uses makes a shallow copy of the
  81    * otherDetails map, so the new and original SequenceFeature may reference the
  82    * same objects in the map.
  83    *
  84    * @param cpy
  85    */
  86   public SequenceFeature(SequenceFeature cpy)
  87   {
  88     if (cpy != null)
  89     {
  90       begin = cpy.begin;
  91       end = cpy.end;
  92       score = cpy.score;
  93       if (cpy.type != null)
  94       {
  95         type = new String(cpy.type);
  96       }
  97       if (cpy.description != null)
  98       {
  99         description = new String(cpy.description);
 100       }
 101       if (cpy.featureGroup != null)
 102       {
 103         featureGroup = new String(cpy.featureGroup);
 104       }
 105       if (cpy.otherDetails != null)
 106       {
 107         try
 108         {
 109           otherDetails = (Map<String, Object>) ((HashMap<String, Object>) cpy.otherDetails)
 110                   .clone();
 111         } catch (Exception e)
 112         {
 113           // ignore
 114         }
 115       }
 116       if (cpy.links != null && cpy.links.size() > 0)
 117       {
 118         links = new Vector<String>();
 119         for (int i = 0, iSize = cpy.links.size(); i < iSize; i++)
 120         {
 121           links.addElement(cpy.links.elementAt(i));
 122         }
 123       }
 124     }
 125   }
 126
 127   /**
 128    * Constructor including a Status value
 129    *
 130    * @param type
 131    * @param desc
 132    * @param status
 133    * @param begin
 134    * @param end
 135    * @param featureGroup
 136    */
 137   public SequenceFeature(String type, String desc, String status,
 138           int begin, int end, String featureGroup)
 139   {
 140     this(type, desc, begin, end, featureGroup);
 141     setStatus(status);
 142   }
 143
 144   /**
 145    * Constructor
 146    *
 147    * @param type
 148    * @param desc
 149    * @param begin
 150    * @param end
 151    * @param featureGroup
 152    */
 153   SequenceFeature(String type, String desc, int begin, int end,
 154           String featureGroup)
 155   {
 156     this.type = type;
 157     this.description = desc;
 158     this.begin = begin;
 159     this.end = end;
 160     this.featureGroup = featureGroup;
 161   }
 162
 163   /**
 164    * Constructor including a score value
 165    *
 166    * @param type
 167    * @param desc
 168    * @param begin
 169    * @param end
 170    * @param score
 171    * @param featureGroup
 172    */
 173   public SequenceFeature(String type, String desc, int begin, int end,
 174           float score, String featureGroup)
 175   {
 176     this(type, desc, begin, end, featureGroup);
 177     this.score = score;
 178   }
 179
 180   /**
 181    * Two features are considered equal if they have the same type, group,
 182    * description, start, end, phase, strand, and (if present) 'Name', ID' and
 183    * 'Parent' attributes.
 184    *
 185    * Note we need to check Parent to distinguish the same exon occurring in
 186    * different transcripts (in Ensembl GFF). This allows assembly of transcript
 187    * sequences from their component exon regions.
 188    */
 189   @Override
 190   public boolean equals(Object o)
 191   {
 192     return equals(o, false);
 193   }
 194
 195   /**
 196    * Overloaded method allows the equality test to optionally ignore the
 197    * 'Parent' attribute of a feature. This supports avoiding adding many
 198    * superficially duplicate 'exon' or CDS features to genomic or protein
 199    * sequence.
 200    *
 201    * @param o
 202    * @param ignoreParent
 203    * @return
 204    */
 205   public boolean equals(Object o, boolean ignoreParent)
 206   {
 207     if (o == null || !(o instanceof SequenceFeature))
 208     {
 209       return false;
 210     }
 211
 212     SequenceFeature sf = (SequenceFeature) o;
 213     boolean sameScore = Float.isNaN(score) ? Float.isNaN(sf.score)
 214             : score == sf.score;
 215     if (begin != sf.begin || end != sf.end || !sameScore)
 216     {
 217       return false;
 218     }
 219
 220     if (getStrand() != sf.getStrand())
 221     {
 222       return false;
 223     }
 224
 225     if (!(type + description + featureGroup + getPhase()).equals(sf.type
 226             + sf.description + sf.featureGroup + sf.getPhase()))
 227     {
 228       return false;
 229     }
 230     if (!equalAttribute(getValue("ID"), sf.getValue("ID")))
 231     {
 232       return false;
 233     }
 234     if (!equalAttribute(getValue("Name"), sf.getValue("Name")))
 235     {
 236       return false;
 237     }
 238     if (!ignoreParent)
 239     {
 240       if (!equalAttribute(getValue("Parent"), sf.getValue("Parent")))
 241       {
 242         return false;
 243       }
 244     }
 245     return true;
 246   }
 247
 248   /**
 249    * Returns true if both values are null, are both non-null and equal
 250    *
 251    * @param att1
 252    * @param att2
 253    * @return
 254    */
 255   protected static boolean equalAttribute(Object att1, Object att2)
 256   {
 257     if (att1 == null && att2 == null)
 258     {
 259       return true;
 260     }
 261     if (att1 != null)
 262     {
 263       return att1.equals(att2);
 264     }
 265     return att2.equals(att1);
 266   }
 267
 268   /**
 269    * DOCUMENT ME!
 270    *
 271    * @return DOCUMENT ME!
 272    */
 273   @Override
 274   public int getBegin()
 275   {
 276     return begin;
 277   }
 278
 279   public void setBegin(int start)
 280   {
 281     this.begin = start;
 282   }
 283
 284   /**
 285    * DOCUMENT ME!
 286    *
 287    * @return DOCUMENT ME!
 288    */
 289   @Override
 290   public int getEnd()
 291   {
 292     return end;
 293   }
 294
 295   public void setEnd(int end)
 296   {
 297     this.end = end;
 298   }
 299
 300   /**
 301    * DOCUMENT ME!
 302    *
 303    * @return DOCUMENT ME!
 304    */
 305   public String getType()
 306   {
 307     return type;
 308   }
 309
 310   public void setType(String type)
 311   {
 312     this.type = type;
 313   }
 314
 315   /**
 316    * DOCUMENT ME!
 317    *
 318    * @return DOCUMENT ME!
 319    */
 320   public String getDescription()
 321   {
 322     return description;
 323   }
 324
 325   public void setDescription(String desc)
 326   {
 327     description = desc;
 328   }
 329
 330   public String getFeatureGroup()
 331   {
 332     return featureGroup;
 333   }
 334
 335   public void setFeatureGroup(String featureGroup)
 336   {
 337     this.featureGroup = featureGroup;
 338   }
 339
 340   public void addLink(String labelLink)
 341   {
 342     if (links == null)
 343     {
 344       links = new Vector<String>();
 345     }
 346
 347     links.insertElementAt(labelLink, 0);
 348   }
 349
 350   public float getScore()
 351   {
 352     return score;
 353   }
 354
 355   public void setScore(float value)
 356   {
 357     score = value;
 358   }
 359
 360   /**
 361    * Used for getting values which are not in the basic set. eg STRAND, PHASE
 362    * for GFF file
 363    *
 364    * @param key
 365    *          String
 366    */
 367   public Object getValue(String key)
 368   {
 369     if (otherDetails == null)
 370     {
 371       return null;
 372     }
 373     else
 374     {
 375       return otherDetails.get(key);
 376     }
 377   }
 378
 379   /**
 380    * Returns a property value for the given key if known, else the specified
 381    * default value
 382    *
 383    * @param key
 384    * @param defaultValue
 385    * @return
 386    */
 387   public Object getValue(String key, Object defaultValue)
 388   {
 389     Object value = getValue(key);
 390     return value == null ? defaultValue : value;
 391   }
 392
 393   /**
 394    * Used for setting values which are not in the basic set. eg STRAND, FRAME
 395    * for GFF file
 396    *
 397    * @param key
 398    *          eg STRAND
 399    * @param value
 400    *          eg +
 401    */
 402   public void setValue(String key, Object value)
 403   {
 404     if (value != null)
 405     {
 406       if (otherDetails == null)
 407       {
 408         otherDetails = new HashMap<String, Object>();
 409       }
 410
 411       otherDetails.put(key, value);
 412     }
 413   }
 414
 415   /*
 416    * The following methods are added to maintain the castor Uniprot mapping file
 417    * for the moment.
 418    */
 419   public void setStatus(String status)
 420   {
 421     setValue(STATUS, status);
 422   }
 423
 424   public String getStatus()
 425   {
 426     return (String) getValue(STATUS);
 427   }
 428
 429   public void setAttributes(String attr)
 430   {
 431     setValue(ATTRIBUTES, attr);
 432   }
 433
 434   public String getAttributes()
 435   {
 436     return (String) getValue(ATTRIBUTES);
 437   }
 438
 439   public void setPosition(int pos)
 440   {
 441     begin = pos;
 442     end = pos;
 443   }
 444
 445   public int getPosition()
 446   {
 447     return begin;
 448   }
 449
 450   /**
 451    * Return 1 for forward strand ('+' in GFF), -1 for reverse strand ('-' in
 452    * GFF), and 0 for unknown or not (validly) specified
 453    *
 454    * @return
 455    */
 456   public int getStrand()
 457   {
 458     int strand = 0;
 459     if (otherDetails != null)
 460     {
 461       Object str = otherDetails.get(STRAND);
 462       if ("-".equals(str))
 463       {
 464         strand = -1;
 465       }
 466       else if ("+".equals(str))
 467       {
 468         strand = 1;
 469       }
 470     }
 471     return strand;
 472   }
 473
 474   /**
 475    * Set the value of strand
 476    *
 477    * @param strand
 478    *          should be "+" for forward, or "-" for reverse
 479    */
 480   public void setStrand(String strand)
 481   {
 482     setValue(STRAND, strand);
 483   }
 484
 485   public void setPhase(String phase)
 486   {
 487     setValue(PHASE, phase);
 488   }
 489
 490   public String getPhase()
 491   {
 492     return (String) getValue(PHASE);
 493   }
 494
 495   /**
 496    * Sets the 'raw' ENA format location specifier e.g. join(12..45,89..121)
 497    *
 498    * @param loc
 499    */
 500   public void setEnaLocation(String loc)
 501   {
 502     setValue(LOCATION, loc);
 503   }
 504
 505   /**
 506    * Gets the 'raw' ENA format location specifier e.g. join(12..45,89..121)
 507    *
 508    * @param loc
 509    */
 510   public String getEnaLocation()
 511   {
 512     return (String) getValue(LOCATION);
 513   }
 514
 515   /**
 516    * Readable representation, for debug only, not guaranteed not to change
 517    * between versions
 518    */
 519   @Override
 520   public String toString()
 521   {
 522     return String.format("%d %d %s %s", getBegin(), getEnd(), getType(),
 523             getDescription());
 524   }
 525
 526   /**
 527    * Overridden to ensure that whenever two objects are equal, they have the
 528    * same hashCode
 529    */
 530   @Override
 531   public int hashCode()
 532   {
 533     String s = getType() + getDescription() + getFeatureGroup()
 534             + getValue("ID") + getValue("Name") + getValue("Parent")
 535             + getPhase();
 536     return s.hashCode() + getBegin() + getEnd() + (int) getScore()
 537             + getStrand();
 538   }
 539
 540   /**
 541    * Answers true if the feature's start/end values represent two related
 542    * positions, rather than ends of a range. Such features may be visualised or
 543    * reported differently to features on a range.
 544    */
 545   @Override
 546   public boolean isContactFeature()
 547   {
 548     // TODO abstract one day to a FeatureType class
 549     if ("disulfide bond".equalsIgnoreCase(type)
 550             || "disulphide bond".equalsIgnoreCase(type))
 551     {
 552       return true;
 553     }
 554     return false;
 555   }
 556 }