Location (biojava 5.0.0 API)

java.lang.Object
- org.biojava.nbio.genome.parsers.gff.Location

All Implemented Interfaces:

Iterable<Location>
```
public class Location
extends Object
implements Iterable<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, (i.e. 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.

Author:

Hanno Hinsch

Constructor Summary

Constructors
Constructor and Description

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

Location(Location other)
Clone other location.

Constructors
Constructor and Description
`Location(int start, int end)` Construct new location from coordinates.
`Location(Location other)` Clone other location.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`bioEnd()` Get end index, in biocoordinates.
`int`	`bioStart()` Get start index, in biocoordinates.
`char`	`bioStrand()` Get character representation of strand.
`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(Object obj)`
`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.
`int`	`getBegin()`
`int`	`getEnd()`
`int`	`hashCode()`
`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).
`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.
`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, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- 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:
    
    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
  - getBegin
```
public int getBegin()
```
  - getEnd
```
public int getEnd()
```
  - 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:
    
    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:
    
    IllegalArgumentException - Strand must be '+', '-', '.'
  - bioStrand
```
public char bioStrand()
```
    Get character representation of strand.
    
    Returns:
    
    '+' or '-'
  - bioStart
```
public int bioStart()
```
    Get start index, in biocoordinates.
    
    Returns:
    
    The origin 1 index of the first symbol in location.
  - bioEnd
```
public int bioEnd()
```
    Get end index, in biocoordinates.
    
    Returns:
    
    The origin 1 index of the final symbol in location.
  - 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.
  - 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.
  - 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:
    
    IllegalArgumentException - Locations are on opposite strands.
  - 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:
    
    IllegalArgumentException - Locations are on opposite strands.
  - start
```
public int start()
```
    Get starting index (origin 0).
    
    Returns:
    
    The start index.
  - end
```
public int end()
```
    Get the ending index.
    
    Returns:
    
    The index of last symbol + 1 (remember Java half-open coordinates).
  - length
```
public int length()
```
    Get length of range.
    
    Returns:
    
    The length of the range (end - start).
  - window
```
public 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.
  - 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 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).
  - 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:
    
    IndexOutOfBoundsException - Specified prefix is longer than location.
  - 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:
    
    IndexOutOfBoundsException - Specified suffix 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:
    
    IllegalArgumentException - Locations are on opposite strands.
    
    IndexOutOfBoundsException - This location does not contain other 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:
    
    IllegalArgumentException - Locations are on opposite strands.
    
    IndexOutOfBoundsException - This location does not contain other location.
  - 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:
    
    IndexOutOfBoundsException - Specified length causes crossing of origin.
  - 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:
    
    IndexOutOfBoundsException - Specified length causes crossing of origin.
  - 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:
    
    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:
    
    IllegalArgumentException - Locations are on opposite strands.
  - 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:
    
    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:
    
    IllegalArgumentException - Locations are on opposite strands.
  - 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:
    
    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:
    
    IllegalArgumentException - Locations are on opposite strands.
  - 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:
    
    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:
    
    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:
    
    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:
    
    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.
  - opposite
```
public Location opposite()
```
    Return location that is in same position on opposite strand.
    
    Returns:
    
    Location on opposite 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.
  - toString
```
public String toString()
```
    Return a string representation of location.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    Text string.
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object

Class Location

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Constructor Detail

Location

Location

Method Detail

getBegin

getEnd

fromBio

fromBioExt

bioStrand

bioStart

bioEnd

plus

minus

union

intersection

start

end

length

window

iterator

iterator

prefix

suffix

prefix

suffix

upstream

downstream

distance

percentOverlap

overlaps

contains

startsAfter

startsBefore

endsAfter

endsBefore

isAfter

isBefore

isNegative

opposite

isSameStrand

toString

hashCode

equals