Classes

Class	Line #	Total Statements	Complexity	Uncovered Elements	TOTAL Coverage	Actions
AlignmentI	31	0	0	0	-1.0 -	Show methods

Class AlignmentI

Class AlignmentI	Line # 31	Total Statements 0	Complexity 0	Uncovered Elements 0	TOTAL Coverage -1.0 -

 

Contributing tests

Source view

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.Hashtable;
24		import java.util.List;
25		import java.util.Map;
26		import java.util.Set;
27
28		/**
29		* Data structure to hold and manipulate a multiple sequence alignment
30		*/
		- Uncovered Elements: 0 (0) Complexity: 0 Complexity Density: -
31		public interface AlignmentI extends AnnotatedCollectionI
32		{
33		/**
34		* Calculates the number of sequences in an alignment, excluding hidden
35		* sequences
36		*
37		* @return Number of sequences in alignment
38		*/
39		int getHeight();
40
41		/**
42		* Calculates the number of sequences in an alignment, including hidden
43		* sequences
44		*
45		* @return Number of sequences in alignment
46		*/
47		int getAbsoluteHeight();
48
49		/**
50		*
51		* Calculates the maximum width of the alignment, including gaps.
52		*
53		* @return Greatest sequence length within alignment, or -1 if no sequences
54		* present
55		*/
56		@Override
57		int getWidth();
58
59		/**
60		* Calculates if this set of sequences (visible and invisible) are all the
61		* same length
62		*
63		* @return true if all sequences in alignment are the same length
64		*/
65		boolean isAligned();
66
67		/**
68		* Calculates if this set of sequences is all the same length
69		*
70		* @param includeHidden
71		* optionally exclude hidden sequences from test
72		* @return true if all (or just visible) sequences are the same length
73		*/
74		boolean isAligned(boolean includeHidden);
75
76		/**
77		* Answers if the sequence at alignmentIndex is hidden
78		*
79		* @param alignmentIndex
80		* the index to check
81		* @return true if the sequence is hidden
82		*/
83		boolean isHidden(int alignmentIndex);
84
85		/**
86		* Gets sequences as a Synchronized collection
87		*
88		* @return All sequences in alignment.
89		*/
90		@Override
91		List<SequenceI> getSequences();
92
93		/**
94		* Gets sequences as a SequenceI[]
95		*
96		* @return All sequences in alignment.
97		*/
98		SequenceI[] getSequencesArray();
99
100		/**
101		* Find a specific sequence in this alignment.
102		*
103		* @param i
104		* Index of required sequence.
105		*
106		* @return SequenceI at given index.
107		*/
108		SequenceI getSequenceAt(int i);
109
110		/**
111		* Find a specific sequence in this alignment.
112		*
113		* @param i
114		* Index of required sequence in full alignment, i.e. if all columns
115		* were visible
116		*
117		* @return SequenceI at given index.
118		*/
119		SequenceI getSequenceAtAbsoluteIndex(int i);
120
121		/**
122		* Returns a map of lists of sequences keyed by sequence name.
123		*
124		* @return
125		*/
126		Map<String, List<SequenceI>> getSequencesByName();
127
128		/**
129		* Add a new sequence to this alignment.
130		*
131		* @param seq
132		* New sequence will be added at end of alignment.
133		*/
134		void addSequence(SequenceI seq);
135
136		/**
137		* Used to set a particular index of the alignment with the given sequence.
138		*
139		* @param i
140		* Index of sequence to be updated. if i>length, sequence will be
141		* added to end, with no intervening positions.
142		* @param seq
143		* New sequence to be inserted. The existing sequence at position i
144		* will be replaced.
145		* @return existing sequence (or null if i>current length)
146		*/
147		SequenceI replaceSequenceAt(int i, SequenceI seq);
148
149		/**
150		* Deletes a sequence from the alignment. Updates hidden sequences to account
151		* for the removed sequence. Do NOT use this method to delete sequences which
152		* are just hidden.
153		*
154		* @param s
155		* Sequence to be deleted.
156		*/
157		void deleteSequence(SequenceI s);
158
159		/**
160		* Deletes a sequence from the alignment. Updates hidden sequences to account
161		* for the removed sequence. Do NOT use this method to delete sequences which
162		* are just hidden.
163		*
164		* @param i
165		* Index of sequence to be deleted.
166		*/
167		void deleteSequence(int i);
168
169		/**
170		* Deletes a sequence in the alignment which has been hidden.
171		*
172		* @param i
173		* Index of sequence to be deleted
174		*/
175		void deleteHiddenSequence(int i);
176
177		/**
178		* Finds sequence in alignment using sequence name as query.
179		*
180		* @param name
181		* Id of sequence to search for.
182		*
183		* @return Sequence matching query, if found. If not found returns null.
184		*/
185		SequenceI findName(String name);
186
187		SequenceI[] findSequenceMatch(String name);
188
189		/**
190		* Finds index of a given sequence in the alignment.
191		*
192		* @param s
193		* Sequence to look for.
194		*
195		* @return Index of sequence within the alignment or -1 if not found
196		*/
197		int findIndex(SequenceI s);
198
199		/**
200		* Returns the first group (in the order in which groups were added) that
201		* includes the given sequence instance and aligned position (base 0), or null
202		* if none found
203		*
204		* @param seq
205		* - must be contained in the alignment (not a dataset sequence)
206		* @param position
207		*
208		* @return
209		*/
210		SequenceGroup findGroup(SequenceI seq, int position);
211
212		/**
213		* Finds all groups that a given sequence is part of.
214		*
215		* @param s
216		* Sequence in alignment.
217		*
218		* @return All groups containing given sequence.
219		*/
220		SequenceGroup[] findAllGroups(SequenceI s);
221
222		/**
223		* Adds a new SequenceGroup to this alignment.
224		*
225		* @param sg
226		* New group to be added.
227		*/
228		void addGroup(SequenceGroup sg);
229
230		/**
231		* Deletes a specific SequenceGroup
232		*
233		* @param g
234		* Group will be deleted from alignment.
235		*/
236		void deleteGroup(SequenceGroup g);
237
238		/**
239		* Get all the groups associated with this alignment.
240		*
241		* @return All groups as a list.
242		*/
243		List<SequenceGroup> getGroups();
244
245		/**
246		* Deletes all groups from this alignment.
247		*/
248		void deleteAllGroups();
249
250		/**
251		* Adds a new AlignmentAnnotation to this alignment
252		*
253		* @note Care should be taken to ensure that annotation is at least as wide as
254		* the longest sequence in the alignment for rendering purposes.
255		*/
256		void addAnnotation(AlignmentAnnotation aa);
257
258		/**
259		* moves annotation to a specified index in alignment annotation display stack
260		*
261		* @param aa
262		* the annotation object to be moved
263		* @param index
264		* the destination position
265		*/
266		void setAnnotationIndex(AlignmentAnnotation aa, int index);
267
268		/**
269		* Delete all annotations, including auto-calculated if the flag is set true.
270		* Returns true if at least one annotation was deleted, else false.
271		*
272		* @param includingAutoCalculated
273		* @return
274		*/
275		boolean deleteAllAnnotations(boolean includingAutoCalculated);
276
277		/**
278		* Deletes a specific AlignmentAnnotation from the alignment, and removes its
279		* reference from any SequenceI or SequenceGroup object's annotation if and
280		* only if aa is contained within the alignment's annotation vector.
281		* Otherwise, it will do nothing.
282		*
283		* @param aa
284		* the annotation to delete
285		* @return true if annotation was deleted from this alignment.
286		*/
287		boolean deleteAnnotation(AlignmentAnnotation aa);
288
289		/**
290		* Deletes a specific AlignmentAnnotation from the alignment, and optionally
291		* removes any reference from any SequenceI or SequenceGroup object's
292		* annotation if and only if aa is contained within the alignment's annotation
293		* vector. Otherwise, it will do nothing.
294		*
295		* @param aa
296		* the annotation to delete
297		* @param unhook
298		* flag indicating if any references should be removed from
299		* annotation - use this if you intend to add the annotation back
300		* into the alignment
301		* @return true if annotation was deleted from this alignment.
302		*/
303		boolean deleteAnnotation(AlignmentAnnotation aa, boolean unhook);
304
305		/**
306		* Get the annotation associated with this alignment (this can be null if no
307		* annotation has ever been created on the alignment)
308		*
309		* @return array of AlignmentAnnotation objects
310		*/
311		@Override
312		AlignmentAnnotation[] getAlignmentAnnotation();
313
314		/**
315		* Change the gap character used in this alignment to 'gc'
316		*
317		* @param gc
318		* the new gap character.
319		*/
320		void setGapCharacter(char gc);
321
322		/**
323		* Get the gap character used in this alignment
324		*
325		* @return gap character
326		*/
327		char getGapCharacter();
328
329		/**
330		* Test if alignment contains RNA structure
331		*
332		* @return true if RNA structure AligmnentAnnotation was added to alignment
333		*/
334		boolean hasRNAStructure();
335
336		/**
337		* Get the associated dataset for the alignment.
338		*
339		* @return Alignment containing dataset sequences or null of this is a
340		* dataset.
341		*/
342		AlignmentI getDataset();
343
344		/**
345		* Set the associated dataset for the alignment, or create one.
346		*
347		* @param dataset
348		* The dataset alignment or null to construct one.
349		*/
350		void setDataset(AlignmentI dataset);
351
352		/**
353		* pads sequences with gaps (to ensure the set looks like an alignment)
354		*
355		* @return boolean true if alignment was modified
356		*/
357		boolean padGaps();
358
359		HiddenSequences getHiddenSequences();
360
361		HiddenColumns getHiddenColumns();
362
363		/**
364		* Compact representation of alignment
365		*
366		* @return CigarArray
367		*/
368		CigarArray getCompactAlignment();
369
370		/**
371		* Set an arbitrary key value pair for an alignment. Note: both key and value
372		* objects should return a meaningful, human readable response to .toString()
373		*
374		* @param key
375		* @param value
376		*/
377		void setProperty(Object key, Object value);
378
379		/**
380		* Get a named property from the alignment.
381		*
382		* @param key
383		* @return value of property
384		*/
385		Object getProperty(Object key);
386
387		/**
388		* Get the property hashtable.
389		*
390		* @return hashtable of alignment properties (or null if none are defined)
391		*/
392		Hashtable getProperties();
393
394		/**
395		* add a reference to a frame of aligned codons for this alignment
396		*
397		* @param codons
398		*/
399		void addCodonFrame(AlignedCodonFrame codons);
400
401		/**
402		* remove a particular codon frame reference from this alignment
403		*
404		* @param codons
405		* @return true if codon frame was removed.
406		*/
407		boolean removeCodonFrame(AlignedCodonFrame codons);
408
409		/**
410		* get all codon frames associated with this alignment
411		*
412		* @return
413		*/
414		List<AlignedCodonFrame> getCodonFrames();
415
416		/**
417		* Set the codon frame mappings (replacing any existing list).
418		*/
419		void setCodonFrames(List<AlignedCodonFrame> acfs);
420
421		/**
422		* get codon frames involving sequenceI
423		*/
424		List<AlignedCodonFrame> getCodonFrame(SequenceI seq);
425
426		/**
427		* find sequence with given name in alignment
428		*
429		* @param token
430		* name to find
431		* @param b
432		* true implies that case insensitive matching will <em>also</em> be
433		* tried
434		* @return matched sequence or null
435		*/
436		SequenceI findName(String token, boolean b);
437
438		/**
439		* find next sequence with given name in alignment starting after a given
440		* sequence
441		*
442		* @param startAfter
443		* the sequence after which the search will be started (usually the
444		* result of the last call to findName)
445		* @param token
446		* name to find
447		* @param b
448		* true implies that case insensitive matching will <em>also</em> be
449		* tried
450		* @return matched sequence or null
451		*/
452		SequenceI findName(SequenceI startAfter, String token, boolean b);
453
454		/**
455		* find first sequence in alignment which is involved in the given search
456		* result object
457		*
458		* @param results
459		* @return -1 or index of sequence in alignment
460		*/
461		int findIndex(SearchResultsI results);
462
463		/**
464		* append sequences and annotation from another alignment object to this one.
465		* Note: this is a straight transfer of object references, and may result in
466		* toappend's dependent data being transformed to fit the alignment (changing
467		* gap characters, etc...). If you are uncertain, use the copy Alignment copy
468		* constructor to create a new version which can be appended without side
469		* effect.
470		*
471		* @param toappend
472		* - the alignment to be appended.
473		*/
474		void append(AlignmentI toappend);
475
476		/**
477		* Justify the sequences to the left or right by deleting and inserting gaps
478		* before the initial residue or after the terminal residue
479		*
480		* @param right
481		* true if alignment padded to right, false to justify to left
482		* @return true if alignment was changed TODO: return undo object
483		*/
484		boolean justify(boolean right);
485
486		/**
487		* add given annotation row at given position (0 is start, -1 is end)
488		*
489		* @param consensus
490		* @param i
491		*/
492		void addAnnotation(AlignmentAnnotation consensus, int i);
493
494		/**
495		* search for or create a specific annotation row on the alignment
496		*
497		* @param name
498		* name for annotation (must match)
499		* @param calcId
500		* calcId for the annotation (null or must match)
501		* @param autoCalc
502		* - value of autocalc flag for the annotation
503		* @param seqRef
504		* - null or specific sequence reference
505		* @param groupRef
506		* - null or specific group reference
507		* @param method
508		* - CalcId for the annotation (must match)
509		*
510		* @return existing annotation matching the given attributes
511		*/
512		AlignmentAnnotation findOrCreateAnnotation(String name, String calcId,
513		boolean autoCalc, SequenceI seqRef, SequenceGroup groupRef);
514
515		/**
516		* move the given group up or down in the alignment by the given number of
517		* rows. Implementor assumes given group is already present on alignment - no
518		* recalculations are triggered.
519		*
520		* @param sg
521		* @param map
522		* @param up
523		* @param i
524		*/
525		void moveSelectedSequencesByOne(SequenceGroup sg,
526		Map<SequenceI, SequenceCollectionI> map, boolean up);
527
528		/**
529		* validate annotation after an edit and update any alignment state flags
530		* accordingly
531		*
532		* @param alignmentAnnotation
533		*/
534		void validateAnnotation(AlignmentAnnotation alignmentAnnotation);
535
536		/**
537		* Align this alignment the same as the given one. If both of the same type
538		* (nucleotide/protein) then align both identically. If this is nucleotide and
539		* the other is protein, make 3 gaps for each gap in the protein sequences. If
540		* this is protein and the other is nucleotide, insert a gap for each 3 gaps
541		* (or part thereof) between nucleotide bases. Returns the number of mapped
542		* sequences that were realigned .
543		*
544		* @param al
545		* @return
546		*/
547		int alignAs(AlignmentI al);
548
549		/**
550		* Returns the set of distinct sequence names in the alignment.
551		*
552		* @return
553		*/
554		Set<String> getSequenceNames();
555
556		/**
557		* Checks if the alignment has at least one sequence with one non-gaped
558		* residue
559		*
560		* @return
561		*/
562		public boolean hasValidSequence();
563
564		/**
565		* Update any mappings to 'virtual' sequences to compatible real ones, if
566		* present in the added sequences. Returns a count of mappings updated.
567		*
568		* @param seqs
569		* @return
570		*/
571		int realiseMappings(List<SequenceI> seqs);
572
573		/**
574		* Returns the first AlignedCodonFrame that has a mapping between the given
575		* dataset sequences
576		*
577		* @param mapFrom
578		* @param mapTo
579		* @return
580		*/
581		AlignedCodonFrame getMapping(SequenceI mapFrom, SequenceI mapTo);
582
583		/**
584		* Set the hidden columns collection on the alignment
585		*
586		* @param cols
587		*/
588		public void setHiddenColumns(HiddenColumns cols);
589
590		/**
591		* Set the first sequence as representative and hide its insertions. Typically
592		* used when loading JPred files.
593		*/
594		public void setupJPredAlignment();
595
596		/**
597		* Add gaps into the sequences aligned to profileseq under the given
598		* AlignmentView
599		*
600		* @param profileseq
601		* sequence in al which sequences are aligned to
602		* @param input
603		* alignment view where sequence corresponding to profileseq is first
604		* entry
605		* @return new HiddenColumns for new alignment view, with insertions into
606		* profileseq marked as hidden.
607		*/
608		public HiddenColumns propagateInsertions(SequenceI profileseq,
609		AlignmentView input);
610
611		}