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