info.bioinfweb.libralign.model.tokenset

Interface TokenSet<T>

Type Parameters:

T - the type of sequence elements (tokens) used in the sequences of an AlignmentArea

All Superinterfaces:

java.lang.Cloneable, java.util.Collection<T>, java.lang.Iterable<T>, java.util.Set<T>

All Known Implementing Classes:

AbstractContinuousSet, AbstractTokenSet, BioJava3TokenSet, CharacterTokenSet, DefaultTokenSet, DoubleTokenSet, FloatTokenSet

public interface TokenSet<T>
extends java.util.Set<T>, java.lang.Cloneable

This interface should be implemented by all classes specifying a set of tokens (sequence elements, e.g. nucleotides) that can be aligned in an AlignmentArea and are provided by an implementation of AlignmentModel.

Implementing classes define a set of valid tokens that may be contained in an alignment and define an optional keyboard shortcut a user of LibrAlign can use to insert the according token into an alignment.

Note that implementations may also represent a set of continuous values. In this case the implementation should return true for #isContinuous(), null for Set.iterator(), Integer.MAX_VALUE for Set.size() and false for Set.isEmpty(). The optional add and remove operations may throw UnsupportedOperationExceptions.

Since:

0.1.0

Author:

Ben Stöver

Method Summary

Modifier and Type	Method and Description
TokenSet<T>	clone() Returns a deep copy of this instance.
java.lang.String	descriptionByToken(T token) An description of the specified token (e.g.
T	getGapToken() Returns the default object that represents a gap in this token set.
CharacterSymbolMeaning	getMeaning(T token) Returns the meaning of the specified symbol.
T	getMissingInformationToken() Returns the default object that represents an unknown position in this token set.
CharacterSymbolType	getSymbolType(T token) Returns the type of the specified token (symbol).
CharacterStateSetType	getType() Determines the type of tokens that are defined by this instance.
boolean	isGapToken(T token) Tests if the specified token represents a gap.
boolean	isMissingInformationToken(T token) Tests if the specified token represents an unknown position (usually '?').
boolean	isSpaceForGap() Determines whether tokenByKeyStroke(KeyStroke) shall return the gap token, if the space bar is pressed, even if that key stroke is not associated with that token.
int	maxRepresentationLength() Calculates the maximal length of a representation returned by representationByToken(Object) of all tokens contained in this set.
java.lang.String	representationByToken(T token) Returns the representation string of the specified token that shall be displayed in an AlignmentArea or written into an alignment file.
boolean	representationLengthEqual() Checks if all representation strings returned by representationByToken(Object) have the same length.
void	setSpaceForGap(boolean spaceForGap) Allows to specify whether tokenByKeyStroke(KeyStroke) shall return the gap token, if the space bar is pressed, even if that key stroke is not associated with that token.
T	tokenByKeyStroke(javax.swing.KeyStroke key) Returns the token from this set that is associated with the specified key stroke.
T	tokenByRepresentation(java.lang.String representation) Returns the token associated with the specified string representation used to display the token in an AlignmentArea or an alignment file.

Methods inherited from interface java.util.Set

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, spliterator, toArray, toArray

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream

Methods inherited from interface java.lang.Iterable

forEach

Method Detail

tokenByKeyStroke

T tokenByKeyStroke(javax.swing.KeyStroke key)

Returns the token from this set that is associated with the specified key stroke. This key can be pressed to insert the specified token into an AlignmentArea.

Note that the key character is only used by AlignmentArea if it does not collide with a default keyboard action. (Usually the key character can be any lower or upper case letter or digit.)

Parameters:

key - the key stroke (key code and shift mask) the user can press to insert the returned token into an AlignmentArea

Returns:

the associated token (sequence element) or null if none is defined

representationByToken

java.lang.String representationByToken(T token)

Returns the representation string of the specified token that shall be displayed in an AlignmentArea or written into an alignment file.

Note that some CharSequenceAdapters and StringAdapters only use the first character of the returned string to represent a token.

Parameters:

token - the token associated with the representation

Returns:

a string which is at least one character long an empty string if no token in this set has the specified representation

tokenByRepresentation

T tokenByRepresentation(java.lang.String representation)

Returns the token associated with the specified string representation used to display the token in an AlignmentArea or an alignment file.

Parameters:

representation - the string representation of the token

Returns:

the according token or null if none is defined

maxRepresentationLength

int maxRepresentationLength()

Calculates the maximal length of a representation returned by representationByToken(Object) of all tokens contained in this set.

Returns:

a value >= 1 (since all representations must be at least one character long)

representationLengthEqual

boolean representationLengthEqual()

Checks if all representation strings returned by representationByToken(Object) have the same length.

Returns:

true if all lengths are equal, false otherwise

descriptionByToken

java.lang.String descriptionByToken(T token)

An description of the specified token (e.g. the full name of the compound like "Adenine").

Parameters:

token - the token that shall be described

Returns:

a string containing no line breaks

getType

CharacterStateSetType getType()

Determines the type of tokens that are defined by this instance.

Returns:

the token set type

isGapToken

boolean isGapToken(T token)

Tests if the specified token represents a gap. This method is e.g. used by data areas to determine the positions of gaps.

Note that it's legal to have multiple tokens to be considered as gaps, but one of them must be defined as the default gap tokens. When alignments are written to files (e.g. using JPhyloIO), some formats may accept only one of these tokens as a gap and the others may be represented as additional character states.

Parameters:

token - the token to be tested

Returns:

true if the specified token is recognized as a gap, false otherwise.

getGapToken

T getGapToken()

Returns the default object that represents a gap in this token set.

Returns:

the according gap object (Implementations may create a new instance with every call of this method or always return the same instance. In general gap objects should not have any mutable object specific properties to avoid problems if the same instance if located at multiple positions in an alignment.)

isSpaceForGap

boolean isSpaceForGap()

Determines whether tokenByKeyStroke(KeyStroke) shall return the gap token, if the space bar is pressed, even if that key stroke is not associated with that token.

Returns:

true if the gap token shall always be returned, false otherwise.

setSpaceForGap

void setSpaceForGap(boolean spaceForGap)

Allows to specify whether tokenByKeyStroke(KeyStroke) shall return the gap token, if the space bar is pressed, even if that key stroke is not associated with that token.

Parameters:

spaceForGap - Specify true here, if the gap token shall always be returned, false otherwise.

isMissingInformationToken

boolean isMissingInformationToken(T token)

Tests if the specified token represents an unknown position (usually '?'). This method is e.g. used by data areas to determine the positions of gaps.

Note that it's legal to have multiple tokens to be considered as unknown symbols, but one of them must be defined as the default. When alignments are written to files, some formats may accept only one

Parameters:

token - the token to be tested

Returns:

true if the specified token is recognized as an unknown position, false otherwise.

getMissingInformationToken

T getMissingInformationToken()

Returns the default object that represents an unknown position in this token set.

Returns:

the according object (Implementations may create a new instance with every call of this method or always return the same instance. In general objects should not have any mutable object specific properties to avoid problems if the same instance if located at multiple positions in an alignment.)

getMeaning

CharacterSymbolMeaning getMeaning(T token)

Returns the meaning of the specified symbol. (Note that LibrAlign models will usually not contain match tokens directly).

Parameters:

token - the token to determine the meaning from

Returns:

the meaning of the specified token

getSymbolType

CharacterSymbolType getSymbolType(T token)

Returns the type of the specified token (symbol). Symbols can either represent an atomic token or a polymorphic state or a set of tokens, if the the position is uncertain.

Parameters:

token - the symbol to be tested

Returns:

the type of the specified symbol

clone

TokenSet<T> clone()

Returns a deep copy of this instance. Implementing this method is important when creating custom implementations of this interface, because other classes in LibrAlign use this method internally.

Returns:

an identical token set