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