javagene.seq
Class Location

java.lang.Object
  javagene.seq.Location

All Implemented Interfaces:

java.lang.Comparable<Location>, java.lang.Iterable<Location>

public class Location
extends java.lang.Object
implements java.lang.Iterable<Location>, java.lang.Comparable<Location>

A location on a sequence. A location is a contiguous range of indices, with a single start and end point.

Internally, location indices are stored in Java "half-open" format: the start is the (origin 0) index of the first symbol in the range; the end is the origin 0 index of the first symbol PAST the end of the range, so that end - start == length.

Location objects, once constructed, cannot be changed. Instead, all methods return a new location. This allows the use of "method chaining" to implement a particular calculation. For example, consider the chained statement "loc.prefix( 100 ).suffix( 10 )", which first applies the prefix method to the variable named loc, and then the suffix method to the result. Together, the chained operations create a new location object of length 10 whose start is the index of the 90th symbol. Here's another example. This one returns a location object holding the coordinates of the intron between the first exon (location exon1) and the second exon (location exon2) on a sequence (seq): "seq.prefix( exon2 ).suffix( exon1 )"

About the negative (reverse) strand: The location object stores reverse strand locations as negative indices. For example, the positive strand location from index 12 to index 97 is on the opposite side as index -97 (start) to index -12 (end). Note that the larger index is always downstream from the smaller index, ie start <= end, regardless of strand. Obviously this representation makes it trivial to convert a location from one strand to the other.

Additional points regarding the use of locations on opposite strands:
(1) Opposite strand locations cannot be compared, eg isBefore() will throw an exception.
(2) Containment queries ( eg overlaps(), contains() ) also throw exceptions.
(3) The plus() method will map a location to its positive strand equivalent; use it on both args before calling, for example the intersection() method, if your code needs to be indifferent to strand.

Exceptions and how they are (typically) used:
IllegalArgumentException - the location given as a parameter is not on the same strand as the location.
IndexOutOfBoundsException - often means the operation caused the location to span the origin, ie be partially on positive and partially on negative strand.

Constructor Summary

Location(int start, int end)
Construct new location from coordinates.

Location(Location other)
Clone other location.

Method Summary

int	bioEnd() Get end index, in biocoordinates.
int	bioStart() Get start index, in biocoordinates.
char	bioStrand() Get character representation of strand.
int	compareTo(Location other) Compare the starting indices (implements Comparable.compareTo())
boolean	contains(Location other) Check if this location contains the other.
int	distance(Location other) Return distance between this location and the other location.
Location	downstream(int length) Return the adjacent location of specified length directly downstream of this location.
int	end() Get the ending index.
boolean	endsAfter(Location other) Check if this location ends after other location ends.
boolean	endsBefore(Location other) Check if this location ends before other location ends.
boolean	equals(Location other) Compare locations for equality.
static Location	fromBio(int start, int end, char strand) Create location from "biocoordinates", as in GFF file.
static Location	fromBioExt(int start, int length, char strand, int totalLength) Create a location from MAF file coordinates, which represent negative strand locations as the distance from the end of the sequence.
Location	intersection(Location other) Return the intersection, or null if no overlap.
boolean	isAfter(Location other) Check if this location is entirely after the other location (no overlap).
boolean	isBefore(Location other) Check if this location is entirely before other location (no overlap).
boolean	isNegative() Check if location is on negative strand.
boolean	isSameStrand(Location other) Check if this location is on same strand as other location.
LocIterator	iterator() Create a location iterator over this location with a window size of 1 and an increment of +1 (successive symbols from start to end).
LocIterator	iterator(int windowSize, int increment) Create a location iterator over this location, using specified window size and increment.
int	length() Get length of range.
Location	minus() Return location that is in same position on negative strand.
Location	opposite() Return location that is in same position on opposite strand.
boolean	overlaps(Location other) Check if this location and other location overlap.
double	percentOverlap(Location other) Return percent overlap of two locations.
Location	plus() Return location that is in same position on plus strand.
Location	prefix(int position) The part of this location before the specified position.
Location	prefix(Location other) The part of this location before the other location (not inclusive).
int	start() Get starting index (origin 0).
boolean	startsAfter(Location other) Check if this location starts after the other location starts.
boolean	startsBefore(Location other) Check if this location starts before other location starts.
Location	suffix(int position) The part of this location after the specified position.
Location	suffix(Location other) The part of this location after the other location (not inclusive).
java.lang.String	toString() Return a string representation of location.
Location	union(Location other) Return the union.
Location	upstream(int length) Return the adjacent location of specified length directly upstream of this location.
java.lang.Iterable<Location>	window(int windowSize, int increment) Enable a "sliding window" iteration over a location to use with Java's "for" loop construct.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Location

public Location(int start,
                int end)

