Package htsjdk.samtools.util
Class IntervalList
- java.lang.Object
-
- htsjdk.samtools.util.IntervalList
-
public class IntervalList extends Object implements Iterable<Interval>
Represents a list of intervals against a reference sequence that can be written to and read from a file. The file format is relatively simple and reflects the SAM alignment format to a degree. A SAM style header must be present in the file which lists the sequence records against which the intervals are described. After the header the file then contains records one per line in text format with the following values tab-separated:- Sequence name
- Start position (1-based)
- End position (1-based, end inclusive)
- Strand (either + or -)
- Interval name (an, ideally unique, name for the interval)
-
-
Field Summary
Fields Modifier and Type Field Description static String
INTERVAL_LIST_FILE_EXTENSION
-
Constructor Summary
Constructors Constructor Description IntervalList(SAMFileHeader header)
Constructs a new interval list using the supplied header information.IntervalList(SAMSequenceDictionary dict)
Constructs a new interval list using the supplied header information.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
add(Interval interval)
Adds an interval to the list of intervals.void
addall(Collection<Interval> intervals)
Adds a Collection of intervals to the list of intervals.static List<Interval>
breakIntervalsAtBandMultiples(List<Interval> intervals, int bandMultiple)
Given a list of Intervals and a band multiple, this method will return a list of Intervals such that all of the intervals do not straddle integer multiples of that band.static IntervalList
concatenate(Collection<IntervalList> lists)
A utility function for merging a list of IntervalLists, checks for equal dictionaries.static IntervalList
copyOf(IntervalList list)
creates a independent copy of the given IntervalListstatic IntervalList
difference(Collection<IntervalList> lists1, Collection<IntervalList> lists2)
A utility function for finding the difference between two IntervalLists.boolean
equals(Object o)
static IntervalList
fromFile(File file)
Parses an interval list from a file.static IntervalList
fromFiles(Collection<File> intervalListFiles)
CallsfromFile(java.io.File)
on the provided files, and returns theirunion(java.util.Collection)
.static IntervalList
fromName(SAMFileHeader header, String sequenceName)
Creates an IntervalList from the given sequence namestatic IntervalList
fromPath(Path path)
Parses an interval list from a path.static IntervalList
fromReader(BufferedReader in)
Parses an interval list from a reader in a stream based fashion.long
getBaseCount()
Gets the (potentially redundant) sum of the length of the intervals in the list.SAMFileHeader
getHeader()
Gets the header (if there is one) for the interval list.List<Interval>
getIntervals()
Gets the set of intervals as held internally.long
getUniqueBaseCount()
Gets the count of unique bases represented by the intervals in the list.List<Interval>
getUniqueIntervals()
Deprecated.use {@link #uniqued()#getIntervals()} instead.List<Interval>
getUniqueIntervals(boolean concatenateNames)
Deprecated.use {@link #uniqued(boolean)#getIntervals()} orgetUniqueIntervals(IntervalList, boolean)
instead.static List<Interval>
getUniqueIntervals(IntervalList list, boolean concatenateNames)
Merges list of intervals and reduces them like htsjdk.samtools.util.IntervalList#getUniqueIntervals()static List<Interval>
getUniqueIntervals(IntervalList list, boolean concatenateNames, boolean enforceSameStrands)
Merges list of intervals and reduces them like htsjdk.samtools.util.IntervalList#getUniqueIntervals()int
hashCode()
static IntervalList
intersection(IntervalList list1, IntervalList list2)
A utility function for generating the intersection of two IntervalLists, checks for equal dictionaries.static IntervalList
intersection(Collection<IntervalList> lists)
A utility function for intersecting a list of IntervalLists, checks for equal dictionaries.static IntervalList
invert(IntervalList list)
inverts an IntervalList and returns one that has exactly all the bases in the dictionary that the original one does not.Iterator<Interval>
iterator()
Returns an iterator over the intervals.static IntervalList
overlaps(IntervalList lhs, IntervalList rhs)
A utility function for finding the intervals in the first list that have at least 1bp overlap with any interval in the second list.static IntervalList
overlaps(Collection<IntervalList> lists1, Collection<IntervalList> lists2)
A utility function for finding the intervals in the first list that have at least 1bp overlap with any interval in the second list.IntervalList
padded(int padding)
Returns a new IntervalList where each interval is padded by 'padding' bases on each side.IntervalList
padded(int before, int after)
Returns a new IntervalList where each interval is padded by the specified amount of bases.int
size()
Returns the count of intervals in the list.void
sort()
Deprecated.usesorted()
instead.IntervalList
sorted()
returns an independent sorted IntervalListstatic IntervalList
subtract(IntervalList lhs, IntervalList rhs)
A utility function for subtracting a single IntervalList from another.static IntervalList
subtract(Collection<IntervalList> lhs, Collection<IntervalList> rhs)
A utility function for subtracting a collection of IntervalLists from another.static IntervalList
union(IntervalList list1, IntervalList list2)
static IntervalList
union(Collection<IntervalList> lists)
A utility function for finding the union of a list of IntervalLists, checks for equal dictionaries.void
unique()
Deprecated.useuniqued()
instead.void
unique(boolean concatenateNames)
Deprecated.useuniqued(boolean)
instead.IntervalList
uniqued()
Returned an independent IntervalList that is sorted and uniquified.IntervalList
uniqued(boolean concatenateNames)
Returned an independent IntervalList that is sorted and uniquified.void
write(File file)
Writes out the list of intervals to the supplied file.-
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface java.lang.Iterable
forEach, spliterator
-
-
-
-
Field Detail
-
INTERVAL_LIST_FILE_EXTENSION
public static final String INTERVAL_LIST_FILE_EXTENSION
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
IntervalList
public IntervalList(SAMFileHeader header)
Constructs a new interval list using the supplied header information.
-
IntervalList
public IntervalList(SAMSequenceDictionary dict)
Constructs a new interval list using the supplied header information.
-
-
Method Detail
-
getHeader
public SAMFileHeader getHeader()
Gets the header (if there is one) for the interval list.
-
add
public void add(Interval interval)
Adds an interval to the list of intervals.
-
addall
public void addall(Collection<Interval> intervals)
Adds a Collection of intervals to the list of intervals.
-
sort
@Deprecated public void sort()
Deprecated.usesorted()
instead.Sorts the internal collection of intervals by coordinate. Note: this function modifies the object in-place and is therefore difficult to work with.
-
padded
public IntervalList padded(int before, int after)
Returns a new IntervalList where each interval is padded by the specified amount of bases.
-
padded
public IntervalList padded(int padding)
Returns a new IntervalList where each interval is padded by 'padding' bases on each side.
-
sorted
public IntervalList sorted()
returns an independent sorted IntervalList
-
uniqued
public IntervalList uniqued()
Returned an independent IntervalList that is sorted and uniquified.
-
uniqued
public IntervalList uniqued(boolean concatenateNames)
Returned an independent IntervalList that is sorted and uniquified.- Parameters:
concatenateNames
- If false, interval names are not concatenated when merging intervals to save space.
-
unique
@Deprecated public void unique()
Deprecated.useuniqued()
instead.Sorts and uniques the list of intervals held within this interval list. Note: this function modifies the object in-place and is therefore difficult to work with.
-
unique
@Deprecated public void unique(boolean concatenateNames)
Deprecated.useuniqued(boolean)
instead.Sorts and uniques the list of intervals held within this interval list. Note: this function modifies the object in-place and is therefore difficult to work with.- Parameters:
concatenateNames
- If false, interval names are not concatenated when merging intervals to save space.
-
getUniqueIntervals
@Deprecated public List<Interval> getUniqueIntervals()
Deprecated.use {@link #uniqued()#getIntervals()} instead.Merges the list of intervals and then reduces them down where regions overlap or are directly adjacent to one another. During this process the "merged" interval will retain the strand and name of the 5' most interval merged. Note: has the side-effect of sorting the stored intervals in coordinate order if not already sorted. Note: this function modifies the object in-place and is therefore difficult to work with.- Returns:
- the set of unique intervals condensed from the contained intervals
-
getUniqueIntervals
public static List<Interval> getUniqueIntervals(IntervalList list, boolean concatenateNames)
Merges list of intervals and reduces them like htsjdk.samtools.util.IntervalList#getUniqueIntervals()- Parameters:
concatenateNames
- If false, the merged interval has the name of the earlier interval. This keeps name shorter.
-
getUniqueIntervals
public static List<Interval> getUniqueIntervals(IntervalList list, boolean concatenateNames, boolean enforceSameStrands)
Merges list of intervals and reduces them like htsjdk.samtools.util.IntervalList#getUniqueIntervals()- Parameters:
concatenateNames
- If false, the merged interval has the name of the earlier interval. This keeps name shorter.enforceSameStrands
- enforce that merged intervals have the same strand, otherwise ignore.
-
getUniqueIntervals
@Deprecated public List<Interval> getUniqueIntervals(boolean concatenateNames)
Deprecated.use {@link #uniqued(boolean)#getIntervals()} orgetUniqueIntervals(IntervalList, boolean)
instead.Merges list of intervals and reduces them likegetUniqueIntervals()
. Note: this function modifies the object in-place and is therefore difficult to work with.- Parameters:
concatenateNames
- If false, the merged interval has the name of the earlier interval. This keeps name shorter.
-
breakIntervalsAtBandMultiples
public static List<Interval> breakIntervalsAtBandMultiples(List<Interval> intervals, int bandMultiple)
Given a list of Intervals and a band multiple, this method will return a list of Intervals such that all of the intervals do not straddle integer multiples of that band. ex: if there is an interval (7200-9300) and the bandMultiple is 1000, the interval will be split into: (7200-7999, 8000-8999, 9000-9300)- Parameters:
intervals
- A list of IntervalbandMultiple
- integer value (> 0) to break up intervals in the list at integer multiples of- Returns:
- list of intervals that are broken up
-
getBaseCount
public long getBaseCount()
Gets the (potentially redundant) sum of the length of the intervals in the list.
-
getUniqueBaseCount
public long getUniqueBaseCount()
Gets the count of unique bases represented by the intervals in the list.
-
size
public int size()
Returns the count of intervals in the list.
-
copyOf
public static IntervalList copyOf(IntervalList list)
creates a independent copy of the given IntervalList
-
fromFile
public static IntervalList fromFile(File file)
Parses an interval list from a file.- Parameters:
file
- the file containing the intervals- Returns:
- an IntervalList object that contains the headers and intervals from the file
-
fromPath
public static IntervalList fromPath(Path path)
Parses an interval list from a path.- Parameters:
path
- the path containing the intervals- Returns:
- an IntervalList object that contains the headers and intervals from the path
-
fromName
public static IntervalList fromName(SAMFileHeader header, String sequenceName)
Creates an IntervalList from the given sequence name- Parameters:
header
- header to use to create IntervalListsequenceName
- name of sequence in header- Returns:
- a new intervalList with given header that contains the reference name
-
fromFiles
public static IntervalList fromFiles(Collection<File> intervalListFiles)
CallsfromFile(java.io.File)
on the provided files, and returns theirunion(java.util.Collection)
.
-
fromReader
public static IntervalList fromReader(BufferedReader in)
Parses an interval list from a reader in a stream based fashion.- Parameters:
in
- a BufferedReader that can be read from. Caller is responsible to close reader as needed.- Returns:
- an IntervalList object that contains the headers and intervals from the file
- Throws:
IllegalArgumentException
- if start or end are less than 1 or greater than the length of the sequence
-
write
public void write(File file)
Writes out the list of intervals to the supplied file.- Parameters:
file
- a file to write to. If exists it will be overwritten.
-
intersection
public static IntervalList intersection(IntervalList list1, IntervalList list2)
A utility function for generating the intersection of two IntervalLists, checks for equal dictionaries.- Parameters:
list1
- the first IntervalListlist2
- the second IntervalList- Returns:
- the intersection of list1 and list2.
-
intersection
public static IntervalList intersection(Collection<IntervalList> lists)
A utility function for intersecting a list of IntervalLists, checks for equal dictionaries.- Parameters:
lists
- the list of IntervalList- Returns:
- the intersection of all the IntervalLists in lists.
-
concatenate
public static IntervalList concatenate(Collection<IntervalList> lists)
A utility function for merging a list of IntervalLists, checks for equal dictionaries. Merging does not look for overlapping intervals nor uniquify- Parameters:
lists
- a list of IntervalList- Returns:
- the union of all the IntervalLists in lists.
-
union
public static IntervalList union(Collection<IntervalList> lists)
A utility function for finding the union of a list of IntervalLists, checks for equal dictionaries. also looks for overlapping intervals, uniquifies, and sorts (by coordinate)- Parameters:
lists
- the list of IntervalList- Returns:
- the union of all the IntervalLists in lists.
-
union
public static IntervalList union(IntervalList list1, IntervalList list2)
-
invert
public static IntervalList invert(IntervalList list)
inverts an IntervalList and returns one that has exactly all the bases in the dictionary that the original one does not.- Parameters:
list
- an IntervalList- Returns:
- an IntervalList that is complementary to list
-
subtract
public static IntervalList subtract(Collection<IntervalList> lhs, Collection<IntervalList> rhs)
A utility function for subtracting a collection of IntervalLists from another. Resulting loci are those that are in the first collection but not the second.- Parameters:
lhs
- the collection of IntervalList from which to subtract intervalsrhs
- the collection of intervals to subtract- Returns:
- an IntervalList comprising all loci that are in the first collection but not the second lhs-rhs=answer.
-
subtract
public static IntervalList subtract(IntervalList lhs, IntervalList rhs)
A utility function for subtracting a single IntervalList from another. Resulting loci are those that are in the first List but not the second.- Parameters:
lhs
- the IntervalList from which to subtract intervalsrhs
- the IntervalList to subtract- Returns:
- an IntervalList comprising all loci that are in first IntervalList but not the second. lhs-rhs=answer
-
difference
public static IntervalList difference(Collection<IntervalList> lists1, Collection<IntervalList> lists2)
A utility function for finding the difference between two IntervalLists.- Parameters:
lists1
- the first collection of IntervalListslists2
- the second collection of IntervalLists- Returns:
- the difference between the two intervals, i.e. the loci that are only in one IntervalList but not both
-
overlaps
public static IntervalList overlaps(IntervalList lhs, IntervalList rhs)
A utility function for finding the intervals in the first list that have at least 1bp overlap with any interval in the second list.- Parameters:
lhs
- the first collection of IntervalListsrhs
- the second collection of IntervalLists- Returns:
- an IntervalList comprising of all intervals in the first IntervalList that have at least 1bp overlap with any interval in the second.
-
overlaps
public static IntervalList overlaps(Collection<IntervalList> lists1, Collection<IntervalList> lists2)
A utility function for finding the intervals in the first list that have at least 1bp overlap with any interval in the second list.- Parameters:
lists1
- the first collection of IntervalListslists2
- the second collection of IntervalLists- Returns:
- an IntervalList comprising of all intervals in the first collection of lists that have at least 1bp overlap with any interval in the second lists.
-
-