2f1da7f9ad9c125d334178b5e34a4bbc40422b24
[jalview.git] / Sequence.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.analysis.AlignSeq;
24 import jalview.api.DBRefEntryI;
25 import jalview.datamodel.features.SequenceFeatures;
26 import jalview.datamodel.features.SequenceFeaturesI;
27 import jalview.util.Comparison;
28 import jalview.util.DBRefUtils;
29 import jalview.util.MapList;
30 import jalview.util.StringUtils;
31
32 import java.util.ArrayList;
33 import java.util.Arrays;
34 import java.util.BitSet;
35 import java.util.Collections;
36 import java.util.Enumeration;
37 import java.util.List;
38 import java.util.ListIterator;
39 import java.util.Vector;
40
41 import com.stevesoft.pat.Regex;
42
43 import fr.orsay.lri.varna.models.rna.RNA;
44
45 /**
46  * 
47  * Implements the SequenceI interface for a char[] based sequence object.
48  * 
49  * @author $author$
50  * @version $Revision$
51  */
52 public class Sequence extends ASequence implements SequenceI
53 {
54   private static final Regex limitrx = new Regex(
55           "[/][0-9]{1,}[-][0-9]{1,}$");
56
57   private static final Regex endrx = new Regex("[0-9]{1,}$");
58
59   SequenceI datasetSequence;
60
61   String name;
62
63   private char[] sequence;
64
65   String description;
66
67   int start;
68
69   int end;
70
71   Vector<PDBEntry> pdbIds;
72
73   String vamsasId;
74
75   DBRefEntry[] dbrefs;
76
77   RNA rna;
78
79   /**
80    * This annotation is displayed below the alignment but the positions are tied
81    * to the residues of this sequence
82    *
83    * TODO: change to List<>
84    */
85   Vector<AlignmentAnnotation> annotation;
86
87   /**
88    * The index of the sequence in a MSA
89    */
90   int index = -1;
91
92   private SequenceFeatures sequenceFeatureStore;
93
94   /*
95    * A cursor holding the approximate current view position to the sequence,
96    * as determined by findIndex or findPosition or findPositions.
97    * Using a cursor as a hint allows these methods to be more performant for
98    * large sequences.
99    */
100   private SequenceCursor cursor;
101
102   /*
103    * A number that should be incremented whenever the sequence is edited.
104    * If the value matches the cursor token, then we can trust the cursor,
105    * if not then it should be recomputed. 
106    */
107   private int changeCount;
108
109   /**
110    * Creates a new Sequence object.
111    * 
112    * @param name
113    *          display name string
114    * @param sequence
115    *          string to form a possibly gapped sequence out of
116    * @param start
117    *          first position of non-gap residue in the sequence
118    * @param end
119    *          last position of ungapped residues (nearly always only used for
120    *          display purposes)
121    */
122   public Sequence(String name, String sequence, int start, int end)
123   {
124     this();
125     initSeqAndName(name, sequence.toCharArray(), start, end);
126   }
127
128   public Sequence(String name, char[] sequence, int start, int end)
129   {
130     this();
131     initSeqAndName(name, sequence, start, end);
132   }
133
134   /**
135    * Stage 1 constructor - assign name, sequence, and set start and end fields.
136    * start and end are updated values from name2 if it ends with /start-end
137    * 
138    * @param name2
139    * @param sequence2
140    * @param start2
141    * @param end2
142    */
143   protected void initSeqAndName(String name2, char[] sequence2, int start2,
144           int end2)
145   {
146     this.name = name2;
147     this.sequence = sequence2;
148     this.start = start2;
149     this.end = end2;
150     parseId();
151     checkValidRange();
152   }
153
154   void parseId()
155   {
156     if (name == null)
157     {
158       System.err.println(
159               "POSSIBLE IMPLEMENTATION ERROR: null sequence name passed to constructor.");
160       name = "";
161     }
162     // Does sequence have the /start-end signature?
163     if (limitrx.search(name))
164     {
165       name = limitrx.left();
166       endrx.search(limitrx.stringMatched());
167       setStart(Integer.parseInt(limitrx.stringMatched().substring(1,
168               endrx.matchedFrom() - 1)));
169       setEnd(Integer.parseInt(endrx.stringMatched()));
170     }
171   }
172
173   void checkValidRange()
174   {
175     // Note: JAL-774 :
176     // http://issues.jalview.org/browse/JAL-774?focusedCommentId=11239&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-11239
177     {
178       int endRes = 0;
179       for (int j = 0; j < sequence.length; j++)
180       {
181         if (!jalview.util.Comparison.isGap(sequence[j]))
182         {
183           endRes++;
184         }
185       }
186       if (endRes > 0)
187       {
188         endRes += start - 1;
189       }
190
191       if (end < endRes)
192       {
193         end = endRes;
194       }
195     }
196
197   }
198
199   /**
200    * default constructor
201    */
202   private Sequence()
203   {
204     sequenceFeatureStore = new SequenceFeatures();
205   }
206
207   /**
208    * Creates a new Sequence object.
209    * 
210    * @param name
211    *          DOCUMENT ME!
212    * @param sequence
213    *          DOCUMENT ME!
214    */
215   public Sequence(String name, String sequence)
216   {
217     this(name, sequence, 1, -1);
218   }
219
220   /**
221    * Creates a new Sequence object with new AlignmentAnnotations but inherits
222    * any existing dataset sequence reference. If non exists, everything is
223    * copied.
224    * 
225    * @param seq
226    *          if seq is a dataset sequence, behaves like a plain old copy
227    *          constructor
228    */
229   public Sequence(SequenceI seq)
230   {
231     this(seq, seq.getAnnotation());
232   }
233
234   /**
235    * Create a new sequence object with new features, DBRefEntries, and PDBIds
236    * but inherits any existing dataset sequence reference, and duplicate of any
237    * annotation that is present in the given annotation array.
238    * 
239    * @param seq
240    *          the sequence to be copied
241    * @param alAnnotation
242    *          an array of annotation including some associated with seq
243    */
244   public Sequence(SequenceI seq, AlignmentAnnotation[] alAnnotation)
245   {
246     this();
247     initSeqFrom(seq, alAnnotation);
248   }
249
250   /**
251    * does the heavy lifting when cloning a dataset sequence, or coping data from
252    * dataset to a new derived sequence.
253    * 
254    * @param seq
255    *          - source of attributes.
256    * @param alAnnotation
257    *          - alignment annotation present on seq that should be copied onto
258    *          this sequence
259    */
260   protected void initSeqFrom(SequenceI seq,
261           AlignmentAnnotation[] alAnnotation)
262   {
263     char[] oseq = seq.getSequence(); // returns a copy of the array
264     initSeqAndName(seq.getName(), oseq, seq.getStart(), seq.getEnd());
265
266     description = seq.getDescription();
267     if (seq != datasetSequence)
268     {
269       setDatasetSequence(seq.getDatasetSequence());
270     }
271     
272     /*
273      * only copy DBRefs and seqfeatures if we really are a dataset sequence
274      */
275     if (datasetSequence == null)
276     {
277       if (seq.getDBRefs() != null)
278       {
279         DBRefEntry[] dbr = seq.getDBRefs();
280         for (int i = 0; i < dbr.length; i++)
281         {
282           addDBRef(new DBRefEntry(dbr[i]));
283         }
284       }
285
286       /*
287        * make copies of any sequence features
288        */
289       for (SequenceFeature sf : seq.getSequenceFeatures())
290       {
291         addSequenceFeature(new SequenceFeature(sf));
292       }
293     }
294
295     if (seq.getAnnotation() != null)
296     {
297       AlignmentAnnotation[] sqann = seq.getAnnotation();
298       for (int i = 0; i < sqann.length; i++)
299       {
300         if (sqann[i] == null)
301         {
302           continue;
303         }
304         boolean found = (alAnnotation == null);
305         if (!found)
306         {
307           for (int apos = 0; !found && apos < alAnnotation.length; apos++)
308           {
309             found = (alAnnotation[apos] == sqann[i]);
310           }
311         }
312         if (found)
313         {
314           // only copy the given annotation
315           AlignmentAnnotation newann = new AlignmentAnnotation(sqann[i]);
316           addAlignmentAnnotation(newann);
317         }
318       }
319     }
320     if (seq.getAllPDBEntries() != null)
321     {
322       Vector<PDBEntry> ids = seq.getAllPDBEntries();
323       for (PDBEntry pdb : ids)
324       {
325         this.addPDBId(new PDBEntry(pdb));
326       }
327     }
328   }
329
330   @Override
331   public void setSequenceFeatures(List<SequenceFeature> features)
332   {
333     if (datasetSequence != null)
334     {
335       datasetSequence.setSequenceFeatures(features);
336       return;
337     }
338     sequenceFeatureStore = new SequenceFeatures(features);
339   }
340
341   @Override
342   public synchronized boolean addSequenceFeature(SequenceFeature sf)
343   {
344     if (sf.getType() == null)
345     {
346       System.err.println("SequenceFeature type may not be null: "
347               + sf.toString());
348       return false;
349     }
350
351     if (datasetSequence != null)
352     {
353       return datasetSequence.addSequenceFeature(sf);
354     }
355
356     return sequenceFeatureStore.add(sf);
357   }
358
359   @Override
360   public void deleteFeature(SequenceFeature sf)
361   {
362     if (datasetSequence != null)
363     {
364       datasetSequence.deleteFeature(sf);
365     }
366     else
367     {
368       sequenceFeatureStore.delete(sf);
369     }
370   }
371
372   /**
373    * {@inheritDoc}
374    * 
375    * @return
376    */
377   @Override
378   public List<SequenceFeature> getSequenceFeatures()
379   {
380     if (datasetSequence != null)
381     {
382       return datasetSequence.getSequenceFeatures();
383     }
384     return sequenceFeatureStore.getAllFeatures();
385   }
386
387   @Override
388   public SequenceFeaturesI getFeatures()
389   {
390     return datasetSequence != null ? datasetSequence.getFeatures()
391             : sequenceFeatureStore;
392   }
393
394   @Override
395   public boolean addPDBId(PDBEntry entry)
396   {
397     if (pdbIds == null)
398     {
399       pdbIds = new Vector<PDBEntry>();
400       pdbIds.add(entry);
401       return true;
402     }
403
404     for (PDBEntry pdbe : pdbIds)
405     {
406       if (pdbe.updateFrom(entry))
407       {
408         return false;
409       }
410     }
411     pdbIds.addElement(entry);
412     return true;
413   }
414
415   /**
416    * DOCUMENT ME!
417    * 
418    * @param id
419    *          DOCUMENT ME!
420    */
421   @Override
422   public void setPDBId(Vector<PDBEntry> id)
423   {
424     pdbIds = id;
425   }
426
427   /**
428    * DOCUMENT ME!
429    * 
430    * @return DOCUMENT ME!
431    */
432   @Override
433   public Vector<PDBEntry> getAllPDBEntries()
434   {
435     return pdbIds == null ? new Vector<PDBEntry>() : pdbIds;
436   }
437
438   /**
439    * DOCUMENT ME!
440    * 
441    * @return DOCUMENT ME!
442    */
443   @Override
444   public String getDisplayId(boolean jvsuffix)
445   {
446     StringBuffer result = new StringBuffer(name);
447     if (jvsuffix)
448     {
449       result.append("/" + start + "-" + end);
450     }
451
452     return result.toString();
453   }
454
455   /**
456    * DOCUMENT ME!
457    * 
458    * @param name
459    *          DOCUMENT ME!
460    */
461   @Override
462   public void setName(String name)
463   {
464     this.name = name;
465     this.parseId();
466   }
467
468   /**
469    * DOCUMENT ME!
470    * 
471    * @return DOCUMENT ME!
472    */
473   @Override
474   public String getName()
475   {
476     return this.name;
477   }
478
479   /**
480    * DOCUMENT ME!
481    * 
482    * @param start
483    *          DOCUMENT ME!
484    */
485   @Override
486   public void setStart(int start)
487   {
488     this.start = start;
489   }
490
491   /**
492    * DOCUMENT ME!
493    * 
494    * @return DOCUMENT ME!
495    */
496   @Override
497   public int getStart()
498   {
499     return this.start;
500   }
501
502   /**
503    * DOCUMENT ME!
504    * 
505    * @param end
506    *          DOCUMENT ME!
507    */
508   @Override
509   public void setEnd(int end)
510   {
511     this.end = end;
512   }
513
514   /**
515    * DOCUMENT ME!
516    * 
517    * @return DOCUMENT ME!
518    */
519   @Override
520   public int getEnd()
521   {
522     return this.end;
523   }
524
525   /**
526    * DOCUMENT ME!
527    * 
528    * @return DOCUMENT ME!
529    */
530   @Override
531   public int getLength()
532   {
533     return this.sequence.length;
534   }
535
536   /**
537    * DOCUMENT ME!
538    * 
539    * @param seq
540    *          DOCUMENT ME!
541    */
542   @Override
543   public void setSequence(String seq)
544   {
545     this.sequence = seq.toCharArray();
546     checkValidRange();
547     sequenceChanged();
548   }
549
550   @Override
551   public String getSequenceAsString()
552   {
553     return new String(sequence);
554   }
555
556   @Override
557   public String getSequenceAsString(int start, int end)
558   {
559     return new String(getSequence(start, end));
560   }
561
562   @Override
563   public char[] getSequence()
564   {
565     // return sequence;
566     return sequence == null ? null : Arrays.copyOf(sequence,
567             sequence.length);
568   }
569
570   /*
571    * (non-Javadoc)
572    * 
573    * @see jalview.datamodel.SequenceI#getSequence(int, int)
574    */
575   @Override
576   public char[] getSequence(int start, int end)
577   {
578     if (start < 0)
579     {
580       start = 0;
581     }
582     // JBPNote - left to user to pad the result here (TODO:Decide on this
583     // policy)
584     if (start >= sequence.length)
585     {
586       return new char[0];
587     }
588
589     if (end >= sequence.length)
590     {
591       end = sequence.length;
592     }
593
594     char[] reply = new char[end - start];
595     System.arraycopy(sequence, start, reply, 0, end - start);
596
597     return reply;
598   }
599
600   @Override
601   public SequenceI getSubSequence(int start, int end)
602   {
603     if (start < 0)
604     {
605       start = 0;
606     }
607     char[] seq = getSequence(start, end);
608     if (seq.length == 0)
609     {
610       return null;
611     }
612     int nstart = findPosition(start);
613     int nend = findPosition(end) - 1;
614     // JBPNote - this is an incomplete copy.
615     SequenceI nseq = new Sequence(this.getName(), seq, nstart, nend);
616     nseq.setDescription(description);
617     if (datasetSequence != null)
618     {
619       nseq.setDatasetSequence(datasetSequence);
620     }
621     else
622     {
623       nseq.setDatasetSequence(this);
624     }
625     return nseq;
626   }
627
628   /**
629    * Returns the character of the aligned sequence at the given position (base
630    * zero), or space if the position is not within the sequence's bounds
631    * 
632    * @return
633    */
634   @Override
635   public char getCharAt(int i)
636   {
637     if (i >= 0 && i < sequence.length)
638     {
639       return sequence[i];
640     }
641     else
642     {
643       return ' ';
644     }
645   }
646
647   /**
648    * DOCUMENT ME!
649    * 
650    * @param desc
651    *          DOCUMENT ME!
652    */
653   @Override
654   public void setDescription(String desc)
655   {
656     this.description = desc;
657   }
658
659   /**
660    * DOCUMENT ME!
661    * 
662    * @return DOCUMENT ME!
663    */
664   @Override
665   public String getDescription()
666   {
667     return this.description;
668   }
669
670   /**
671    * {@inheritDoc}
672    */
673   @Override
674   public int findIndex(int pos)
675   {
676     /*
677      * use a valid, hopefully nearby, cursor if available
678      */
679     if (isValidCursor(cursor))
680     {
681       return findIndex(pos, cursor);
682     }
683
684     int j = start;
685     int i = 0;
686     int startColumn = 0;
687
688     /*
689      * traverse sequence from the start counting gaps; make a note of
690      * the column of the first residue to save in the cursor
691      */
692     while ((i < sequence.length) && (j <= end) && (j <= pos))
693     {
694       if (!Comparison.isGap(sequence[i]))
695       {
696         if (j == start)
697         {
698           startColumn = i;
699         }
700         j++;
701       }
702       i++;
703     }
704
705     if (j == end && j < pos)
706     {
707       return end + 1;
708     }
709
710     updateCursor(pos, i, startColumn);
711     return i;
712   }
713
714   /**
715    * Updates the cursor to the latest found residue and column position
716    * 
717    * @param residuePos
718    *          (start..)
719    * @param column
720    *          (1..)
721    * @param startColumn
722    *          column position of the first sequence residue
723    */
724   protected void updateCursor(int residuePos, int column, int startColumn)
725   {
726     /*
727      * preserve end residue column provided cursor was valid
728      */
729     int endColumn = isValidCursor(cursor) ? cursor.lastColumnPosition : 0;
730     if (residuePos == this.end)
731     {
732       endColumn = column;
733     }
734
735     cursor = new SequenceCursor(this, residuePos, column, startColumn,
736             endColumn, this.changeCount);
737   }
738
739   /**
740    * Answers the aligned column position (1..) for the given residue position
741    * (start..) given a 'hint' of a residue/column location in the neighbourhood.
742    * The hint may be left of, at, or to the right of the required position.
743    * 
744    * @param pos
745    * @param curs
746    * @return
747    */
748   protected int findIndex(int pos, SequenceCursor curs)
749   {
750     if (!isValidCursor(curs))
751     {
752       /*
753        * wrong or invalidated cursor, compute de novo
754        */
755       return findIndex(pos);
756     }
757
758     if (curs.residuePosition == pos)
759     {
760       return curs.columnPosition;
761     }
762
763     /*
764      * move left or right to find pos from hint.position
765      */
766     int col = curs.columnPosition - 1; // convert from base 1 to 0-based array
767                                        // index
768     int newPos = curs.residuePosition;
769     int delta = newPos > pos ? -1 : 1;
770
771     while (newPos != pos)
772     {
773       col += delta; // shift one column left or right
774       if (col < 0 || col == sequence.length)
775       {
776         break;
777       }
778       if (!Comparison.isGap(sequence[col]))
779       {
780         newPos += delta;
781       }
782     }
783
784     col++; // convert back to base 1
785     updateCursor(pos, col, curs.firstColumnPosition);
786
787     return col;
788   }
789
790   /**
791    * {@inheritDoc}
792    */
793   @Override
794   public int findPosition(final int column)
795   {
796     /*
797      * use a valid, hopefully nearby, cursor if available
798      */
799     if (isValidCursor(cursor))
800     {
801       return findPosition(column + 1, cursor);
802     }
803     
804     // TODO recode this more naturally i.e. count residues only
805     // as they are found, not 'in anticipation'
806
807     /*
808      * traverse the sequence counting gaps; note the column position
809      * of the first residue, to save in the cursor
810      */
811     int firstResidueColumn = 0;
812     int lastPosFound = 0;
813     int lastPosFoundColumn = 0;
814     int seqlen = sequence.length;
815
816     if (seqlen > 0 && !Comparison.isGap(sequence[0]))
817     {
818       lastPosFound = start;
819       lastPosFoundColumn = 0;
820     }
821
822     int j = 0;
823     int pos = start;
824
825     while (j < column && j < seqlen)
826     {
827       if (!Comparison.isGap(sequence[j]))
828       {
829         lastPosFound = pos;
830         lastPosFoundColumn = j;
831         if (pos == this.start)
832         {
833           firstResidueColumn = j;
834         }
835         pos++;
836       }
837       j++;
838     }
839     if (j < seqlen && !Comparison.isGap(sequence[j]))
840     {
841       lastPosFound = pos;
842       lastPosFoundColumn = j;
843       if (pos == this.start)
844       {
845         firstResidueColumn = j;
846       }
847     }
848
849     /*
850      * update the cursor to the last residue position found (if any)
851      * (converting column position to base 1)
852      */
853     if (lastPosFound != 0)
854     {
855       updateCursor(lastPosFound, lastPosFoundColumn + 1,
856               firstResidueColumn + 1);
857     }
858
859     return pos;
860   }
861
862   /**
863    * Answers true if the given cursor is not null, is for this sequence object,
864    * and has a token value that matches this object's changeCount, else false.
865    * This allows us to ignore a cursor as 'stale' if the sequence has been
866    * modified since the cursor was created.
867    * 
868    * @param curs
869    * @return
870    */
871   protected boolean isValidCursor(SequenceCursor curs)
872   {
873     if (curs == null || curs.sequence != this || curs.token != changeCount)
874     {
875       return false;
876     }
877     /*
878      * sanity check against range
879      */
880     if (curs.columnPosition < 0 || curs.columnPosition > sequence.length)
881     {
882       return false;
883     }
884     if (curs.residuePosition < start || curs.residuePosition > end)
885     {
886       return false;
887     }
888     return true;
889   }
890
891   /**
892    * Answers the sequence position (start..) for the given aligned column
893    * position (1..), given a hint of a cursor in the neighbourhood. The cursor
894    * may lie left of, at, or to the right of the column position.
895    * 
896    * @param col
897    * @param curs
898    * @return
899    */
900   protected int findPosition(final int col, SequenceCursor curs)
901   {
902     if (!isValidCursor(curs))
903     {
904       /*
905        * wrong or invalidated cursor, compute de novo
906        */
907       return findPosition(col - 1);// ugh back to base 0
908     }
909
910     if (curs.columnPosition == col)
911     {
912       cursor = curs; // in case this method becomes public
913       return curs.residuePosition; // easy case :-)
914     }
915
916     if (curs.lastColumnPosition > 0 && curs.lastColumnPosition < col)
917     {
918       /*
919        * sequence lies entirely to the left of col
920        * - return last residue + 1
921        */
922       return end + 1;
923     }
924
925     if (curs.firstColumnPosition > 0 && curs.firstColumnPosition > col)
926     {
927       /*
928        * sequence lies entirely to the right of col
929        * - return first residue
930        */
931       return start;
932     }
933
934     // todo could choose closest to col out of column,
935     // firstColumnPosition, lastColumnPosition as a start point
936
937     /*
938      * move left or right to find pos from cursor position
939      */
940     int firstResidueColumn = curs.firstColumnPosition;
941     int column = curs.columnPosition - 1; // to base 0
942     int newPos = curs.residuePosition;
943     int delta = curs.columnPosition > col ? -1 : 1;
944     boolean gapped = false;
945     int lastFoundPosition = curs.residuePosition;
946     int lastFoundPositionColumn = curs.columnPosition;
947
948     while (column != col - 1)
949     {
950       column += delta; // shift one column left or right
951       if (column < 0 || column == sequence.length)
952       {
953         break;
954       }
955       gapped = Comparison.isGap(sequence[column]);
956       if (!gapped)
957       {
958         newPos += delta;
959         lastFoundPosition = newPos;
960         lastFoundPositionColumn = column + 1;
961         if (lastFoundPosition == this.start)
962         {
963           firstResidueColumn = column + 1;
964         }
965       }
966     }
967
968     if (cursor == null || lastFoundPosition != cursor.residuePosition)
969     {
970       updateCursor(lastFoundPosition, lastFoundPositionColumn,
971               firstResidueColumn);
972     }
973
974     /*
975      * hack to give position to the right if on a gap
976      * or beyond the length of the sequence (see JAL-2562)
977      */
978     if (delta > 0 && (gapped || column >= sequence.length))
979     {
980       newPos++;
981     }
982
983     return newPos;
984   }
985
986   /**
987    * {@inheritDoc}
988    */
989   @Override
990   public Range findPositions(int fromColumn, int toColumn)
991   {
992     if (toColumn < fromColumn || fromColumn < 1)
993     {
994       return null;
995     }
996
997     /*
998      * find the first non-gapped position, if any
999      */
1000     int firstPosition = 0;
1001     int col = fromColumn - 1;
1002     int length = sequence.length;
1003     while (col < length && col < toColumn)
1004     {
1005       if (!Comparison.isGap(sequence[col]))
1006       {
1007         firstPosition = findPosition(col++);
1008         break;
1009       }
1010       col++;
1011     }
1012
1013     if (firstPosition == 0)
1014     {
1015       return null;
1016     }
1017
1018     /*
1019      * find the last non-gapped position
1020      */
1021     int lastPosition = firstPosition;
1022     while (col < length && col < toColumn)
1023     {
1024       if (!Comparison.isGap(sequence[col++]))
1025       {
1026         lastPosition++;
1027       }
1028     }
1029
1030     return new Range(firstPosition, lastPosition);
1031   }
1032
1033   /**
1034    * Returns an int array where indices correspond to each residue in the
1035    * sequence and the element value gives its position in the alignment
1036    * 
1037    * @return int[SequenceI.getEnd()-SequenceI.getStart()+1] or null if no
1038    *         residues in SequenceI object
1039    */
1040   @Override
1041   public int[] gapMap()
1042   {
1043     String seq = jalview.analysis.AlignSeq.extractGaps(
1044             jalview.util.Comparison.GapChars, new String(sequence));
1045     int[] map = new int[seq.length()];
1046     int j = 0;
1047     int p = 0;
1048
1049     while (j < sequence.length)
1050     {
1051       if (!jalview.util.Comparison.isGap(sequence[j]))
1052       {
1053         map[p++] = j;
1054       }
1055
1056       j++;
1057     }
1058
1059     return map;
1060   }
1061
1062   @Override
1063   public int[] findPositionMap()
1064   {
1065     int map[] = new int[sequence.length];
1066     int j = 0;
1067     int pos = start;
1068     int seqlen = sequence.length;
1069     while ((j < seqlen))
1070     {
1071       map[j] = pos;
1072       if (!jalview.util.Comparison.isGap(sequence[j]))
1073       {
1074         pos++;
1075       }
1076
1077       j++;
1078     }
1079     return map;
1080   }
1081
1082   @Override
1083   public List<int[]> getInsertions()
1084   {
1085     ArrayList<int[]> map = new ArrayList<int[]>();
1086     int lastj = -1, j = 0;
1087     int pos = start;
1088     int seqlen = sequence.length;
1089     while ((j < seqlen))
1090     {
1091       if (jalview.util.Comparison.isGap(sequence[j]))
1092       {
1093         if (lastj == -1)
1094         {
1095           lastj = j;
1096         }
1097       }
1098       else
1099       {
1100         if (lastj != -1)
1101         {
1102           map.add(new int[] { lastj, j - 1 });
1103           lastj = -1;
1104         }
1105       }
1106       j++;
1107     }
1108     if (lastj != -1)
1109     {
1110       map.add(new int[] { lastj, j - 1 });
1111       lastj = -1;
1112     }
1113     return map;
1114   }
1115
1116   @Override
1117   public BitSet getInsertionsAsBits()
1118   {
1119     BitSet map = new BitSet();
1120     int lastj = -1, j = 0;
1121     int pos = start;
1122     int seqlen = sequence.length;
1123     while ((j < seqlen))
1124     {
1125       if (jalview.util.Comparison.isGap(sequence[j]))
1126       {
1127         if (lastj == -1)
1128         {
1129           lastj = j;
1130         }
1131       }
1132       else
1133       {
1134         if (lastj != -1)
1135         {
1136           map.set(lastj, j);
1137           lastj = -1;
1138         }
1139       }
1140       j++;
1141     }
1142     if (lastj != -1)
1143     {
1144       map.set(lastj, j);
1145       lastj = -1;
1146     }
1147     return map;
1148   }
1149
1150   @Override
1151   public void deleteChars(int i, int j)
1152   {
1153     int newstart = start, newend = end;
1154     if (i >= sequence.length || i < 0)
1155     {
1156       return;
1157     }
1158
1159     char[] tmp = StringUtils.deleteChars(sequence, i, j);
1160     boolean createNewDs = false;
1161     // TODO: take a (second look) at the dataset creation validation method for
1162     // the very large sequence case
1163     int eindex = -1, sindex = -1;
1164     boolean ecalc = false, scalc = false;
1165     for (int s = i; s < j; s++)
1166     {
1167       if (jalview.schemes.ResidueProperties.aaIndex[sequence[s]] != 23)
1168       {
1169         if (createNewDs)
1170         {
1171           newend--;
1172         }
1173         else
1174         {
1175           if (!scalc)
1176           {
1177             sindex = findIndex(start) - 1;
1178             scalc = true;
1179           }
1180           if (sindex == s)
1181           {
1182             // delete characters including start of sequence
1183             newstart = findPosition(j);
1184             break; // don't need to search for any more residue characters.
1185           }
1186           else
1187           {
1188             // delete characters after start.
1189             if (!ecalc)
1190             {
1191               eindex = findIndex(end) - 1;
1192               ecalc = true;
1193             }
1194             if (eindex < j)
1195             {
1196               // delete characters at end of sequence
1197               newend = findPosition(i - 1);
1198               break; // don't need to search for any more residue characters.
1199             }
1200             else
1201             {
1202               createNewDs = true;
1203               newend--; // decrease end position by one for the deleted residue
1204               // and search further
1205             }
1206           }
1207         }
1208       }
1209     }
1210     // deletion occured in the middle of the sequence
1211     if (createNewDs && this.datasetSequence != null)
1212     {
1213       // construct a new sequence
1214       Sequence ds = new Sequence(datasetSequence);
1215       // TODO: remove any non-inheritable properties ?
1216       // TODO: create a sequence mapping (since there is a relation here ?)
1217       ds.deleteChars(i, j);
1218       datasetSequence = ds;
1219     }
1220     start = newstart;
1221     end = newend;
1222     sequence = tmp;
1223     sequenceChanged();
1224   }
1225
1226   @Override
1227   public void insertCharAt(int i, int length, char c)
1228   {
1229     char[] tmp = new char[sequence.length + length];
1230
1231     if (i >= sequence.length)
1232     {
1233       System.arraycopy(sequence, 0, tmp, 0, sequence.length);
1234       i = sequence.length;
1235     }
1236     else
1237     {
1238       System.arraycopy(sequence, 0, tmp, 0, i);
1239     }
1240
1241     int index = i;
1242     while (length > 0)
1243     {
1244       tmp[index++] = c;
1245       length--;
1246     }
1247
1248     if (i < sequence.length)
1249     {
1250       System.arraycopy(sequence, i, tmp, index, sequence.length - i);
1251     }
1252
1253     sequence = tmp;
1254     sequenceChanged();
1255   }
1256
1257   @Override
1258   public void insertCharAt(int i, char c)
1259   {
1260     insertCharAt(i, 1, c);
1261   }
1262
1263   @Override
1264   public String getVamsasId()
1265   {
1266     return vamsasId;
1267   }
1268
1269   @Override
1270   public void setVamsasId(String id)
1271   {
1272     vamsasId = id;
1273   }
1274
1275   @Override
1276   public void setDBRefs(DBRefEntry[] dbref)
1277   {
1278     if (dbrefs == null && datasetSequence != null
1279             && this != datasetSequence)
1280     {
1281       datasetSequence.setDBRefs(dbref);
1282       return;
1283     }
1284     dbrefs = dbref;
1285     if (dbrefs != null)
1286     {
1287       DBRefUtils.ensurePrimaries(this);
1288     }
1289   }
1290
1291   @Override
1292   public DBRefEntry[] getDBRefs()
1293   {
1294     if (dbrefs == null && datasetSequence != null
1295             && this != datasetSequence)
1296     {
1297       return datasetSequence.getDBRefs();
1298     }
1299     return dbrefs;
1300   }
1301
1302   @Override
1303   public void addDBRef(DBRefEntry entry)
1304   {
1305     if (datasetSequence != null)
1306     {
1307       datasetSequence.addDBRef(entry);
1308       return;
1309     }
1310
1311     if (dbrefs == null)
1312     {
1313       dbrefs = new DBRefEntry[0];
1314     }
1315
1316     for (DBRefEntryI dbr : dbrefs)
1317     {
1318       if (dbr.updateFrom(entry))
1319       {
1320         /*
1321          * found a dbref that either matched, or could be
1322          * updated from, the new entry - no need to add it
1323          */
1324         return;
1325       }
1326     }
1327
1328     /*
1329      * extend the array to make room for one more
1330      */
1331     // TODO use an ArrayList instead
1332     int j = dbrefs.length;
1333     DBRefEntry[] temp = new DBRefEntry[j + 1];
1334     System.arraycopy(dbrefs, 0, temp, 0, j);
1335     temp[temp.length - 1] = entry;
1336
1337     dbrefs = temp;
1338
1339     DBRefUtils.ensurePrimaries(this);
1340   }
1341
1342   @Override
1343   public void setDatasetSequence(SequenceI seq)
1344   {
1345     if (seq == this)
1346     {
1347       throw new IllegalArgumentException(
1348               "Implementation Error: self reference passed to SequenceI.setDatasetSequence");
1349     }
1350     if (seq != null && seq.getDatasetSequence() != null)
1351     {
1352       throw new IllegalArgumentException(
1353               "Implementation error: cascading dataset sequences are not allowed.");
1354     }
1355     datasetSequence = seq;
1356   }
1357
1358   @Override
1359   public SequenceI getDatasetSequence()
1360   {
1361     return datasetSequence;
1362   }
1363
1364   @Override
1365   public AlignmentAnnotation[] getAnnotation()
1366   {
1367     return annotation == null ? null
1368             : annotation
1369                     .toArray(new AlignmentAnnotation[annotation.size()]);
1370   }
1371
1372   @Override
1373   public boolean hasAnnotation(AlignmentAnnotation ann)
1374   {
1375     return annotation == null ? false : annotation.contains(ann);
1376   }
1377
1378   @Override
1379   public void addAlignmentAnnotation(AlignmentAnnotation annotation)
1380   {
1381     if (this.annotation == null)
1382     {
1383       this.annotation = new Vector<AlignmentAnnotation>();
1384     }
1385     if (!this.annotation.contains(annotation))
1386     {
1387       this.annotation.addElement(annotation);
1388     }
1389     annotation.setSequenceRef(this);
1390   }
1391
1392   @Override
1393   public void removeAlignmentAnnotation(AlignmentAnnotation annotation)
1394   {
1395     if (this.annotation != null)
1396     {
1397       this.annotation.removeElement(annotation);
1398       if (this.annotation.size() == 0)
1399       {
1400         this.annotation = null;
1401       }
1402     }
1403   }
1404
1405   /**
1406    * test if this is a valid candidate for another sequence's dataset sequence.
1407    * 
1408    */
1409   private boolean isValidDatasetSequence()
1410   {
1411     if (datasetSequence != null)
1412     {
1413       return false;
1414     }
1415     for (int i = 0; i < sequence.length; i++)
1416     {
1417       if (jalview.util.Comparison.isGap(sequence[i]))
1418       {
1419         return false;
1420       }
1421     }
1422     return true;
1423   }
1424
1425   @Override
1426   public SequenceI deriveSequence()
1427   {
1428     Sequence seq = null;
1429     if (datasetSequence == null)
1430     {
1431       if (isValidDatasetSequence())
1432       {
1433         // Use this as dataset sequence
1434         seq = new Sequence(getName(), "", 1, -1);
1435         seq.setDatasetSequence(this);
1436         seq.initSeqFrom(this, getAnnotation());
1437         return seq;
1438       }
1439       else
1440       {
1441         // Create a new, valid dataset sequence
1442         createDatasetSequence();
1443       }
1444     }
1445     return new Sequence(this);
1446   }
1447
1448   private boolean _isNa;
1449
1450   private int _seqhash = 0;
1451
1452   /**
1453    * Answers false if the sequence is more than 85% nucleotide (ACGTU), else
1454    * true
1455    */
1456   @Override
1457   public boolean isProtein()
1458   {
1459     if (datasetSequence != null)
1460     {
1461       return datasetSequence.isProtein();
1462     }
1463     if (_seqhash != sequence.hashCode())
1464     {
1465       _seqhash = sequence.hashCode();
1466       _isNa = Comparison.isNucleotide(this);
1467     }
1468     return !_isNa;
1469   };
1470
1471   /*
1472    * (non-Javadoc)
1473    * 
1474    * @see jalview.datamodel.SequenceI#createDatasetSequence()
1475    */
1476   @Override
1477   public SequenceI createDatasetSequence()
1478   {
1479     if (datasetSequence == null)
1480     {
1481       Sequence dsseq = new Sequence(getName(),
1482               AlignSeq.extractGaps(jalview.util.Comparison.GapChars,
1483                       getSequenceAsString()),
1484               getStart(), getEnd());
1485
1486       datasetSequence = dsseq;
1487
1488       dsseq.setDescription(description);
1489       // move features and database references onto dataset sequence
1490       dsseq.sequenceFeatureStore = sequenceFeatureStore;
1491       sequenceFeatureStore = null;
1492       dsseq.dbrefs = dbrefs;
1493       dbrefs = null;
1494       // TODO: search and replace any references to this sequence with
1495       // references to the dataset sequence in Mappings on dbref
1496       dsseq.pdbIds = pdbIds;
1497       pdbIds = null;
1498       datasetSequence.updatePDBIds();
1499       if (annotation != null)
1500       {
1501         // annotation is cloned rather than moved, to preserve what's currently
1502         // on the alignment
1503         for (AlignmentAnnotation aa : annotation)
1504         {
1505           AlignmentAnnotation _aa = new AlignmentAnnotation(aa);
1506           _aa.sequenceRef = datasetSequence;
1507           _aa.adjustForAlignment(); // uses annotation's own record of
1508                                     // sequence-column mapping
1509           datasetSequence.addAlignmentAnnotation(_aa);
1510         }
1511       }
1512     }
1513     return datasetSequence;
1514   }
1515
1516   /*
1517    * (non-Javadoc)
1518    * 
1519    * @see
1520    * jalview.datamodel.SequenceI#setAlignmentAnnotation(AlignmmentAnnotation[]
1521    * annotations)
1522    */
1523   @Override
1524   public void setAlignmentAnnotation(AlignmentAnnotation[] annotations)
1525   {
1526     if (annotation != null)
1527     {
1528       annotation.removeAllElements();
1529     }
1530     if (annotations != null)
1531     {
1532       for (int i = 0; i < annotations.length; i++)
1533       {
1534         if (annotations[i] != null)
1535         {
1536           addAlignmentAnnotation(annotations[i]);
1537         }
1538       }
1539     }
1540   }
1541
1542   @Override
1543   public AlignmentAnnotation[] getAnnotation(String label)
1544   {
1545     if (annotation == null || annotation.size() == 0)
1546     {
1547       return null;
1548     }
1549
1550     Vector<AlignmentAnnotation> subset = new Vector<AlignmentAnnotation>();
1551     Enumeration<AlignmentAnnotation> e = annotation.elements();
1552     while (e.hasMoreElements())
1553     {
1554       AlignmentAnnotation ann = e.nextElement();
1555       if (ann.label != null && ann.label.equals(label))
1556       {
1557         subset.addElement(ann);
1558       }
1559     }
1560     if (subset.size() == 0)
1561     {
1562       return null;
1563     }
1564     AlignmentAnnotation[] anns = new AlignmentAnnotation[subset.size()];
1565     int i = 0;
1566     e = subset.elements();
1567     while (e.hasMoreElements())
1568     {
1569       anns[i++] = e.nextElement();
1570     }
1571     subset.removeAllElements();
1572     return anns;
1573   }
1574
1575   @Override
1576   public boolean updatePDBIds()
1577   {
1578     if (datasetSequence != null)
1579     {
1580       // TODO: could merge DBRefs
1581       return datasetSequence.updatePDBIds();
1582     }
1583     if (dbrefs == null || dbrefs.length == 0)
1584     {
1585       return false;
1586     }
1587     boolean added = false;
1588     for (DBRefEntry dbr : dbrefs)
1589     {
1590       if (DBRefSource.PDB.equals(dbr.getSource()))
1591       {
1592         /*
1593          * 'Add' any PDB dbrefs as a PDBEntry - add is only performed if the
1594          * PDB id is not already present in a 'matching' PDBEntry
1595          * Constructor parses out a chain code if appended to the accession id
1596          * (a fudge used to 'store' the chain code in the DBRef)
1597          */
1598         PDBEntry pdbe = new PDBEntry(dbr);
1599         added |= addPDBId(pdbe);
1600       }
1601     }
1602     return added;
1603   }
1604
1605   @Override
1606   public void transferAnnotation(SequenceI entry, Mapping mp)
1607   {
1608     if (datasetSequence != null)
1609     {
1610       datasetSequence.transferAnnotation(entry, mp);
1611       return;
1612     }
1613     if (entry.getDatasetSequence() != null)
1614     {
1615       transferAnnotation(entry.getDatasetSequence(), mp);
1616       return;
1617     }
1618     // transfer any new features from entry onto sequence
1619     if (entry.getSequenceFeatures() != null)
1620     {
1621
1622       List<SequenceFeature> sfs = entry.getSequenceFeatures();
1623       for (SequenceFeature feature : sfs)
1624       {
1625        SequenceFeature sf[] = (mp != null) ? mp.locateFeature(feature)
1626                 : new SequenceFeature[] { new SequenceFeature(feature) };
1627         if (sf != null)
1628         {
1629           for (int sfi = 0; sfi < sf.length; sfi++)
1630           {
1631             addSequenceFeature(sf[sfi]);
1632           }
1633         }
1634       }
1635     }
1636
1637     // transfer PDB entries
1638     if (entry.getAllPDBEntries() != null)
1639     {
1640       Enumeration<PDBEntry> e = entry.getAllPDBEntries().elements();
1641       while (e.hasMoreElements())
1642       {
1643         PDBEntry pdb = e.nextElement();
1644         addPDBId(pdb);
1645       }
1646     }
1647     // transfer database references
1648     DBRefEntry[] entryRefs = entry.getDBRefs();
1649     if (entryRefs != null)
1650     {
1651       for (int r = 0; r < entryRefs.length; r++)
1652       {
1653         DBRefEntry newref = new DBRefEntry(entryRefs[r]);
1654         if (newref.getMap() != null && mp != null)
1655         {
1656           // remap ref using our local mapping
1657         }
1658         // we also assume all version string setting is done by dbSourceProxy
1659         /*
1660          * if (!newref.getSource().equalsIgnoreCase(dbSource)) {
1661          * newref.setSource(dbSource); }
1662          */
1663         addDBRef(newref);
1664       }
1665     }
1666   }
1667
1668   /**
1669    * @return The index (zero-based) on this sequence in the MSA. It returns
1670    *         {@code -1} if this information is not available.
1671    */
1672   @Override
1673   public int getIndex()
1674   {
1675     return index;
1676   }
1677
1678   /**
1679    * Defines the position of this sequence in the MSA. Use the value {@code -1}
1680    * if this information is undefined.
1681    * 
1682    * @param The
1683    *          position for this sequence. This value is zero-based (zero for
1684    *          this first sequence)
1685    */
1686   @Override
1687   public void setIndex(int value)
1688   {
1689     index = value;
1690   }
1691
1692   @Override
1693   public void setRNA(RNA r)
1694   {
1695     rna = r;
1696   }
1697
1698   @Override
1699   public RNA getRNA()
1700   {
1701     return rna;
1702   }
1703
1704   @Override
1705   public List<AlignmentAnnotation> getAlignmentAnnotations(String calcId,
1706           String label)
1707   {
1708     List<AlignmentAnnotation> result = new ArrayList<AlignmentAnnotation>();
1709     if (this.annotation != null)
1710     {
1711       for (AlignmentAnnotation ann : annotation)
1712       {
1713         if (ann.calcId != null && ann.calcId.equals(calcId)
1714                 && ann.label != null && ann.label.equals(label))
1715         {
1716           result.add(ann);
1717         }
1718       }
1719     }
1720     return result;
1721   }
1722
1723   @Override
1724   public String toString()
1725   {
1726     return getDisplayId(false);
1727   }
1728
1729   @Override
1730   public PDBEntry getPDBEntry(String pdbIdStr)
1731   {
1732     if (getDatasetSequence() != null)
1733     {
1734       return getDatasetSequence().getPDBEntry(pdbIdStr);
1735     }
1736     if (pdbIds == null)
1737     {
1738       return null;
1739     }
1740     List<PDBEntry> entries = getAllPDBEntries();
1741     for (PDBEntry entry : entries)
1742     {
1743       if (entry.getId().equalsIgnoreCase(pdbIdStr))
1744       {
1745         return entry;
1746       }
1747     }
1748     return null;
1749   }
1750
1751   @Override
1752   public List<DBRefEntry> getPrimaryDBRefs()
1753   {
1754     if (datasetSequence != null)
1755     {
1756       return datasetSequence.getPrimaryDBRefs();
1757     }
1758     if (dbrefs == null || dbrefs.length == 0)
1759     {
1760       return Collections.emptyList();
1761     }
1762     synchronized (dbrefs)
1763     {
1764       List<DBRefEntry> primaries = new ArrayList<DBRefEntry>();
1765       DBRefEntry[] tmp = new DBRefEntry[1];
1766       for (DBRefEntry ref : dbrefs)
1767       {
1768         if (!ref.isPrimaryCandidate())
1769         {
1770           continue;
1771         }
1772         if (ref.hasMap())
1773         {
1774           MapList mp = ref.getMap().getMap();
1775           if (mp.getFromLowest() > start || mp.getFromHighest() < end)
1776           {
1777             // map only involves a subsequence, so cannot be primary
1778             continue;
1779           }
1780         }
1781         // whilst it looks like it is a primary ref, we also sanity check type
1782         if (DBRefUtils.getCanonicalName(DBRefSource.PDB)
1783                 .equals(DBRefUtils.getCanonicalName(ref.getSource())))
1784         {
1785           // PDB dbrefs imply there should be a PDBEntry associated
1786           // TODO: tighten PDB dbrefs
1787           // formally imply Jalview has actually downloaded and
1788           // parsed the pdb file. That means there should be a cached file
1789           // handle on the PDBEntry, and a real mapping between sequence and
1790           // extracted sequence from PDB file
1791           PDBEntry pdbentry = getPDBEntry(ref.getAccessionId());
1792           if (pdbentry != null && pdbentry.getFile() != null)
1793           {
1794             primaries.add(ref);
1795           }
1796           continue;
1797         }
1798         // check standard protein or dna sources
1799         tmp[0] = ref;
1800         DBRefEntry[] res = DBRefUtils.selectDbRefs(!isProtein(), tmp);
1801         if (res != null && res[0] == tmp[0])
1802         {
1803           primaries.add(ref);
1804           continue;
1805         }
1806       }
1807       return primaries;
1808     }
1809   }
1810
1811   /**
1812    * {@inheritDoc}
1813    */
1814   @Override
1815   public List<SequenceFeature> findFeatures(int fromColumn, int toColumn,
1816           String... types)
1817   {
1818     int startPos = findPosition(fromColumn - 1); // convert base 1 to base 0
1819     int endPos = fromColumn == toColumn ? startPos
1820             : findPosition(toColumn - 1);
1821
1822     List<SequenceFeature> result = getFeatures().findFeatures(startPos,
1823             endPos, types);
1824
1825     /*
1826      * if end column is gapped, endPos may be to the right, 
1827      * and we may have included adjacent or enclosing features;
1828      * remove any that are not enclosing, non-contact features
1829      */
1830     if (endPos > this.end || Comparison.isGap(sequence[toColumn - 1]))
1831     {
1832       ListIterator<SequenceFeature> it = result.listIterator();
1833       while (it.hasNext())
1834       {
1835         SequenceFeature sf = it.next();
1836         int sfBegin = sf.getBegin();
1837         int sfEnd = sf.getEnd();
1838         int featureStartColumn = findIndex(sfBegin);
1839         if (featureStartColumn > toColumn)
1840         {
1841           it.remove();
1842         }
1843         else if (featureStartColumn < fromColumn)
1844         {
1845           int featureEndColumn = sfEnd == sfBegin ? featureStartColumn
1846                   : findIndex(sfEnd);
1847           if (featureEndColumn < fromColumn)
1848           {
1849             it.remove();
1850           }
1851           else if (featureEndColumn > toColumn && sf.isContactFeature())
1852           {
1853             /*
1854              * remove an enclosing feature if it is a contact feature
1855              */
1856             it.remove();
1857           }
1858         }
1859       }
1860     }
1861
1862     return result;
1863   }
1864
1865   /**
1866    * Invalidates any stale cursors (forcing recalculation) by incrementing the
1867    * token that has to match the one presented by the cursor
1868    */
1869   @Override
1870   public void sequenceChanged()
1871   {
1872     changeCount++;
1873   }
1874
1875   /**
1876    * {@inheritDoc}
1877    */
1878   @Override
1879   public int replace(char c1, char c2)
1880   {
1881     if (c1 == c2)
1882     {
1883       return 0;
1884     }
1885     int count = 0;
1886     synchronized (sequence)
1887     {
1888       for (int c = 0; c < sequence.length; c++)
1889       {
1890         if (sequence[c] == c1)
1891         {
1892           sequence[c] = c2;
1893           count++;
1894         }
1895       }
1896     }
1897     if (count > 0)
1898     {
1899       sequenceChanged();
1900     }
1901
1902     return count;
1903   }
1904 }