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

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer (Development Version 2.4.1)
   3  * Copyright (C) 2009 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
 404    *                features
 405    * @return dataset sequences with DBRefs and features - DNA always comes first
 406    */
 407   public jalview.datamodel.SequenceI[] getSequences(boolean noNa,
 408           boolean noPeptide, String sourceDb)
 409   { // TODO: ensure emblEntry.getSequences behaves correctly for returning all
 410     // cases of noNa and noPeptide
 411     Vector seqs = new Vector();
 412     Sequence dna = null;
 413     if (!noNa)
 414     {
 415       // In theory we still need to create this if noNa is set to avoid a null
 416       // pointer exception
 417       dna = new Sequence(sourceDb + "|" + accession, sequence.getSequence());
 418       dna.setDescription(desc);
 419       dna.addDBRef(new DBRefEntry(sourceDb, version, accession));
 420       // TODO: add mapping for parentAccession attribute
 421       // TODO: transform EMBL Database refs to canonical form
 422       if (dbRefs != null)
 423         for (Iterator i = dbRefs.iterator(); i.hasNext(); dna
 424                 .addDBRef((DBRefEntry) i.next()))
 425           ;
 426     }
 427     try
 428     {
 429       for (Iterator i = features.iterator(); i.hasNext();)
 430       {
 431         EmblFeature feature = (EmblFeature) i.next();
 432         if (!noNa)
 433         {
 434           if (feature.dbRefs != null && feature.dbRefs.size() > 0)
 435           {
 436             for (Iterator dbr = feature.dbRefs.iterator(); dbr.hasNext(); dna
 437                     .addDBRef((DBRefEntry) dbr.next()))
 438               ;
 439           }
 440         }
 441         if (FeatureProperties.isCodingFeature(sourceDb, feature.getName()))
 442         {
 443           parseCodingFeature(feature, sourceDb, seqs, dna, noPeptide);
 444         }
 445         else
 446         {
 447           // General feature type.
 448           if (!noNa)
 449           {
 450             if (feature.dbRefs != null && feature.dbRefs.size() > 0)
 451             {
 452               for (Iterator dbr = feature.dbRefs.iterator(); dbr.hasNext(); dna
 453                       .addDBRef((DBRefEntry) dbr.next()))
 454                 ;
 455             }
 456           }
 457         }
 458       }
 459     } catch (Exception e)
 460     {
 461       System.err.println("EMBL Record Features parsing error!");
 462       System.err
 463               .println("Please report the following to help@jalview.org :");
 464       System.err.println("EMBL Record " + accession);
 465       System.err.println("Resulted in exception: " + e.getMessage());
 466       e.printStackTrace(System.err);
 467     }
 468     if (!noNa && dna != null)
 469     {
 470       seqs.add(dna);
 471     }
 472     SequenceI[] sqs = new SequenceI[seqs.size()];
 473     for (int i = 0, j = seqs.size(); i < j; i++)
 474     {
 475       sqs[i] = (SequenceI) seqs.elementAt(i);
 476       seqs.set(i, null);
 477     }
 478     return sqs;
 479   }
 480
 481   /**
 482    * attempt to extract coding region and product from a feature and properly
 483    * decorate it with annotations.
 484    *
 485    * @param feature
 486    *                coding feature
 487    * @param sourceDb
 488    *                source database for the EMBLXML
 489    * @param seqs
 490    *                place where sequences go
 491    * @param dna
 492    *                parent dna sequence for this record
 493    * @param noPeptide
 494    *                flag for generation of Peptide sequence objects
 495    */
 496   private void parseCodingFeature(EmblFeature feature, String sourceDb,
 497           Vector seqs, Sequence dna, boolean noPeptide)
 498   {
 499     boolean isEmblCdna = sourceDb.equals(DBRefSource.EMBLCDS);
 500     // extract coding region(s)
 501     jalview.datamodel.Mapping map = null;
 502     int[] exon = null;
 503     if (feature.locations != null && feature.locations.size() > 0)
 504     {
 505       for (Enumeration locs = feature.locations.elements(); locs
 506               .hasMoreElements();)
 507       {
 508         EmblFeatureLocations loc = (EmblFeatureLocations) locs
 509                 .nextElement();
 510         int[] se = loc.getElementRanges(accession);
 511         if (exon == null)
 512         {
 513           exon = se;
 514         }
 515         else
 516         {
 517           int[] t = new int[exon.length + se.length];
 518           System.arraycopy(exon, 0, t, 0, exon.length);
 519           System.arraycopy(se, 0, t, exon.length, se.length);
 520           exon = t;
 521         }
 522       }
 523     }
 524     String prseq = null;
 525     String prname = new String();
 526     String prid = null;
 527     Hashtable vals = new Hashtable();
 528     int prstart = 1;
 529     // get qualifiers
 530     if (feature.getQualifiers() != null
 531             && feature.getQualifiers().size() > 0)
 532     {
 533       for (Iterator quals = feature.getQualifiers().iterator(); quals
 534               .hasNext();)
 535       {
 536         Qualifier q = (Qualifier) quals.next();
 537         if (q.getName().equals("translation"))
 538         {
 539           StringBuffer prsq = new StringBuffer(q.getValues()[0]);
 540           int p = prsq.indexOf(" ");
 541           while (p > -1)
 542           {
 543             prsq.deleteCharAt(p);
 544             p = prsq.indexOf(" ", p);
 545           }
 546           prseq = prsq.toString();
 547           prsq = null;
 548
 549         }
 550         else if (q.getName().equals("protein_id"))
 551         {
 552           prid = q.getValues()[0];
 553         }
 554         else if (q.getName().equals("codon_start"))
 555         {
 556           prstart = Integer.parseInt(q.getValues()[0]);
 557         }
 558         else if (q.getName().equals("product"))
 559         {
 560           prname = q.getValues()[0];
 561         }
 562         else
 563         {
 564           // throw anything else into the additional properties hash
 565           String[] s = q.getValues();
 566           StringBuffer sb = new StringBuffer();
 567           if (s != null)
 568           {
 569             for (int i = 0; i < s.length; i++)
 570             {
 571               sb.append(s[i]);
 572               sb.append("\n");
 573             }
 574           }
 575           vals.put(q.getName(), sb.toString());
 576         }
 577       }
 578     }
 579     Sequence product = null;
 580     if (prseq != null && prname != null && prid != null)
 581     {
 582       // extract proteins.
 583       product = new Sequence(prid, prseq, prstart, prstart + prseq.length()
 584               - 1);
 585       product
 586               .setDescription(((prname.length() == 0) ? "Protein Product from "
 587                       + sourceDb
 588                       : prname));
 589
 590       if (!noPeptide)
 591       {
 592         // Protein is also added to vector of sequences returned
 593         seqs.add(product);
 594       }
 595       // we have everything - create the mapping and perhaps the protein
 596       // sequence
 597       if (exon == null || exon.length == 0)
 598       {
 599         System.err
 600                 .println("Implementation Notice: EMBLCDS records not properly supported yet - Making up the CDNA region of this sequence... may be incorrect ("
 601                         + sourceDb + ":" + getAccession() + ")");
 602         if (prseq.length() * 3 == dna.getSequence().length)
 603         {
 604           // this might occur for CDS sequences where no features are
 605           // marked.
 606           exon = new int[]
 607           { dna.getStart(), dna.getEnd() };
 608           map = new jalview.datamodel.Mapping(product, exon, new int[]
 609           { prstart, prstart + prseq.length() - 1 }, 3, 1);
 610         }
 611         if ((prseq.length() + 1) * 3 == dna.getSequence().length)
 612         {
 613           exon = new int[]
 614           { dna.getStart(), dna.getEnd() - 3 };
 615           map = new jalview.datamodel.Mapping(product, exon, new int[]
 616           { prstart, prstart + prseq.length() - 1 }, 3, 1);
 617         }
 618       }
 619       else
 620       {
 621         if (isEmblCdna)
 622         {
 623           // TODO: Add a DbRef back to the parent EMBL sequence with the exon
 624           // map
 625           // if given a dataset reference, search dataset for parent EMBL
 626           // sequence if it exists and set its map
 627           // make a new feature annotating the coding contig
 628         }
 629         else
 630         {
 631           map = new jalview.datamodel.Mapping(product, exon, new int[]
 632           { prstart, prstart + prseq.length() - 1 }, 3, 1);
 633           // reconstruct the EMBLCDS entry
 634           DBRefEntry pcdnaref = new DBRefEntry();
 635           pcdnaref.setAccessionId(prid);
 636           pcdnaref.setSource(DBRefSource.EMBLCDS);
 637           pcdnaref.setVersion(getVersion()); // same as parent EMBL version.
 638           jalview.util.MapList mp = new jalview.util.MapList(new int[]
 639           { 1 + (prstart - 1) * 3,
 640               1 + (prstart - 1) * 3 + (prseq.length() - 1) * 3 }, new int[]
 641           { prstart, prstart + prseq.length() - 1 }, 3, 1);
 642           pcdnaref.setMap(new Mapping(mp));
 643           if (product != null)
 644             product.addDBRef(pcdnaref);
 645
 646         }
 647       }
 648       // add cds feature to dna seq - this may include the stop codon
 649       for (int xint = 0; exon != null && xint < exon.length; xint += 2)
 650       {
 651         SequenceFeature sf = new SequenceFeature();
 652         sf.setBegin(exon[xint]);
 653         sf.setEnd(exon[xint + 1]);
 654         sf.setType(feature.getName());
 655         sf.setFeatureGroup(sourceDb);
 656         sf.setDescription("Exon " + (1 + (int) (xint / 2))
 657                 + " for protein '" + prname + "' EMBLCDS:" + prid);
 658         sf.setValue(FeatureProperties.EXONPOS, new Integer(1 + xint));
 659         sf.setValue(FeatureProperties.EXONPRODUCT, prname);
 660         if (vals != null && vals.size() > 0)
 661         {
 662           Enumeration kv = vals.elements();
 663           while (kv.hasMoreElements())
 664           {
 665             Object key = kv.nextElement();
 666             if (key != null)
 667               sf.setValue(key.toString(), vals.get(key));
 668           }
 669         }
 670         dna.addSequenceFeature(sf);
 671       }
 672     }
 673     // add dbRefs to sequence
 674     if (feature.dbRefs != null && feature.dbRefs.size() > 0)
 675     {
 676       for (Iterator dbr = feature.dbRefs.iterator(); dbr.hasNext();)
 677       {
 678         DBRefEntry ref = (DBRefEntry) dbr.next();
 679         ref.setSource(jalview.util.DBRefUtils.getCanonicalName(ref
 680                 .getSource()));
 681         // Hard code the kind of protein product accessions that EMBL cite
 682         if (ref.getSource().equals(jalview.datamodel.DBRefSource.UNIPROT))
 683         {
 684           ref.setMap(map);
 685           if (map != null && map.getTo() != null)
 686           {
 687             map.getTo().addDBRef(
 688                     new DBRefEntry(ref.getSource(), ref.getVersion(), ref
 689                             .getAccessionId())); // don't copy map over.
 690             if (map.getTo().getName().indexOf(prid) == 0)
 691             {
 692               map.getTo().setName(
 693                       jalview.datamodel.DBRefSource.UNIPROT + "|"
 694                               + ref.getAccessionId());
 695             }
 696           }
 697         }
 698         if (product != null)
 699         {
 700           DBRefEntry pref = new DBRefEntry(ref.getSource(), ref
 701                   .getVersion(), ref.getAccessionId());
 702           pref.setMap(null); // reference is direct
 703           product.addDBRef(pref);
 704           // Add converse mapping reference
 705           if (map != null)
 706           {
 707             Mapping pmap = new Mapping(dna, map.getMap().getInverse());
 708             pref = new DBRefEntry(sourceDb, getVersion(), this
 709                     .getAccession());
 710             pref.setMap(pmap);
 711             if (map.getTo() != null)
 712             {
 713               map.getTo().addDBRef(pref);
 714             }
 715           }
 716         }
 717         dna.addDBRef(ref);
 718       }
 719     }
 720   }
 721 }