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