# Class IntervalList

java.lang.Object
htsjdk.samtools.util.IntervalList

All Implemented Interfaces:
  `Iterable<Interval>`

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)

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`IntervalList.IntervalMergerIterator`
An iterator that feeds on an `Iterator<Interval>` and combines consecutive intervals that need merging.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`INTERVAL_LIST_FILE_EXTENSION`
Deprecated.
since June 2019 Use `FileExtensions.INTERVAL_LIST` instead.

## 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

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.
`IntervalList`
`addOther(IntervalList other)`
A method for concatenating the intervals from one list to this one, checks for equal dictionaries.
`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(IntervalList list1, IntervalList list2)`
A utility function for merging a two IntervalLists, checks for equal dictionaries.
`static IntervalList`
`concatenate(Collection<IntervalList> lists)`
A utility function for concatenating a list of IntervalLists, checks for equal dictionaries.
`static IntervalList`
`copyOf(IntervalList list)`
creates a independent copy of the given IntervalList
`static IntervalList`
`difference(IntervalList list1, IntervalList list2)`
A utility function for finding the difference between two IntervalLists.
`static 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)`
Calls `fromFile(java.io.File)` on the provided files, and returns their `concatenate(Collection)`
`static IntervalList`
`fromName(SAMFileHeader header, String sequenceName)`
Creates an IntervalList from the given sequence name
`static 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 `uniqued()`.`getIntervals()` instead.
`List<Interval>`
`getUniqueIntervals(boolean concatenateNames)`
Deprecated.
use `uniqued(boolean)`.`getIntervals()` or `getUniqueIntervals(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()
`static List<Interval>`
`getUniqueIntervals(IntervalList list, boolean combineAbuttingIntervals, 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.
use `sorted()` instead.
`IntervalList`
`sorted()`
returns an independent sorted IntervalList
`static IntervalList`
`subtract(IntervalList lhs, IntervalList rhs)`
A utility function for subtracting one IntervalLists 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.
use `uniqued()` instead.
`void`
`unique(boolean concatenateNames)`
Deprecated.
use `uniqued(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.
`void`
`write(Path path)`
Writes out the list of intervals to the supplied path.

### Methods inherited from class Object

`clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface Iterable

`forEach, spliterator`

## Field Details

### INTERVAL_LIST_FILE_EXTENSION

@Deprecated public static final String INTERVAL_LIST_FILE_EXTENSION
Deprecated.
since June 2019 Use `FileExtensions.INTERVAL_LIST` instead.

See Also:
  - Constant Field Values

## Constructor Details

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

### getHeader

public SAMFileHeader getHeader()
Gets the header (if there is one) for the interval list.

### iterator

public Iterator<Interval> iterator()
Returns an iterator over the intervals.

Specified by:
  `iterator` in interface `Iterable<Interval>`

### 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.
use `sorted()` 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.
use `uniqued()` 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.
use `uniqued(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.

### getIntervals

public List<Interval> getIntervals()
Gets the set of intervals as held internally.

### getUniqueIntervals

@Deprecated public List<Interval> getUniqueIntervals()
Deprecated.
use `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

public static List<Interval> getUniqueIntervals(IntervalList list, boolean combineAbuttingIntervals, boolean concatenateNames, boolean enforceSameStrands)
Merges list of intervals and reduces them like htsjdk.samtools.util.IntervalList#getUniqueIntervals()

Parameters:
  `combineAbuttingIntervals` - If true, intervals that are abutting will be combined into one interval.
  `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 `uniqued(boolean)`.`getIntervals()` or `getUniqueIntervals(IntervalList, boolean)` instead.
Merges list of intervals and reduces them like `getUniqueIntervals()`. 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 Interval
  `bandMultiple` - 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 IntervalList
  `sequenceName` - 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)
Calls `fromFile(java.io.File)` on the provided files, and returns their `concatenate(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(Path path)
Writes out the list of intervals to the supplied path.

Parameters:
  `path` - a path to write to. If exists it will be overwritten.

### 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 IntervalList
  `list2` - 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(IntervalList list1, IntervalList list2)
A utility function for merging a two IntervalLists, checks for equal dictionaries. Merging does not look for overlapping intervals nor uniquify

Parameters:
  `list1` - the first list
  `list2` - the second list
Returns:
  the union of all the IntervalLists in lists.

### addOther

public IntervalList addOther(IntervalList other)
A method for concatenating the intervals from one list to this one, checks for equal dictionaries. Does not look for overlapping intervals nor uniquify.

Parameters:
  `other` - the other list
Returns:
  the modified this

### concatenate

public static IntervalList concatenate(Collection<IntervalList> lists)
A utility function for concatenating a list of IntervalLists, checks for equal dictionaries. Concatenating does not look for overlapping intervals nor uniquify the intervals.

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(IntervalList lhs, IntervalList rhs)
A utility function for subtracting one IntervalLists from another. Resulting loci are those that are in the first but not the second.

Parameters:
  `lhs` - the IntervalList from which to subtract intervals
  `rhs` - the IntervalList to subtract
Returns:
  an IntervalList comprising all loci that are in the first IntervalList but not the second lhs-rhs=answer.

### 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 intervals
  `rhs` - 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.

### 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 IntervalLists
  `lists2` - 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

### difference

public static IntervalList difference(IntervalList list1, IntervalList list2)
A utility function for finding the difference between two IntervalLists.

Parameters:
  `list1` - the first collection of IntervalLists
  `list2` - 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 IntervalLists
  `rhs` - 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 IntervalLists
  `lists2` - 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.

### equals

public boolean equals(Object o)

Overrides:
  `equals` in class `Object`

### hashCode

public int hashCode()

Overrides:
  `hashCode` in class `Object`