Package com.biomatters.geneious.publicapi.documents.sequence

Class SequenceAnnotationInterval

  • public final class SequenceAnnotationInterval
extends java.lang.Object
    Immutable pair of integers with a direction, representing a directed range in the sequence annotation. Both ends are included in the range except in the special case of a 0 length interval between 2 bases (see isBetweenBases())

    Values are usually in range from 1 to n (sequence length) but may extend outside the sequence range in cases where the partial sequence it is on doesn't cover the full length of the annotation.

    • Constructor Detail

      • SequenceAnnotationInterval

        public SequenceAnnotationInterval​(java.lang.String text)
                           throws java.lang.NumberFormatException
        constructs interval from the string representation of the form "[...]n,nnn D m,mmm[...]" where "n,nnn" is an integer with commas every three digits and "D" is a valid direction (see SequenceAnnotationInterval.Direction.toArrowString()). This is the format returned from toString()
        Parameters:
        text - A value of the format returned by toString()
        Throws:
        java.lang.NumberFormatException - if the value isn't formatted correctly. This should only happen if text is not a value of the format returned by toString().

      • SequenceAnnotationInterval

        public SequenceAnnotationInterval​(Interval interval)
        Creates a SequenceAnnotationInterval (which uses 1-based inclusive max co-ordinates) from an interval (which uses 0-based exclusive max co-ordinates)
        Parameters:
        interval - the interval to create an equivalent SequenceAnnotationInterval to.

      • SequenceAnnotationInterval

        public SequenceAnnotationInterval​(int from,
                                  int to)
        Backwards compatibility constructor for an interval that starts at index from (inclusive) and ends at index to (inclusive). The direction is leftToRight if from < end, and rightToLeft if from > end. For from==end, no guarantee is made what the direction of the resulting interval will be.
        Parameters:
        from - The start of the interval (inclusive), usually in range 1 to sequence length inclusive but it may extend outside this range in cases where the partial sequence it is on doesn't cover the full length of the annotation.
        to - The end of the interval (inclusive), usually in range 1 to sequence length inclusive but it may extend outside this range in cases where the partial sequence it is on doesn't cover the full length of the annotation.

      • SequenceAnnotationInterval

        public SequenceAnnotationInterval​(int minIndex,
                                  int maxIndex,
                                  SequenceAnnotationInterval.Direction direction)
        Parameters:
        minIndex - The minimum index (inclusive) spanned by this interval, usually in range 1 to sequence length inclusive but it may extend outside this range in cases where the partial sequence it is on doesn't cover the full length of the annotation.
        maxIndex - The maximum index (inclusive) spanned by this interval, usually in range 1 to sequence length inclusive but it may extend outside this range in cases where the partial sequence it is on doesn't cover the full length of the annotation.
        direction - The direction of the interval
        Throws:
        java.lang.IllegalArgumentException - if maxIndex < minIndex - 1. The special case of maxIndex==minIndex-1 represents an annotation the sits between the bases maxIndex and minIndex. As of 2008-2-29, Geneious has not been checked to see if all modules handle this situation correctly, so it is generally not a good idea to use these special annotations yet.
        java.lang.NullPointerException - if direction is null
        See Also:
        SequenceAnnotationInterval.Direction

      • SequenceAnnotationInterval

        public SequenceAnnotationInterval​(int minIndex,
                                  int maxIndex,
                                  SequenceAnnotationInterval.Direction direction,
                                  boolean isTruncatedAtMinimumIndex,
                                  boolean isTruncatedAtMaximumIndex)
        Main constructor.
        Parameters:
        minIndex - The minimum index (inclusive) spanned by this interval, indexed from 1
        maxIndex - The maximum index (inclusive) spanned by this interval, indexed from 1
        direction - The direction of the interval
        isTruncatedAtMinimumIndex - true to indicate that the interval is incomplete and really begins before minIndex.
        isTruncatedAtMaximumIndex - true to indicate that the interval is incomplete and really finishes after maxIndex.
        Throws:
        java.lang.IllegalArgumentException - if maxIndex < minIndex - 1. The special case of maxIndex==minIndex-1 represents an annotation the sits between the bases maxIndex and minIndex. As of 2008-2-29, Geneious has not been checked to see if all modules handle this situation correctly, so it is generally not a good idea to use these special annotations yet.
        java.lang.NullPointerException - if direction is null
        See Also:
        SequenceAnnotationInterval.Direction

      • SequenceAnnotationInterval

        public SequenceAnnotationInterval​(SequenceAnnotationInterval interval)
        Construct a SequenceAnnotationInterval that is identical to the given parameter. Because SequenceAnnotationInterval is an immutable class, it can be shared safely and it is never necessary to construct a copy of the same value. Therefore, use of this constructor is discouraged.
        Parameters:
        interval - interval to create a copy from

    • Method Detail

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
        Returns:
        a string representation of the form "[...]n,nnn D m,mmm[...]" where "n,nnn" is an integer with commas every three digits and '...' is prepended or appended if the interval beings before the minimum index or ends after the maximum index and D is an arrow in the format returned by Direction.toArrowString(). If this interval is between bases (see isBetweenBases()) then the returned string will be of the form "Between 55 and 56".

      • toString

        public java.lang.String toString​(boolean showDigitSeparator)
        Parameters:
        showDigitSeparator - true to separate every 3rd digit with commas
        Returns:
        a string representation of the form "[...]n,nnn D m,mmm[...]" where "n,nnn" is an integer with commas every three digits (if showDigitSeparator is true) and '...' is prepended or appended if the interval beings before the minimum index or ends after the maximum index and D is an arrow in the format returned by Direction.toArrowString(). If this interval is between bases (see isBetweenBases()) then the returned string will be of the form "Between 55 and 56".

      • toString

        public java.lang.String toString​(boolean showDigitSeparator,
                                 boolean formatNicely)
        Parameters:
        showDigitSeparator - true to separate every 3rd digit with commas
        formatNicely - to display intervals in the reverse direction more nicely when the maximum and minimum indices are not identical. For example it would return "5->1" instead of the alternative format of "1 -< 5". Note that this nicer format is not guaranteed to be parsable by SequenceAnnotationInterval(String) because formats such as "2->1" could be interpreted as an annotation between bases 1 and 2 in older versions of Geneious.
        Returns:
        a string representation of the form "[...]n,nnn D m,mmm[...]" where "n,nnn" is an integer with commas every three digits (if showDigitSeparator is true) and '...' is prepended or appended if the interval beings before the minimum index or ends after the maximum index and D is an arrow in the format returned by Direction.toArrowString(). If this interval is between bases (see isBetweenBases()) then the returned string will be of the form "Between 55 and 56".

      • asInterval

        public Interval asInterval()
        Returns this SequenceAnnotationInterval as an Interval, which uses 0-based exclusive max co-ordinates rather than 1-based inclusive max co-ordinates used by SequenceAnnotationInterval
        Returns:
        this SequenceAnnotationInterval as an Interval

      • between

        public static SequenceAnnotationInterval between​(int min,
                                                 int max)
        Creates a zero-length SequenceAnnotationInterval between the given bases/residues with direction SequenceAnnotationInterval.Direction.none
        Parameters:
        min - base/residue this interval comes directly after
        max - base/residue this interval comes directly before
        Returns:
        a zero-length SequenceAnnotationInterval between the given bases/residues
        Throws:
        java.lang.IllegalArgumentException - if max!=min+1 or min!=max+1
        Since:
        API 4.51 (Geneious 5.5.1)
        See Also:
        isBetweenBases()

      • between

        public static SequenceAnnotationInterval between​(int min,
                                                 int max,
                                                 int gapLengthToExpandToFill)
        Creates a zero-length SequenceAnnotationInterval between the given bases/residues with direction SequenceAnnotationInterval.Direction.none such that if it appears in an alignment with a gap in this region of the given size, will expand to fill that gap.
        Parameters:
        min - base/residue this interval comes directly after
        max - base/residue this interval comes directly before
        gapLengthToExpandToFill - if this annotation appears in an alignment with a gap in this region of the given size, will expand to fill that gap.
        Returns:
        a zero-length SequenceAnnotationInterval between the given bases/residues
        Throws:
        java.lang.IllegalArgumentException - if max!=min+1 or min!=max+1
        Since:
        API 4.910 (Geneious 9.1.0)
        See Also:
        isBetweenBases()

      • getReverse

        public SequenceAnnotationInterval getReverse()
        Returns the reverse of this interval, covering the same sequence residues but having the opposite direction (as defined by SequenceAnnotationInterval.Direction.reverse()). Truncation status of the interval ends are not changed. For example if this interval is truncated at its maximum index, the returned interval is also truncated at its maximum index.
        Returns:
        the reverse of this interval
        Since:
        API 4.50 (Geneious 5.5.0)
        See Also:
        getReverseComplement(int)

      • getReverseComplement

        public SequenceAnnotationInterval getReverseComplement​(int sequenceLength)
        Returns the reverse complement of this interval, suitable for adding to a sequence that is the reverse complement of the sequence this interval is on. Truncation status of the maximum and minimum indices are swapped. For example if this interval is truncated at its maximum index, the returned interval is truncated at its minimum index.
        Parameters:
        sequenceLength - the length of the sequence this interval is on
        Returns:
        the reverse complement of this interval
        Since:
        API 4.201900 (Geneious 2019.0.0)
        See Also:
        getReverse()

      • getFrom

        public int getFrom()
        Start position of annotation. The start position will be greater than getTo() for reverse directed annotations. See also getMinimumIndex() and getMaximumIndex(). The start position is usually (but not always) in the range 1 to the length of the sequence inclusive. If the value is outside this range, the annotation is considered to start before (or after) the end of the sequence.

        In the case of circular sequences (see SequenceDocument.isCircular()), any multiple of the sequence length may be added (or subtracted) from the position, as long as at least one of getMinimumIndex(), getMaximumIndex() is in the range [1, sequenceLength]. As this can still allow two different encodings of the range when it spans the end of the sequence, the recommended encoding is the one where getMinimumIndex() is in the range [1, sequenceLength]. For example, if the sequence length of a circular sequence is 10, an annotation from 5 to 13 goes from residue 5 to residue 3. An annotation from 7 to 22 goes around the sequence 1.5 times starting on residue 7 and finishing on residue 2.

        Returns:
        start position of the annotation
        See Also:
        getTo(), getMinimumIndex(), getMaximumIndex()

      • getTo

        public int getTo()
        End position of annotation. This position will be less than getFrom() position for reverse directed annotations. See also getMinimumIndex() and getMaximumIndex(). The to position is usually (but not always) in the range 1 to the length of the sequence inclusive. If the value is outside this range, the annotation is considered to start before (or after) the end of the sequence.

        See getFrom() for how circular sequences are handled

        Returns:
        end position of the annotation
        See Also:
        getFrom(), getMinimumIndex(), getMaximumIndex()

      • getMinimumIndex

        public int getMinimumIndex()
        The smallest sequence index covered by this interval, equivalent to Math.min(getFrom(), getTo()). Usually in range 1 to sequence length. If the value is outside this range, the annotation is considered to start before (or after) the end of the sequence.
        Returns:
        The smallest sequence index covered by this interval, equivalent to Math.min(getFrom(), getTo()).

      • getMaximumIndex

        public int getMaximumIndex()
        The largest sequence index covered by this interval, equivalent to Math.max(getFrom(), getTo()). Usually in the range 1 to sequence length. If the value is outside this range, the annotation is considered to start before (or after) the end of the sequence.
        Returns:
        The largest sequence index covered by this interval, equivalent to Math.max(getFrom(), getTo()).

      • isTruncatedAtMinimumIndex

        public boolean isTruncatedAtMinimumIndex()
        Checks whether the interval is incomplete and really beings before the minimum index.
        Returns:
        true to indicate that the interval is incomplete and really beings before the minimum index.

      • isTruncatedAtMaximumIndex

        public boolean isTruncatedAtMaximumIndex()
        Checks whether the interval is incomplete and really finishes after the maximum index.
        Returns:
        true to indicate that the interval is incomplete and really finishes after the maximum index.

      • contains

        public boolean contains​(int index)
        Checks whether this interval includes the residue at the specified index. If the sequence in question may potentially be a ciruclar sequence (see SequenceDocument.isCircular()) then containsOnPotentiallyCircularSequence(int, int) should be used instead.
        Parameters:
        index - An index in a sequence (In range 1 to sequence length.)
        Returns:
        true if this interval contains the specified index. i.e. minIndex <= index && index <= maxIndex

      • containsOnPotentiallyCircularSequence

        public boolean containsOnPotentiallyCircularSequence​(int index,
                                                     int sequenceLengthIfCircular)
        Checks whether this interval includes the residue at the specified index in a potentially circular sequence.
        Parameters:
        index - An index in a sequence (In range 1 to sequence length.)
        sequenceLengthIfCircular - if the sequence this annotation corresponds to is circular, then this should be >0 to indicate the length of a circular sequence
        Returns:
        true if this interval contains the specified index. i.e. minIndex <= index && index <= maxIndex
        Since:
        API 4.700 (Geneious 7.0.0)

      • contains

        public boolean contains​(SequenceAnnotationInterval anotherInterval)
        Determines if this interval entirely covers another interval. Two intervals with the same boundaries are considered to contain each other.

        Intervals between two bases (the special case where getMaximumIndex()==getMinimumIndex()-1) can only contain an identical interval. They are contained by an interval if they are within or on the edge of it.

        This method does not handle annotations on a circular sequence (where Intervals that extend outside the range "1->sequence length" inclusive are considered to wrap around to the other end of the sequence)

        Parameters:
        anotherInterval - another interval to check containment of
        Returns:
        true if this interval entirely contains the other interval.
        Since:
        Geneious API 4.40 (Geneious 5.4.0)

      • intersectsWith

        public boolean intersectsWith​(SequenceAnnotationInterval anotherInterval)
        Determines if this interval intersects with another interval. i.e. they have at least 1 residue in common. Two intervals are also considered to intersect if one interval entirely covers the other interval.
        Parameters:
        anotherInterval - another interval to check intersection with
        Returns:
        true if this interval intersects with the other interval.

      • intersectsWithInCircularSequence

        public boolean intersectsWithInCircularSequence​(SequenceAnnotationInterval anotherInterval,
                                                int circularSequenceLength)
        Determines if this interval intersects with another interval in a circular sequence. i.e. they have at least 1 residue in common. Intervals that extend outside the range "1->sequence length" inclusive are considered to wrap around to the other end of the sequence.

        . Two intervals are also considered to intersect if one interval entirely covers the other interval.

        Parameters:
        anotherInterval - another interval to check intersection with
        circularSequenceLength - the length of the circular sequence on which both intervals are present.
        Returns:
        true if this interval intersects with the other interval.

      • intersectsWith

        public boolean intersectsWith​(int minimumIndexOfOtherInterval,
                              int maximumIndexOfOtherIntervalInclusive)
        Equivalent to calling intersectsWith(new SequenceAnnotationInterval(minimumIndexOfOtherInterval, maximumIndexOfOtherIntervalInclusive))
        Parameters:
        minimumIndexOfOtherInterval - the 1-based minimum index of another interval to test for intersection with
        maximumIndexOfOtherIntervalInclusive - the 1-based maximum index (inclusive) of another interval to test for intersection with
        Returns:
        true if this interval intersects with the other interval.

      • intersectsWithInCircularSequence

        public boolean intersectsWithInCircularSequence​(int minimumIndexOfOtherInterval,
                                                int maximumIndexOfOtherIntervalInclusive,
                                                int circularSequenceLength)
        Equivalent to calling intersectsWithInCircularSequence(new SequenceAnnotationInterval(minimumIndexOfOtherInterval, maximumIndexOfOtherIntervalInclusive),circularSequenceLength)
        Parameters:
        minimumIndexOfOtherInterval - the 1-based minimum index of another interval to test for intersection with
        maximumIndexOfOtherIntervalInclusive - the 1-based maximum index (inclusive) of another interval to test for intersection with
        circularSequenceLength - the length of the circular sequence on which both intervals are present.
        Returns:
        true if this interval intersects with the other interval.

      • isBetweenBases

        public boolean isBetweenBases()
        Returns true if this interval represents a position between 2 bases, which is represented by the special case where getMaximumIndex()==getMinimumIndex()-1. The bases it is between are getMaximumIndex() (lower of the two) and getMinimumIndex() (upper of the two), both 1-based
        Returns:
        true if this interval represents a position between 2 bases, which is represented by the special case where getMaximumIndex()==getMinimumIndex()-1. The bases it is between are getMaximumIndex() (lower of the two) and getMinimumIndex() (upper of the two), both 1-based
        See Also:
        between(int, int)

      • getLength

        public int getLength()
        The length (number of residues and gaps) of this interval.
        Returns:
        The length of this interval, 1 + getMaximumIndex() - getMinimumIndex()

      • merge

        public static java.util.List<SequenceAnnotationInterval> merge​(java.util.List<SequenceAnnotationInterval> _intervals,
                                                               boolean mergeIntervalsWithDifferentDirections)
        Merges a list of intervals, i.e. replaces sets of overlapping or (conditionally) directly adjacent intervals with a single interval. If merging intervals with different directions, to determine the direction of the resulting interval, the directions occurring in the overlapping set are considered in the order that they have been defined in the enum Direction. The first direction to have occurred is taken. This implies: - If all intervals in the overlapping set have the same direction, this direction is taken. - If there is a disagreement, preference is given to the direction that is the smallest according to Direction's natural order. The exact number of intervals for each direction does not matter; i.e. 10x right-to-left and 1x left-to-right yields left-to-right.

        Empty intervals are preserved (unless they are contained within other intervals).

        The returned merged intervals will not be flagged as either isTruncatedAtMinimumIndex() or isTruncatedAtMaximumIndex() even if the original intervals were flagged in this way.

        Parameters:
        _intervals - the intervals to merge
        mergeIntervalsWithDifferentDirections - true to allow merging of intervals in different directions. False to merge them anyway and use one of the directions as described above.
        Returns:
        Merged set of intervals, ordered from left to right (increasing coordinates)

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • getResidues

        @Deprecated
