src/jalview/datamodel/xdb/embl/EmblEntry.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.4)
   3  * Copyright (C) 2008 AM Waterhouse, J Procter, G Barton, M Clamp, S Searle
   4  *
   5  * This program is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU General Public License
   7  * as published by the Free Software Foundation; either version 2
   8  * of the License, or (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
  18  */
  19 package jalview.datamodel.xdb.embl;
  20
  21 import jalview.datamodel.DBRefEntry;
  22 import jalview.datamodel.DBRefSource;
  23 import jalview.datamodel.FeatureProperties;
  24 import jalview.datamodel.Mapping;
  25 import jalview.datamodel.Sequence;
  26 import jalview.datamodel.SequenceFeature;
  27 import jalview.datamodel.SequenceI;
  28
  29 import java.util.Enumeration;
  30 import java.util.Hashtable;
  31 import java.util.Iterator;
  32 import java.util.Vector;
  33
  34 public class EmblEntry
  35 {
  36   String accession;
  37
  38   String version;
  39
  40   String taxDivision;
  41
  42   String desc;
  43
  44   String rCreated;
  45
  46   String rLastUpdated;
  47
  48   String lastUpdated;
  49
  50   Vector keywords;
  51
  52   Vector refs;
  53
  54   Vector dbRefs;
  55
  56   Vector features;
  57
  58   EmblSequence sequence;
  59
  60   /**
  61    * @return the accession
  62    */
  63   public String getAccession()
  64   {
  65     return accession;
  66   }
  67
  68   /**
  69    * @param accession
  70    *          the accession to set
  71    */
  72   public void setAccession(String accession)
  73   {
  74     this.accession = accession;
  75   }
  76
  77   /**
  78    * @return the dbRefs
  79    */
  80   public Vector getDbRefs()
  81   {
  82     return dbRefs;
  83   }
  84
  85   /**
  86    * @param dbRefs
  87    *          the dbRefs to set
  88    */
  89   public void setDbRefs(Vector dbRefs)
  90   {
  91     this.dbRefs = dbRefs;
  92   }
  93
  94   /**
  95    * @return the desc
  96    */
  97   public String getDesc()
  98   {
  99     return desc;
 100   }
 101
 102   /**
 103    * @param desc
 104    *          the desc to set
 105    */
 106   public void setDesc(String desc)
 107   {
 108     this.desc = desc;
 109   }
 110
 111   /**
 112    * @return the features
 113    */
 114   public Vector getFeatures()
 115   {
 116     return features;
 117   }
 118
 119   /**
 120    * @param features
 121    *          the features to set
 122    */
 123   public void setFeatures(Vector features)
 124   {
 125     this.features = features;
 126   }
 127
 128   /**
 129    * @return the keywords
 130    */
 131   public Vector getKeywords()
 132   {
 133     return keywords;
 134   }
 135
 136   /**
 137    * @param keywords
 138    *          the keywords to set
 139    */
 140   public void setKeywords(Vector keywords)
 141   {
 142     this.keywords = keywords;
 143   }
 144
 145   /**
 146    * @return the lastUpdated
 147    */
 148   public String getLastUpdated()
 149   {
 150     return lastUpdated;
 151   }
 152
 153   /**
 154    * @param lastUpdated
 155    *          the lastUpdated to set
 156    */
 157   public void setLastUpdated(String lastUpdated)
 158   {
 159     this.lastUpdated = lastUpdated;
 160   }
 161
 162   /**
 163    * @return the refs
 164    */
 165   public Vector getRefs()
 166   {
 167     return refs;
 168   }
 169
 170   /**
 171    * @param refs
 172    *          the refs to set
 173    */
 174   public void setRefs(Vector refs)
 175   {
 176     this.refs = refs;
 177   }
 178
 179   /**
 180    * @return the releaseCreated
 181    */
 182   public String getRCreated()
 183   {
 184     return rCreated;
 185   }
 186
 187   /**
 188    * @param releaseCreated
 189    *          the releaseCreated to set
 190    */
 191   public void setRcreated(String releaseCreated)
 192   {
 193     this.rCreated = releaseCreated;
 194   }
 195
 196   /**
 197    * @return the releaseLastUpdated
 198    */
 199   public String getRLastUpdated()
 200   {
 201     return rLastUpdated;
 202   }
 203
 204   /**
 205    * @param releaseLastUpdated
 206    *          the releaseLastUpdated to set
 207    */
 208   public void setRLastUpdated(String releaseLastUpdated)
 209   {
 210     this.rLastUpdated = releaseLastUpdated;
 211   }
 212
 213   /**
 214    * @return the sequence
 215    */
 216   public EmblSequence getSequence()
 217   {
 218     return sequence;
 219   }
 220
 221   /**
 222    * @param sequence
 223    *          the sequence to set
 224    */
 225   public void setSequence(EmblSequence sequence)
 226   {
 227     this.sequence = sequence;
 228   }
 229
 230   /**
 231    * @return the taxDivision
 232    */
 233   public String getTaxDivision()
 234   {
 235     return taxDivision;
 236   }
 237
 238   /**
 239    * @param taxDivision
 240    *          the taxDivision to set
 241    */
 242   public void setTaxDivision(String taxDivision)
 243   {
 244     this.taxDivision = taxDivision;
 245   }
 246
 247   /**
 248    * @return the version
 249    */
 250   public String getVersion()
 251   {
 252     return version;
 253   }
 254
 255   /**
 256    * @param version
 257    *          the version to set
 258    */
 259   public void setVersion(String version)
 260   {
 261     this.version = version;
 262   }
 263
 264   /*
 265    * EMBL Feature support is limited. The text below is included for the benefit
 266    * of any developer working on improving EMBL feature import in Jalview.
 267    * Extract from EMBL feature specification see
 268    * http://www.embl-ebi.ac.uk/embl/Documentation/FT_definitions/feature_table.html
 269    * 3.5 Location 3.5.1 Purpose
 270    *
 271    * The location indicates the region of the presented sequence which
 272    * corresponds to a feature.
 273    *
 274    * 3.5.2 Format and conventions The location contains at least one sequence
 275    * location descriptor and may contain one or more operators with one or more
 276    * sequence location descriptors. Base numbers refer to the numbering in the
 277    * entry. This numbering designates the first base (5' end) of the presented
 278    * sequence as base 1. Base locations beyond the range of the presented
 279    * sequence may not be used in location descriptors, the only exception being
 280    * location in a remote entry (see 3.5.2.1, e).
 281    *
 282    * Location operators and descriptors are discussed in more detail below.
 283    *
 284    * 3.5.2.1 Location descriptors
 285    *
 286    * The location descriptor can be one of the following: (a) a single base
 287    * number (b) a site between two indicated adjoining bases (c) a single base
 288    * chosen from within a specified range of bases (not allowed for new entries)
 289    * (d) the base numbers delimiting a sequence span (e) a remote entry
 290    * identifier followed by a local location descriptor (i.e., a-d)
 291    *
 292    * A site between two adjoining nucleotides, such as endonucleolytic cleavage
 293    * site, is indicated by listing the two points separated by a carat (^). The
 294    * permitted formats for this descriptor are n^n+1 (for example 55^56), or,
 295    * for circular molecules, n^1, where "n" is the full length of the molecule,
 296    * ie 1000^1 for circular molecule with length 1000.
 297    *
 298    * A single base chosen from a range of bases is indicated by the first base
 299    * number and the last base number of the range separated by a single period
 300    * (e.g., '12.21' indicates a single base taken from between the indicated
 301    * points). From October 2006 the usage of this descriptor is restricted : it
 302    * is illegal to use "a single base from a range" (c) either on its own or in
 303    * combination with the "sequence span" (d) descriptor for newly created
 304    * entries. The existing entries where such descriptors exist are going to be
 305    * retrofitted.
 306    *
 307    * Sequence spans are indicated by the starting base number and the ending
 308    * base number separated by two periods (e.g., '34..456'). The '<' and '>'
 309    * symbols may be used with the starting and ending base numbers to indicate
 310    * that an end point is beyond the specified base number. The starting and
 311    * ending base positions can be represented as distinct base numbers
 312    * ('34..456') or a site between two indicated adjoining bases.
 313    *
 314    * A location in a remote entry (not the entry to which the feature table
 315    * belongs) can be specified by giving the accession-number and sequence
 316    * version of the remote entry, followed by a colon ":", followed by a
 317    * location descriptor which applies to that entry's sequence (i.e.
 318    * J12345.1:1..15, see also examples below)
 319    *
 320    * 3.5.2.2 Operators
 321    *
 322    * The location operator is a prefix that specifies what must be done to the
 323    * indicated sequence to find or construct the location corresponding to the
 324    * feature. A list of operators is given below with their definitions and most
 325    * common format.
 326    *
 327    * complement(location) Find the complement of the presented sequence in the
 328    * span specified by " location" (i.e., read the complement of the presented
 329    * strand in its 5'-to-3' direction)
 330    *
 331    * join(location,location, ... location) The indicated elements should be
 332    * joined (placed end-to-end) to form one contiguous sequence
 333    *
 334    * order(location,location, ... location) The elements can be found in the
 335    * specified order (5' to 3' direction), but nothing is implied about the
 336    * reasonableness about joining them
 337    *
 338    * Note : location operator "complement" can be used in combination with
 339    * either " join" or "order" within the same location; combinations of "join"
 340    * and "order" within the same location (nested operators) are illegal.
 341    *
 342    *
 343    *
 344    * 3.5.3 Location examples
 345    *
 346    * The following is a list of common location descriptors with their meanings:
 347    *
 348    * Location Description
 349    *
 350    * 467 Points to a single base in the presented sequence
 351    *
 352    * 340..565 Points to a continuous range of bases bounded by and including the
 353    * starting and ending bases
 354    *
 355    * <345..500 Indicates that the exact lower boundary point of a feature is
 356    * unknown. The location begins at some base previous to the first base
 357    * specified (which need not be contained in the presented sequence) and
 358    * continues to and includes the ending base
 359    *
 360    * <1..888 The feature starts before the first sequenced base and continues to
 361    * and includes base 888
 362    *
 363    * 1..>888 The feature starts at the first sequenced base and continues beyond
 364    * base 888
 365    *
 366    * 102.110 Indicates that the exact location is unknown but that it is one of
 367    * the bases between bases 102 and 110, inclusive
 368    *
 369    * 123^124 Points to a site between bases 123 and 124
 370    *
 371    * join(12..78,134..202) Regions 12 to 78 and 134 to 202 should be joined to
 372    * form one contiguous sequence
 373    *
 374    *
 375    * complement(34..126) Start at the base complementary to 126 and finish at
 376    * the base complementary to base 34 (the feature is on the strand
 377    * complementary to the presented strand)
 378    *
 379    *
 380    * complement(join(2691..4571,4918..5163)) Joins regions 2691 to 4571 and 4918
 381    * to 5163, then complements the joined segments (the feature is on the strand
 382    * complementary to the presented strand)
 383    *
 384    * join(complement(4918..5163),complement(2691..4571)) Complements regions
 385    * 4918 to 5163 and 2691 to 4571, then joins the complemented segments (the
 386    * feature is on the strand complementary to the presented strand)
 387    *
 388    * J00194.1:100..202 Points to bases 100 to 202, inclusive, in the entry (in
 389    * this database) with primary accession number 'J00194'
 390    *
 391    * join(1..100,J00194.1:100..202) Joins region 1..100 of the existing entry
 392    * with the region 100..202 of remote entry J00194
 393    *
 394    */
 395   /**
 396    * Recover annotated sequences from EMBL file
 397    *
 398    * @param noNa
 399    *          don't return nucleic acid sequences
 400    * @param sourceDb
 401    *          TODO
 402    * @param noProtein
 403    *          don't return any translated protein sequences marked in features
 404    * @return dataset sequences with DBRefs and features - DNA always comes first
 405    */
 406   public jalview.datamodel.SequenceI[] getSequences(boolean noNa,
 407           boolean noPeptide, String sourceDb)
 408   { //TODO: ensure emblEntry.getSequences behaves correctly for returning all cases of noNa and noPeptide
 409     Vector seqs = new Vector();
 410     Sequence dna = null;
 411     if (!noNa)
 412     {
 413       // In theory we still need to create this if noNa is set to avoid a null pointer exception
 414       dna = new Sequence(sourceDb + "|" + accession, sequence.getSequence());
 415       dna.setDescription(desc);
 416       dna.addDBRef(new DBRefEntry(sourceDb, version, accession));
 417       // TODO: add mapping for parentAccession attribute
 418       // TODO: transform EMBL Database refs to canonical form
 419       if (dbRefs != null)
 420         for (Iterator i = dbRefs.iterator(); i.hasNext(); dna
 421         .addDBRef((DBRefEntry) i.next()))
 422         ;
 423     }
 424     try
 425     {
 426       for (Iterator i = features.iterator(); i.hasNext();)
 427       {
 428         EmblFeature feature = (EmblFeature) i.next();
 429         if (!noNa)
 430         {
 431           if (feature.dbRefs != null && feature.dbRefs.size() > 0)
 432           {
 433             for (Iterator dbr = feature.dbRefs.iterator(); dbr.hasNext(); dna
 434                     .addDBRef((DBRefEntry) dbr.next()))
 435               ;
 436           }
 437         }
 438         if (FeatureProperties.isCodingFeature(sourceDb, feature.getName()))
 439         {
 440           parseCodingFeature(feature, sourceDb, seqs, dna, noPeptide);
 441         }
 442         else
 443         {
 444           // General feature type.
 445           if (!noNa)
 446           {
 447             if (feature.dbRefs != null && feature.dbRefs.size() > 0)
 448             {
 449               for (Iterator dbr = feature.dbRefs.iterator(); dbr.hasNext(); dna
 450                       .addDBRef((DBRefEntry) dbr.next()))
 451                 ;
 452             }
 453           }
 454         }
 455       }
 456     }
 457     catch (Exception e)
 458     {
 459       System.err.println("EMBL Record Features parsing error!");
 460       System.err
 461               .println("Please report the following to help@jalview.org :");
 462       System.err.println("EMBL Record " + accession);
 463       System.err.println("Resulted in exception: " + e.getMessage());
 464       e.printStackTrace(System.err);
 465     }
 466     if (!noNa && dna != null)
 467     {
 468       seqs.add(dna);
 469     }
 470     SequenceI[] sqs = new SequenceI[seqs.size()];
 471     for (int i = 0, j = seqs.size(); i < j; i++)
 472     {
 473       sqs[i] = (SequenceI) seqs.elementAt(i);
 474       seqs.set(i, null);
 475     }
 476     return sqs;
 477   }
 478
 479   /**
 480    * attempt to extract coding region and product from a feature and properly decorate it with annotations.
 481    * @param feature coding feature
 482    * @param sourceDb source database for the EMBLXML
 483    * @param seqs place where sequences go
 484    * @param dna parent dna sequence for this record
 485    * @param noPeptide flag for generation of Peptide sequence objects
 486    */
 487   private void parseCodingFeature(EmblFeature feature, String sourceDb, Vector seqs, Sequence dna, boolean noPeptide)
 488   {
 489     boolean isEmblCdna = sourceDb.equals(DBRefSource.EMBLCDS);
 490     // extract coding region(s)
 491     jalview.datamodel.Mapping map = null;
 492     int[] exon = null;
 493     if (feature.locations != null && feature.locations.size() > 0)
 494     {
 495       for (Enumeration locs = feature.locations.elements(); locs
 496               .hasMoreElements();)
 497       {
 498         EmblFeatureLocations loc = (EmblFeatureLocations) locs
 499                 .nextElement();
 500         int[] se = loc.getElementRanges(accession);
 501         if (exon == null)
 502         {
 503           exon = se;
 504         }
 505         else
 506         {
 507           int[] t = new int[exon.length + se.length];
 508           System.arraycopy(exon, 0, t, 0, exon.length);
 509           System.arraycopy(se, 0, t, exon.length, se.length);
 510           exon = t;
 511         }
 512       }
 513     }
 514     String prseq = null;
 515     String prname = new String();
 516     String prid = null;
 517     Hashtable vals = new Hashtable();
 518     int prstart = 1;
 519     // get qualifiers
 520     if (feature.getQualifiers() != null
 521             && feature.getQualifiers().size() > 0)
 522     {
 523       for (Iterator quals = feature.getQualifiers().iterator(); quals
 524               .hasNext();)
 525       {
 526         Qualifier q = (Qualifier) quals.next();
 527         if (q.getName().equals("translation"))
 528         {
 529           StringBuffer prsq = new StringBuffer(q.getValues()[0]);
 530           int p = prsq.indexOf(" ");
 531           while (p > -1)
 532           {
 533             prsq.deleteCharAt(p);
 534             p = prsq.indexOf(" ", p);
 535           }
 536           prseq = prsq.toString();
 537           prsq = null;
 538
 539         }
 540         else if (q.getName().equals("protein_id"))
 541         {
 542           prid = q.getValues()[0];
 543         }
 544         else if (q.getName().equals("codon_start"))
 545         {
 546           prstart = Integer.parseInt(q.getValues()[0]);
 547         }
 548         else if (q.getName().equals("product"))
 549         {
 550           prname = q.getValues()[0];
 551         }
 552         else
 553         {
 554           // throw anything else into the additional properties hash
 555           String[] s= q.getValues();
 556           StringBuffer sb = new StringBuffer();
 557           if (s!=null)
 558           {
 559             for (int i=0; i<s.length; i++)
 560             {
 561               sb.append(s[i]);
 562               sb.append("\n");
 563             }
 564           }
 565           vals.put(q.getName(), sb.toString());
 566         }
 567       }
 568     }
 569     Sequence product = null;
 570     if (prseq != null && prname != null && prid != null)
 571     {
 572       // extract proteins.
 573       product = new Sequence(prid
 574               , prseq, prstart, prstart
 575               + prseq.length() - 1);
 576       product.setDescription(((prname.length()==0) ? "Protein Product from " + sourceDb : prname));
 577
 578       if (!noPeptide)
 579       {
 580         // Protein is also added to vector of sequences returned
 581         seqs.add(product);
 582       }
 583       // we have everything - create the mapping and perhaps the protein
 584       // sequence
 585       if (exon == null || exon.length == 0)
 586       {
 587         System.err
 588                 .println("Implementation Notice: EMBLCDS records not properly supported yet - Making up the CDNA region of this sequence... may be incorrect ("
 589                         + sourceDb + ":" + getAccession() + ")");
 590         if (prseq.length() * 3 == dna.getSequence().length)
 591         {
 592           // this might occur for CDS sequences where no features are
 593           // marked.
 594           exon = new int[]
 595           { dna.getStart(), dna.getEnd() };
 596           map = new jalview.datamodel.Mapping(product, exon,
 597                   new int[]
 598                   { prstart, prstart + prseq.length() - 1 }, 3, 1);
 599         }
 600         if ((prseq.length() + 1) * 3 == dna.getSequence().length)
 601         {
 602           exon = new int[]
 603           { dna.getStart(), dna.getEnd() - 3 };
 604           map = new jalview.datamodel.Mapping(product, exon,
 605                   new int[]
 606                   { prstart, prstart + prseq.length() - 1 }, 3, 1);
 607         }
 608       }
 609       else
 610       {
 611         if (isEmblCdna)
 612         {
 613           // TODO: Add a DbRef back to the parent EMBL sequence with the exon
 614           // map
 615           // if given a dataset reference, search dataset for parent EMBL sequence if it exists and set its map
 616           // make a new feature annotating the coding contig
 617         }
 618         else
 619         {
 620           map = new jalview.datamodel.Mapping(product, exon,
 621                   new int[]
 622                   { prstart, prstart + prseq.length() - 1 }, 3, 1);
 623           // reconstruct the EMBLCDS entry
 624           DBRefEntry pcdnaref = new DBRefEntry();
 625           pcdnaref.setAccessionId(prid);
 626           pcdnaref.setSource(DBRefSource.EMBLCDS);
 627           pcdnaref.setVersion(getVersion()); // same as parent EMBL version.
 628           jalview.util.MapList mp = new jalview.util.MapList(new int[]
 629           { 1+(prstart-1)*3, 1+(prstart-1)*3 + (prseq.length()-1)*3 }, new int[] { prstart, prstart+prseq.length() - 1 }, 3, 1);
 630           pcdnaref.setMap(new Mapping(mp));
 631           if (product!=null)
 632             product.addDBRef(pcdnaref);
 633
 634         }
 635       }
 636       // add cds feature to dna seq - this may include the stop codon
 637       for (int xint = 0; exon != null && xint < exon.length; xint += 2)
 638       {
 639         SequenceFeature sf = new SequenceFeature();
 640         sf.setBegin(exon[xint]);
 641         sf.setEnd(exon[xint + 1]);
 642         sf.setType(feature.getName());
 643         sf.setFeatureGroup(sourceDb);
 644         sf.setDescription("Exon " + (1 + (int)(xint/2)) + " for protein '"
 645                 + prname + "' EMBLCDS:" + prid);
 646         sf.setValue(FeatureProperties.EXONPOS, new Integer(1 + xint));
 647         sf.setValue(FeatureProperties.EXONPRODUCT, prname);
 648         if (vals != null && vals.size() > 0)
 649         {
 650           Enumeration kv = vals.elements();
 651           while (kv.hasMoreElements())
 652           {
 653             Object key = kv.nextElement();
 654             if (key != null)
 655               sf.setValue(key.toString(), vals.get(key));
 656           }
 657         }
 658         dna.addSequenceFeature(sf);
 659       }
 660     }
 661     // add dbRefs to sequence
 662     if (feature.dbRefs != null && feature.dbRefs.size() > 0)
 663     {
 664       for (Iterator dbr = feature.dbRefs.iterator(); dbr.hasNext();)
 665       {
 666         DBRefEntry ref = (DBRefEntry) dbr.next();
 667         ref.setSource(jalview.util.DBRefUtils.getCanonicalName(ref
 668                 .getSource()));
 669         // Hard code the kind of protein product accessions that EMBL cite
 670         if (ref.getSource().equals(
 671                 jalview.datamodel.DBRefSource.UNIPROT))
 672         {
 673           ref.setMap(map);
 674           if (map!=null && map.getTo()!=null)
 675           {
 676             map.getTo().addDBRef(new DBRefEntry(ref.getSource(), ref.getVersion(), ref.getAccessionId())); // don't copy map over.
 677             if (map.getTo().getName().indexOf(prid)==0)
 678             {
 679               map.getTo().setName(jalview.datamodel.DBRefSource.UNIPROT+"|"+ref.getAccessionId());
 680             }
 681           }
 682         }
 683         if (product != null)
 684         {
 685           DBRefEntry pref = new DBRefEntry(ref.getSource(), ref
 686                 .getVersion(), ref.getAccessionId());
 687           pref.setMap(null); // reference is direct
 688           product.addDBRef(pref);
 689           // Add converse mapping reference
 690           if (map != null)
 691           {
 692             Mapping pmap = new Mapping(dna, map.getMap().getInverse());
 693             pref = new DBRefEntry(sourceDb, getVersion(), this
 694                     .getAccession());
 695             pref.setMap(pmap);
 696             if (map.getTo()!=null)
 697             {
 698               map.getTo().addDBRef(pref);
 699             }
 700           }
 701         }
 702         dna.addDBRef(ref);
 703       }
 704     }
 705   }
 706 }