Package org.biojava.nbio.genome.parsers.gff

Class Location

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
    Description
    Location(int start, int end)
    Construct new location from coordinates.
    Location(Location other)
    Clone other location.

  • Method Summary

    Modifier and Type
    Method
    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.
    static void
    main(String[] args)
    Deprecated. 
    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 Details

    • 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 Details

    • 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

    • main

      @Deprecated public static void main(String[] args) throws Exception
      Deprecated.
      Throws:
      Exception