src/jalview/datamodel/AlignedCodonFrame.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.util.MapList;
  24 import jalview.util.MappingUtils;
  25
  26 import java.util.AbstractList;
  27 import java.util.ArrayList;
  28 import java.util.List;
  29
  30 /**
  31  * Stores mapping between the columns of a protein alignment and a DNA alignment
  32  * and a list of individual codon to amino acid mappings between sequences.
  33  */
  34 public class AlignedCodonFrame
  35 {
  36
  37   /*
  38    * Data bean to hold mappings from one sequence to another
  39    */
  40   public class SequenceToSequenceMapping
  41   {
  42     private SequenceI fromSeq;
  43
  44     private Mapping mapping;
  45
  46     SequenceToSequenceMapping(SequenceI from, Mapping map)
  47     {
  48       this.fromSeq = from;
  49       this.mapping = map;
  50     }
  51
  52     /**
  53      * Readable representation for debugging only, not guaranteed not to change
  54      */
  55     @Override
  56     public String toString()
  57     {
  58       return String.format("From %s %s", fromSeq.getName(),
  59               mapping.toString());
  60     }
  61
  62     /**
  63      * Returns a hashCode derived from the hashcodes of the mappings and fromSeq
  64      *
  65      * @see SequenceToSequenceMapping#hashCode()
  66      */
  67     @Override
  68     public int hashCode()
  69     {
  70       return (fromSeq == null ? 0 : fromSeq.hashCode() * 31)
  71               + mapping.hashCode();
  72     }
  73
  74     /**
  75      * Answers true if the objects hold the same mapping between the same two
  76      * sequences
  77      *
  78      * @see Mapping#equals
  79      */
  80     @Override
  81     public boolean equals(Object obj)
  82     {
  83       if (!(obj instanceof SequenceToSequenceMapping))
  84       {
  85         return false;
  86       }
  87       SequenceToSequenceMapping that = (SequenceToSequenceMapping) obj;
  88       if (this.mapping == null)
  89       {
  90         return that.mapping == null;
  91       }
  92       // TODO: can simplify by asserting fromSeq is a dataset sequence
  93       return (this.fromSeq == that.fromSeq
  94               || (this.fromSeq != null && that.fromSeq != null
  95                       && this.fromSeq.getDatasetSequence() != null
  96                       && this.fromSeq.getDatasetSequence() == that.fromSeq
  97                               .getDatasetSequence()))
  98               && this.mapping.equals(that.mapping);
  99     }
 100
 101     public SequenceI getFromSeq()
 102     {
 103       return fromSeq;
 104     }
 105
 106     public Mapping getMapping()
 107     {
 108       return mapping;
 109     }
 110
 111     /**
 112      * Returns true if the mapping covers the full length of the given sequence.
 113      * This allows us to distinguish the CDS that codes for a protein from
 114      * another overlapping CDS in the parent dna sequence.
 115      *
 116      * @param seq
 117      * @return
 118      */
 119     public boolean covers(SequenceI seq)
 120     {
 121       List<int[]> mappedRanges = null;
 122       MapList mapList = mapping.getMap();
 123       if (fromSeq == seq || fromSeq == seq.getDatasetSequence())
 124       {
 125         mappedRanges = mapList.getFromRanges();
 126       }
 127       else if (mapping.to == seq || mapping.to == seq.getDatasetSequence())
 128       {
 129         mappedRanges = mapList.getToRanges();
 130       }
 131       else
 132       {
 133         return false;
 134       }
 135
 136       /*
 137        * check that each mapped range lieS with the sequence range
 138        * (necessary for circular CDS - example EMBL:J03321:AAA91567)
 139        * and mapped length covers (at least) sequence length
 140        */
 141       int length = 0;
 142       for (int[] range : mappedRanges)
 143       {
 144         int from = Math.min(range[0], range[1]);
 145         int to = Math.max(range[0], range[1]);
 146         if (from < seq.getStart() || to > seq.getEnd())
 147         {
 148           return false;
 149         }
 150         length += (to - from + 1);
 151       }
 152       // add 1 to mapped length to allow for a mapped stop codon
 153       if (length + 1 < (seq.getEnd() - seq.getStart() + 1))
 154       {
 155         return false;
 156       }
 157       return true;
 158     }
 159   }
 160
 161   private List<SequenceToSequenceMapping> mappings;
 162
 163   /**
 164    * Constructor
 165    */
 166   public AlignedCodonFrame()
 167   {
 168     mappings = new ArrayList<>();
 169   }
 170
 171   /**
 172    * Adds a mapping between the dataset sequences for the associated dna and
 173    * protein sequence objects
 174    *
 175    * @param dnaseq
 176    * @param aaseq
 177    * @param map
 178    */
 179   public void addMap(SequenceI dnaseq, SequenceI aaseq, MapList map)
 180   {
 181     addMap(dnaseq, aaseq, map, null);
 182   }
 183
 184   /**
 185    * Adds a mapping between the dataset sequences for the associated dna and
 186    * protein sequence objects
 187    *
 188    * @param dnaseq
 189    * @param aaseq
 190    * @param map
 191    * @param mapFromId
 192    */
 193   public void addMap(SequenceI dnaseq, SequenceI aaseq, MapList map,
 194           String mapFromId)
 195   {
 196     // JBPNote DEBUG! THIS !
 197     // dnaseq.transferAnnotation(aaseq, mp);
 198     // aaseq.transferAnnotation(dnaseq, new Mapping(map.getInverse()));
 199
 200     SequenceI fromSeq = (dnaseq.getDatasetSequence() == null) ? dnaseq
 201             : dnaseq.getDatasetSequence();
 202     SequenceI toSeq = (aaseq.getDatasetSequence() == null) ? aaseq
 203             : aaseq.getDatasetSequence();
 204
 205     /*
 206      * if we already hold a mapping between these sequences, just add to it
 207      * note that 'adding' a duplicate map does nothing; this protects against
 208      * creating duplicate mappings in AlignedCodonFrame
 209      */
 210     for (SequenceToSequenceMapping ssm : mappings)
 211     {
 212       if (ssm.fromSeq == fromSeq && ssm.mapping.to == toSeq)
 213       {
 214         ssm.mapping.map.addMapList(map);
 215         return;
 216       }
 217     }
 218
 219     /*
 220      * otherwise, add a new sequence mapping
 221      */
 222     Mapping mp = new Mapping(toSeq, map);
 223     mp.setMappedFromId(mapFromId);
 224     mappings.add(new SequenceToSequenceMapping(fromSeq, mp));
 225   }
 226
 227   public SequenceI[] getdnaSeqs()
 228   {
 229     // TODO return a list instead?
 230     // return dnaSeqs;
 231     List<SequenceI> seqs = new ArrayList<>();
 232     for (SequenceToSequenceMapping ssm : mappings)
 233     {
 234       seqs.add(ssm.fromSeq);
 235     }
 236     return seqs.toArray(new SequenceI[seqs.size()]);
 237   }
 238
 239   public SequenceI[] getAaSeqs()
 240   {
 241     // TODO not used - remove?
 242     List<SequenceI> seqs = new ArrayList<>();
 243     for (SequenceToSequenceMapping ssm : mappings)
 244     {
 245       seqs.add(ssm.mapping.to);
 246     }
 247     return seqs.toArray(new SequenceI[seqs.size()]);
 248   }
 249
 250   public MapList[] getdnaToProt()
 251   {
 252     List<MapList> maps = new ArrayList<>();
 253     for (SequenceToSequenceMapping ssm : mappings)
 254     {
 255       maps.add(ssm.mapping.map);
 256     }
 257     return maps.toArray(new MapList[maps.size()]);
 258   }
 259
 260   public Mapping[] getProtMappings()
 261   {
 262     List<Mapping> maps = new ArrayList<>();
 263     for (SequenceToSequenceMapping ssm : mappings)
 264     {
 265       maps.add(ssm.mapping);
 266     }
 267     return maps.toArray(new Mapping[maps.size()]);
 268   }
 269
 270   /**
 271    * Returns the first mapping found which is to or from the given sequence, or
 272    * null if none is found
 273    *
 274    * @param seq
 275    * @return
 276    */
 277   public Mapping getMappingForSequence(SequenceI seq)
 278   {
 279     SequenceI seqDs = seq.getDatasetSequence();
 280     seqDs = seqDs != null ? seqDs : seq;
 281
 282     for (SequenceToSequenceMapping ssm : mappings)
 283     {
 284       if (ssm.fromSeq == seqDs || ssm.mapping.to == seqDs)
 285       {
 286         return ssm.mapping;
 287       }
 288     }
 289     return null;
 290   }
 291
 292   /**
 293    * Return the corresponding aligned or dataset aa sequence for given dna
 294    * sequence, null if not found.
 295    *
 296    * @param sequenceRef
 297    * @return
 298    */
 299   public SequenceI getAaForDnaSeq(SequenceI dnaSeqRef)
 300   {
 301     SequenceI dnads = dnaSeqRef.getDatasetSequence();
 302     for (SequenceToSequenceMapping ssm : mappings)
 303     {
 304       if (ssm.fromSeq == dnaSeqRef || ssm.fromSeq == dnads)
 305       {
 306         return ssm.mapping.to;
 307       }
 308     }
 309     return null;
 310   }
 311
 312   /**
 313    * Return the corresponding aligned or dataset dna sequence for given amino
 314    * acid sequence, or null if not found. returns the sequence from the first
 315    * mapping found that involves the protein sequence.
 316    *
 317    * @param aaSeqRef
 318    * @return
 319    */
 320   public SequenceI getDnaForAaSeq(SequenceI aaSeqRef)
 321   {
 322     SequenceI aads = aaSeqRef.getDatasetSequence();
 323     for (SequenceToSequenceMapping ssm : mappings)
 324     {
 325       if (ssm.mapping.to == aaSeqRef || ssm.mapping.to == aads)
 326       {
 327         return ssm.fromSeq;
 328       }
 329     }
 330     return null;
 331   }
 332
 333   /**
 334    * test to see if codon frame involves seq in any way
 335    *
 336    * @param seq
 337    *          a nucleotide or protein sequence
 338    * @return true if a mapping exists to or from this sequence to any translated
 339    *         sequence
 340    */
 341   public boolean involvesSequence(SequenceI seq)
 342   {
 343     return getAaForDnaSeq(seq) != null || getDnaForAaSeq(seq) != null;
 344   }
 345
 346   /**
 347    * Add search results for regions in other sequences that translate or are
 348    * translated from a particular position in seq
 349    *
 350    * @param seq
 351    * @param index
 352    *          position in seq
 353    * @param results
 354    *          where highlighted regions go
 355    */
 356   public void markMappedRegion(SequenceI seq, int index,
 357           SearchResultsI results)
 358   {
 359     int[] codon;
 360     SequenceI ds = seq.getDatasetSequence();
 361     for (SequenceToSequenceMapping ssm : mappings)
 362     {
 363       if (ssm.fromSeq == seq || ssm.fromSeq == ds)
 364       {
 365         codon = ssm.mapping.map.locateInTo(index, index);
 366         if (codon != null)
 367         {
 368           for (int i = 0; i < codon.length; i += 2)
 369           {
 370             results.addResult(ssm.mapping.to, codon[i], codon[i + 1]);
 371           }
 372         }
 373       }
 374       else if (ssm.mapping.to == seq || ssm.mapping.to == ds)
 375       {
 376         {
 377           codon = ssm.mapping.map.locateInFrom(index, index);
 378           if (codon != null)
 379           {
 380             for (int i = 0; i < codon.length; i += 2)
 381             {
 382               results.addResult(ssm.fromSeq, codon[i], codon[i + 1]);
 383             }
 384           }
 385         }
 386       }
 387     }
 388   }
 389
 390   /**
 391    * Returns the DNA codon positions (base 1) for the given position (base 1) in
 392    * a mapped protein sequence, or null if no mapping is found.
 393    *
 394    * Intended for use in aligning cDNA to match aligned protein. Only the first
 395    * mapping found is returned, so not suitable for use if multiple protein
 396    * sequences are mapped to the same cDNA (but aligning cDNA as protein is
 397    * ill-defined for this case anyway).
 398    *
 399    * @param seq
 400    *          the DNA dataset sequence
 401    * @param aaPos
 402    *          residue position (base 1) in a protein sequence
 403    * @return
 404    */
 405   public int[] getDnaPosition(SequenceI seq, int aaPos)
 406   {
 407     /*
 408      * Adapted from markMappedRegion().
 409      */
 410     MapList ml = null;
 411     int i = 0;
 412     for (SequenceToSequenceMapping ssm : mappings)
 413     {
 414       if (ssm.fromSeq == seq)
 415       {
 416         ml = getdnaToProt()[i];
 417         break;
 418       }
 419       i++;
 420     }
 421     return ml == null ? null : ml.locateInFrom(aaPos, aaPos);
 422   }
 423
 424   /**
 425    * Convenience method to return the first aligned sequence in the given
 426    * alignment whose dataset has a mapping with the given (aligned or dataset)
 427    * sequence.
 428    *
 429    * @param seq
 430    *
 431    * @param al
 432    * @return
 433    */
 434   public SequenceI findAlignedSequence(SequenceI seq, AlignmentI al)
 435   {
 436     /*
 437      * Search mapped protein ('to') sequences first.
 438      */
 439     for (SequenceToSequenceMapping ssm : mappings)
 440     {
 441       if (ssm.fromSeq == seq || ssm.fromSeq == seq.getDatasetSequence())
 442       {
 443         for (SequenceI sourceAligned : al.getSequences())
 444         {
 445           if (ssm.mapping.to == sourceAligned.getDatasetSequence()
 446                   || ssm.mapping.to == sourceAligned)
 447           {
 448             return sourceAligned;
 449           }
 450         }
 451       }
 452     }
 453
 454     /*
 455      * Then try mapped dna sequences.
 456      */
 457     for (SequenceToSequenceMapping ssm : mappings)
 458     {
 459       if (ssm.mapping.to == seq
 460               || ssm.mapping.to == seq.getDatasetSequence())
 461       {
 462         for (SequenceI sourceAligned : al.getSequences())
 463         {
 464           if (ssm.fromSeq == sourceAligned.getDatasetSequence())
 465           {
 466             return sourceAligned;
 467           }
 468         }
 469       }
 470     }
 471
 472     return null;
 473   }
 474
 475   /**
 476    * Returns the region in the target sequence's dataset that is mapped to the
 477    * given position (base 1) in the query sequence's dataset. The region is a
 478    * set of start/end position pairs.
 479    *
 480    * @param target
 481    * @param query
 482    * @param queryPos
 483    * @return
 484    */
 485   public int[] getMappedRegion(SequenceI target, SequenceI query,
 486           int queryPos)
 487   {
 488     SequenceI targetDs = target.getDatasetSequence() == null ? target
 489             : target.getDatasetSequence();
 490     SequenceI queryDs = query.getDatasetSequence() == null ? query
 491             : query.getDatasetSequence();
 492     if (targetDs == null || queryDs == null /*|| dnaToProt == null*/)
 493     {
 494       return null;
 495     }
 496     for (SequenceToSequenceMapping ssm : mappings)
 497     {
 498       /*
 499        * try mapping from target to query
 500        */
 501       if (ssm.fromSeq == targetDs && ssm.mapping.to == queryDs)
 502       {
 503         int[] codon = ssm.mapping.map.locateInFrom(queryPos, queryPos);
 504         if (codon != null)
 505         {
 506           return codon;
 507         }
 508       }
 509       /*
 510        * else try mapping from query to target
 511        */
 512       else if (ssm.fromSeq == queryDs && ssm.mapping.to == targetDs)
 513       {
 514         int[] codon = ssm.mapping.map.locateInTo(queryPos, queryPos);
 515         if (codon != null)
 516         {
 517           return codon;
 518         }
 519       }
 520     }
 521     return null;
 522   }
 523
 524   /**
 525    * Returns the mapped DNA codons for the given position in a protein sequence,
 526    * or null if no mapping is found. Returns a list of (e.g.) ['g', 'c', 't']
 527    * codons. There may be more than one codon mapped to the protein if (for
 528    * example), there are mappings to cDNA variants.
 529    *
 530    * @param protein
 531    *          the peptide dataset sequence
 532    * @param aaPos
 533    *          residue position (base 1) in the peptide sequence
 534    * @return
 535    */
 536   public List<char[]> getMappedCodons(SequenceI protein, int aaPos)
 537   {
 538     MapList ml = null;
 539     SequenceI dnaSeq = null;
 540     List<char[]> result = new ArrayList<>();
 541
 542     for (SequenceToSequenceMapping ssm : mappings)
 543     {
 544       if (ssm.mapping.to == protein
 545               && ssm.mapping.getMap().getFromRatio() == 3)
 546       {
 547         ml = ssm.mapping.map;
 548         dnaSeq = ssm.fromSeq;
 549
 550         int[] codonPos = ml.locateInFrom(aaPos, aaPos);
 551         if (codonPos == null)
 552         {
 553           return null;
 554         }
 555
 556         /*
 557          * Read off the mapped nucleotides (converting to position base 0)
 558          */
 559         codonPos = MappingUtils.flattenRanges(codonPos);
 560         int start = dnaSeq.getStart();
 561         char c1 = dnaSeq.getCharAt(codonPos[0] - start);
 562         char c2 = dnaSeq.getCharAt(codonPos[1] - start);
 563         char c3 = dnaSeq.getCharAt(codonPos[2] - start);
 564         result.add(new char[] { c1, c2, c3 });
 565       }
 566     }
 567     return result.isEmpty() ? null : result;
 568   }
 569
 570   /**
 571    * Returns any mappings found which are from the given sequence, and to
 572    * distinct sequences.
 573    *
 574    * @param seq
 575    * @return
 576    */
 577   public List<Mapping> getMappingsFromSequence(SequenceI seq)
 578   {
 579     List<Mapping> result = new ArrayList<>();
 580     List<SequenceI> related = new ArrayList<>();
 581     SequenceI seqDs = seq.getDatasetSequence();
 582     seqDs = seqDs != null ? seqDs : seq;
 583
 584     for (SequenceToSequenceMapping ssm : mappings)
 585     {
 586       final Mapping mapping = ssm.mapping;
 587       if (ssm.fromSeq == seqDs)
 588       {
 589         if (!related.contains(mapping.to))
 590         {
 591           result.add(mapping);
 592           related.add(mapping.to);
 593         }
 594       }
 595     }
 596     return result;
 597   }
 598
 599   /**
 600    * Test whether the given sequence is substitutable for one or more dummy
 601    * sequences in this mapping
 602    *
 603    * @param map
 604    * @param seq
 605    * @return
 606    */
 607   public boolean isRealisableWith(SequenceI seq)
 608   {
 609     return realiseWith(seq, false) > 0;
 610   }
 611
 612   /**
 613    * Replace any matchable mapped dummy sequences with the given real one.
 614    * Returns the count of sequence mappings instantiated.
 615    *
 616    * @param seq
 617    * @return
 618    */
 619   public int realiseWith(SequenceI seq)
 620   {
 621     return realiseWith(seq, true);
 622   }
 623
 624   /**
 625    * Returns the number of mapped dummy sequences that could be replaced with
 626    * the given real sequence.
 627    *
 628    * @param seq
 629    *          a dataset sequence
 630    * @param doUpdate
 631    *          if true, performs replacements, else only counts
 632    * @return
 633    */
 634   protected int realiseWith(SequenceI seq, boolean doUpdate)
 635   {
 636     SequenceI ds = seq.getDatasetSequence() != null
 637             ? seq.getDatasetSequence()
 638             : seq;
 639     int count = 0;
 640
 641     /*
 642      * check for replaceable DNA ('map from') sequences
 643      */
 644     for (SequenceToSequenceMapping ssm : mappings)
 645     {
 646       SequenceI dna = ssm.fromSeq;
 647       if (dna instanceof SequenceDummy
 648               && dna.getName().equals(ds.getName()))
 649       {
 650         Mapping mapping = ssm.mapping;
 651         int mapStart = mapping.getMap().getFromLowest();
 652         int mapEnd = mapping.getMap().getFromHighest();
 653         boolean mappable = couldRealiseSequence(dna, ds, mapStart, mapEnd);
 654         if (mappable)
 655         {
 656           count++;
 657           if (doUpdate)
 658           {
 659             // TODO: new method ? ds.realise(dna);
 660             // might want to copy database refs as well
 661             ds.setSequenceFeatures(dna.getSequenceFeatures());
 662             // dnaSeqs[i] = ds;
 663             ssm.fromSeq = ds;
 664             System.out.println("Realised mapped sequence " + ds.getName());
 665           }
 666         }
 667       }
 668
 669       /*
 670        * check for replaceable protein ('map to') sequences
 671        */
 672       Mapping mapping = ssm.mapping;
 673       SequenceI prot = mapping.getTo();
 674       int mapStart = mapping.getMap().getToLowest();
 675       int mapEnd = mapping.getMap().getToHighest();
 676       boolean mappable = couldRealiseSequence(prot, ds, mapStart, mapEnd);
 677       if (mappable)
 678       {
 679         count++;
 680         if (doUpdate)
 681         {
 682           // TODO: new method ? ds.realise(dna);
 683           // might want to copy database refs as well
 684           ds.setSequenceFeatures(dna.getSequenceFeatures());
 685           ssm.mapping.setTo(ds);
 686         }
 687       }
 688     }
 689     return count;
 690   }
 691
 692   /**
 693    * Helper method to test whether a 'real' sequence could replace a 'dummy'
 694    * sequence in the map. The criteria are that they have the same name, and
 695    * that the mapped region overlaps the candidate sequence.
 696    *
 697    * @param existing
 698    * @param replacement
 699    * @param mapStart
 700    * @param mapEnd
 701    * @return
 702    */
 703   protected static boolean couldRealiseSequence(SequenceI existing,
 704           SequenceI replacement, int mapStart, int mapEnd)
 705   {
 706     if (existing instanceof SequenceDummy
 707             && !(replacement instanceof SequenceDummy)
 708             && existing.getName().equals(replacement.getName()))
 709     {
 710       int start = replacement.getStart();
 711       int end = replacement.getEnd();
 712       boolean mappingOverlapsSequence = (mapStart >= start
 713               && mapStart <= end) || (mapEnd >= start && mapEnd <= end);
 714       if (mappingOverlapsSequence)
 715       {
 716         return true;
 717       }
 718     }
 719     return false;
 720   }
 721
 722   /**
 723    * Change any mapping to the given sequence to be to its dataset sequence
 724    * instead. For use when mappings are created before their referenced
 725    * sequences are instantiated, for example when parsing GFF data.
 726    *
 727    * @param seq
 728    */
 729   public void updateToDataset(SequenceI seq)
 730   {
 731     if (seq == null || seq.getDatasetSequence() == null)
 732     {
 733       return;
 734     }
 735     SequenceI ds = seq.getDatasetSequence();
 736
 737     for (SequenceToSequenceMapping ssm : mappings)
 738     /*
 739      * 'from' sequences
 740      */
 741     {
 742       if (ssm.fromSeq == seq)
 743       {
 744         ssm.fromSeq = ds;
 745       }
 746
 747       /*
 748        * 'to' sequences
 749        */
 750       if (ssm.mapping.to == seq)
 751       {
 752         ssm.mapping.to = ds;
 753       }
 754     }
 755   }
 756
 757   /**
 758    * Answers true if this object contains no mappings
 759    *
 760    * @return
 761    */
 762   public boolean isEmpty()
 763   {
 764     return mappings.isEmpty();
 765   }
 766
 767   /**
 768    * Method for debug / inspection purposes only, may change in future
 769    */
 770   @Override
 771   public String toString()
 772   {
 773     return mappings == null ? "null" : mappings.toString();
 774   }
 775
 776   /**
 777    * Returns the first mapping found that is between 'fromSeq' and 'toSeq', or
 778    * null if none found
 779    *
 780    * @param fromSeq
 781    *          aligned or dataset sequence
 782    * @param toSeq
 783    *          aligned or dataset sequence
 784    * @return
 785    */
 786   public Mapping getMappingBetween(SequenceI fromSeq, SequenceI toSeq)
 787   {
 788     SequenceI dssFrom = fromSeq.getDatasetSequence() == null ? fromSeq
 789             : fromSeq.getDatasetSequence();
 790     SequenceI dssTo = toSeq.getDatasetSequence() == null ? toSeq
 791             : toSeq.getDatasetSequence();
 792
 793     for (SequenceToSequenceMapping mapping : mappings)
 794     {
 795       SequenceI from = mapping.fromSeq;
 796       SequenceI to = mapping.mapping.to;
 797       if ((from == dssFrom && to == dssTo)
 798               || (from == dssTo && to == dssFrom))
 799       {
 800         return mapping.mapping;
 801       }
 802     }
 803     return null;
 804   }
 805
 806   /**
 807    * Returns a hashcode derived from the list of sequence mappings
 808    *
 809    * @see SequenceToSequenceMapping#hashCode()
 810    * @see AbstractList#hashCode()
 811    */
 812   @Override
 813   public int hashCode()
 814   {
 815     return this.mappings.hashCode();
 816   }
 817
 818   /**
 819    * Two AlignedCodonFrame objects are equal if they hold the same ordered list
 820    * of mappings
 821    *
 822    * @see SequenceToSequenceMapping#equals
 823    */
 824   @Override
 825   public boolean equals(Object obj)
 826   {
 827     if (!(obj instanceof AlignedCodonFrame))
 828     {
 829       return false;
 830     }
 831     return this.mappings.equals(((AlignedCodonFrame) obj).mappings);
 832   }
 833
 834   public List<SequenceToSequenceMapping> getMappings()
 835   {
 836     return mappings;
 837   }
 838
 839   /**
 840    * Returns the first mapping found which is between the two given sequences,
 841    * and covers the full extent of both.
 842    *
 843    * @param seq1
 844    * @param seq2
 845    * @return
 846    */
 847   public SequenceToSequenceMapping getCoveringMapping(SequenceI seq1,
 848           SequenceI seq2)
 849   {
 850     for (SequenceToSequenceMapping mapping : mappings)
 851     {
 852       if (mapping.covers(seq2) && mapping.covers(seq1))
 853       {
 854         return mapping;
 855       }
 856     }
 857     return null;
 858   }
 859 }