Construct new location from coordinates. See package description of coordinate format.

Parameters:

start - Origin 0 index of first symbol.

end - Origin 0 index of last symbol + 1.

Throws:

java.lang.IllegalArgumentException - End is not after start, or location spans the origin

Location

public Location(Location other)

Clone other location.

Parameters:

other - The location to clone.

Method Detail

bioEnd

public int bioEnd()

Get end index, in biocoordinates.

Returns:

The origin 1 index of the final symbol in location.

bioStart

public int bioStart()

Get start index, in biocoordinates.

Returns:

The origin 1 index of the first symbol in location.

bioStrand

public char bioStrand()

Get character representation of strand.

Returns:

'+' or '-'

compareTo

public int compareTo(Location other)

Compare the starting indices (implements Comparable.compareTo())

Specified by:

compareTo in interface java.lang.Comparable<Location>

Parameters:

other - The location to compare.

Returns:

The start index of this location minus the start location of the other location.

Throws:

java.lang.IllegalArgumentException - Locations are on opposite strands.

contains

public boolean contains(Location other)

Check if this location contains the other.

Parameters:

other - The location to compare.

Returns:

True if other is entirely contained by this location.

Throws:

java.lang.IllegalArgumentException - Locations are on opposite strands.

distance

public int distance(Location other)

Return distance between this location and the other location. Distance is defined only if both locations are on same strand.

Parameters:

other - The location to compare.

Returns:

The integer distance. Returns -1 if they overlap; 0 if directly adjacent.

Throws:

java.lang.IllegalArgumentException - Locations are on opposite strands.

downstream

public Location downstream(int length)

Return the adjacent location of specified length directly downstream of this location.

Parameters:

length - The length of the downstream location.

Returns:

The downstream location.

Throws:

java.lang.IndexOutOfBoundsException - Specified length causes crossing of origin.

end

public int end()

Get the ending index.

Returns:

The index of last symbol + 1 (remember Java half-open coordinates).

endsAfter

public boolean endsAfter(Location other)

Check if this location ends after other location ends. The locations may overlap.

Parameters:

other - The location to compare.

Returns:

True if location ends after other.

Throws:

java.lang.IllegalArgumentException - Locations are on opposite strands.

endsBefore

public boolean endsBefore(Location other)

Check if this location ends before other location ends. The locations may overlap.

Parameters:

other - The location to compare.

Returns:

True if this ends before other.

Throws:

java.lang.IllegalArgumentException - Locations are on opposite strands.

equals

public boolean equals(Location other)

Compare locations for equality.

Parameters:

other - The location to compare.

Returns:

True if locations are the same.

fromBio

public static Location fromBio(int start,
                               int end,
                               char strand)

Create location from "biocoordinates", as in GFF file. In biocoordinates, the start index of a range is represented in origin 1 (ie the very first index is 1, not 0), and end= start + length - 1.

Parameters:

start - Origin 1 index of first symbol.

end - Origin 1 index of last symbol.

strand - '+' or '-' or '.' ('.' is interpreted as '+').

Returns:

Created location.

Throws:

java.lang.IllegalArgumentException - strand must be '+', '-' or '.'

fromBioExt

public static Location fromBioExt(int start,
                                  int length,
                                  char strand,
                                  int totalLength)

Create a location from MAF file coordinates, which represent negative strand locations as the distance from the end of the sequence.

Parameters:

start - Origin 1 index of first symbol.

length - Number of symbols in range.

strand - '+' or '-' or '.' ('.' is interpreted as '+').

totalLength - Total number of symbols in sequence.

Throws:

java.lang.IllegalArgumentException - Strand must be '+', '-', '.'

intersection

public Location intersection(Location other)

Return the intersection, or null if no overlap.

Parameters:

other - The location to intersect.

Returns:

The maximal location that is contained by both. Returns null if no overlap!

Throws:

java.lang.IllegalArgumentException - Locations are on opposite strands.

isAfter

public boolean isAfter(Location other)

Check if this location is entirely after the other location (no overlap).

Parameters:

other - The location to compare.

Returns:

True if this is after other.

Throws:

java.lang.IllegalArgumentException - Locations are on opposite strands.

isBefore

public boolean isBefore(Location other)

Check if this location is entirely before other location (no overlap).

Parameters:

other - The location to compare.

Returns:

True if this is before other.

Throws:

java.lang.IllegalArgumentException - Locations are on opposite strands.

isNegative

public boolean isNegative()

Check if location is on negative strand. Note that Location( 0, 0 ) is by construction defined to be on the positive strand.

Returns:

True if on negative (reverse) strand.

isSameStrand

public boolean isSameStrand(Location other)

Check if this location is on same strand as other location.

Parameters:

other - The location to compare.

Returns:

True if on same strand.

iterator

public LocIterator iterator()