public java.lang.CharSequence getResidues​(java.lang.CharSequence residues,
                                          int maximumResiduesToReturn,
                                          boolean isNucleotideSequence)
        Deprecated.
        New code should use getResidues(CharSequence, int, boolean, boolean, boolean)
        Gets the residues covered by this interval for displaying to a user, truncating it with "..." on the ends if it is too long or if the interval extends outside the sequence bounds.
        Parameters:
        residues - the residues for the entire sequence.
        maximumResiduesToReturn - the maximum number of residue characters to include. Does not include the possible "..."s
        isNucleotideSequence - true if this is a nucleotide sequence. Used for deciding whether to reverse complement residues when a reverse annotation is encountered. For protein sequences, the residues displayed will always be in the forwards direction no matter what direction this interval has.
        Returns:
        the residues covered by this interval, possibly truncated and with "..." appended or prepended

      • getResidues

        public java.lang.CharSequence getResidues​(java.lang.CharSequence residues,
                                          int maximumResiduesToReturn,
                                          boolean isNucleotideSequence,
                                          boolean isRna,
                                          boolean includeDots)
        Gets the residues covered by this interval for displaying to a user,
        Parameters:
        residues - the residues for the entire sequence.
        maximumResiduesToReturn - the maximum number of residue characters to include. Does not include the possible "..."s
        isNucleotideSequence - true if this is a nucleotide sequence. Used for deciding whether to reverse complement residues when a reverse annotation is encountered. For protein sequences, the residues displayed will always be in the forwards direction no matter what direction this interval has.
        isRna - Whether this sequence is RNA. This parameter will be ignored if isNucleotideSequence is false. SequenceUtilities.isRna(CharSequence, int) can be used to provide a value for this parameter.
        includeDots - Whether to append/prepend "..." on the result ends if it is too long or if the interval extends outside the sequence bounds.
        Returns:
        the residues covered by this interval.
        Since:
        API 4.202200 (Geneious 2022.0.0)

      • offsetBy

        public SequenceAnnotationInterval offsetBy​(int offsetDistance)
        Returns a new interval offset to the right by the given distance from this interval
        Parameters:
        offsetDistance - the distance fo offset to the right
        Returns:
        a new interval offset to the right by the given distance from this interval

      • truncate

        public SequenceAnnotationInterval truncate​(int minIndex,
                                           int maxIndex)
        Truncates (clips) this interval to not extend below minIndex or above maxIndex. If this interval lies entirely outside that range null is returned.
        Parameters:
        minIndex - the 1-based minimum index
        maxIndex - the 1-base maximum index
        Returns:
        either this interval (if no truncation is necessary), a truncated interval, or null if this interval lies entirely outside the range.
        Since:
        Geneious API 4.14 (Geneious 5.1)