Create a location iterator over this location with a window size of 1 and an increment of +1 (successive symbols from start to end).

Specified by:

iterator in interface java.lang.Iterable<Location>

Returns:

An iterator over a Location (a LocIterator object).

iterator

public LocIterator iterator(int windowSize,
                            int increment)

Create a location iterator over this location, using specified window size and increment.

Parameters:

windowSize - The number of symbols to get on each iteration.

increment - The direction and number of symbols to advance at each iteration.

Returns:

An iterator over a Location (a LocIterator object).

length

public int length()

Get length of range.

Returns:

The length of the range (end - start).

minus

public Location minus()

Return location that is in same position on negative strand. If location is already on negative strand, just return the location unchanged.

Returns:

Location on negative strand.

opposite

public Location opposite()

Return location that is in same position on opposite strand.

Returns:

Location on opposite strand.

overlaps

public boolean overlaps(Location other)

Check if this location and other location overlap.

Parameters:

other - The location to compare.

Returns:

True if they overlap.

Throws:

java.lang.IllegalArgumentException - Locations are on opposite strands.

percentOverlap

public double percentOverlap(Location other)

Return percent overlap of two locations.

Parameters:

other - The location to compare.

Returns:

100.0 * intersection(other).length() / this.length()

Throws:

java.lang.IllegalArgumentException - Locations are on opposite strands.

plus

public Location plus()

Return location that is in same position on plus strand. If location is already on plus strand, just return the location unchanged.

Returns:

Location on plus strand.

prefix

public Location prefix(int position)

The part of this location before the specified position. If position is negative, count backwards from the end.

For position >= 0, return Location( start, start + position ).
For position < 0, return Location( start, end + position ).

Parameters:

position - Where the prefix ends.

Returns:

New location from start of this location to directly before position.

Throws:

java.lang.IndexOutOfBoundsException - Specified prefix is longer than location.

prefix

public Location prefix(Location other)

The part of this location before the other location (not inclusive).

Parameters:

other - The other location.

Returns:

The part of this location before the other location.

Throws:

java.lang.IllegalArgumentException - Locations are on opposite strands.

java.lang.IndexOutOfBoundsException - This location does not contain other location.

start

public int start()

Get starting index (origin 0).

Returns:

The start index.

startsAfter

public boolean startsAfter(Location other)

Check if this location starts after the other location starts. The locations may overlap.

Parameters:

other - The location to compare.

Returns:

True if this starts after other.

Throws:

java.lang.IllegalArgumentException - Locations are on opposite strands.

startsBefore

public boolean startsBefore(Location other)

Check if this location starts before other location starts. The locations may overlap.

Parameters:

other - The location to compare.

Returns:

True if this starts before other.

Throws:

java.lang.IllegalArgumentException - Locations are on opposite strands.

suffix

public Location suffix(int position)

The part of this location after the specified position. If position is negative, count backwards from the end.

For position >= 0, return Location( start + position, end ).
For position < 0, return Location( end - position, end ).

Parameters:

position - Where the suffix starts.

Returns:

New location from position to end of this location.

Throws:

java.lang.IndexOutOfBoundsException - Specified suffix is longer than location.

suffix

public Location suffix(Location other)

The part of this location after the other location (not inclusive).

Parameters:

other - The other location.

Returns:

The part of this location after the other location.

Throws:

java.lang.IllegalArgumentException - Locations are on opposite strands.

java.lang.IndexOutOfBoundsException - This location does not contain other location.

toString

public java.lang.String toString()

Return a string representation of location.

Overrides:

toString in class java.lang.Object

Returns:

Text string.

union

public Location union(Location other)

Return the union.

Parameters:

other - The location to join.

Returns:

The union is a range that starts at the lesser of the two starting indices and ends at the greater of the two ends.

Throws:

java.lang.IllegalArgumentException - Locations are on opposite strands.

upstream

public Location upstream(int length)

Return the adjacent location of specified length directly upstream of this location.

Parameters:

length - The length of the upstream location.

Returns:

Upstream location.

Throws:

java.lang.IndexOutOfBoundsException - Specified length causes crossing of origin.

window

public java.lang.Iterable<Location> window(int windowSize,
                                           int increment)

Enable a "sliding window" iteration over a location to use with Java's "for" loop construct. The returned helper object implements the Iterable interface; the windowSize and increment semantics are implemented by an underlying LocIterator.

For example, given a location variable "loc":

        //use window size of 3 and increment of +3
        for( Location temp: loc.window( 3, 3 ))
        {
        //at each iteration, temp will be the location of the next 3 symbols
        }

Parameters:

windowSize - The number of symbols to get on each iteration.

increment - The direction and number of symbols to advance at each iteration.

Returns:

An anonymous iterable object to use with Java's for( ... ) loop construct.