org.broadinstitute.hellbender.utils

Class IntervalUtils

java.lang.Object

org.broadinstitute.hellbender.utils.IntervalUtils

public final class IntervalUtils
extends java.lang.Object

Parse text representations of interval strings that can appear in GATK-based applications.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	IntervalUtils.IntervalBreakpointType An enum to classify breakpoints whether the breakpoint is the start or end of a region.

Field Summary

Fields

Modifier and Type	Field and Description
static java.util.List<java.lang.String>	INTERVAL_FILE_EXTENSIONS Recognized extensions for interval files
static java.util.Comparator<htsjdk.samtools.util.Locatable>	LEXICOGRAPHICAL_ORDER_COMPARATOR Lexicographical (contig) order comparator.

Constructor Summary

Constructors

Constructor and Description
IntervalUtils()

Method Summary

Modifier and Type	Method and Description
static int	beginOfShard(int shardIndex, int shardSize) first offset in this shard (1-based).
static <T extends htsjdk.samtools.util.Locatable> java.util.List<htsjdk.samtools.util.Locatable>	combineAndSortBreakpoints(java.util.List<T> unsortedLocatables1, java.util.List<T> unsortedLocatables2, htsjdk.samtools.SAMSequenceDictionary dictionary) Combine the breakpoints of multiple intervals and return a list of locatables based on the updated breakpoints.
static int	compareContigs(htsjdk.samtools.util.Locatable first, htsjdk.samtools.util.Locatable second, htsjdk.samtools.SAMSequenceDictionary dictionary) Determines the relative contig ordering of first and second using the provided sequence dictionary
static int	compareLocatables(htsjdk.samtools.util.Locatable first, htsjdk.samtools.util.Locatable second, htsjdk.samtools.SAMSequenceDictionary dictionary) Compare two locations using a SAMSequenceDictionary sequence ordering
static java.util.List<SimpleInterval>	convertGenomeLocsToSimpleIntervals(java.util.List<GenomeLoc> genomeLocIntervals) Convert a List of intervals in GenomeLoc format into a List of intervals in SimpleInterval format.
static htsjdk.samtools.QueryInterval	convertSimpleIntervalToQueryInterval(SimpleInterval interval, htsjdk.samtools.SAMSequenceDictionary sequenceDictionary) Converts an interval in SimpleInterval format into an htsjdk QueryInterval.
static <T extends htsjdk.samtools.util.Locatable,U extends htsjdk.samtools.util.Locatable> java.util.Map<T,java.util.List<U>>	createOverlapMap(java.util.List<T> keys, java.util.List<U> vals, htsjdk.samtools.SAMSequenceDictionary dictionary) Creates a map of which locatables (keys) overlap the other list of locatables (vals) Input lists will be sorted sorted by the input dictionary.
static java.util.List<SimpleInterval>	cutToShards(java.lang.Iterable<SimpleInterval> intervals, int shardSize) Splits the given input intervals into shards of at most the requested size.
static int	endOfShard(int shardIndex, int shardSize) last offset in this shard (1-based).
static java.lang.String	equateIntervals(java.util.List<GenomeLoc> masterArg, java.util.List<GenomeLoc> testArg) computes whether the test interval list is equivalent to master.
static java.util.List<GenomeLoc>	featureFileToIntervals(GenomeLocParser parser, java.lang.String featureFile) Converts a Feature-containing file to a list of intervals
static java.util.List<GenomeLoc>	flattenSplitIntervals(java.util.List<java.util.List<GenomeLoc>> splits)
static java.util.List<GenomeLoc>	genomeLocsFromLocatables(GenomeLocParser parser, java.util.Collection<? extends htsjdk.samtools.util.Locatable> locatables) Generates a list of GenomeLoc instances given the appropriate GenomeLocParser factory and a collection of Locatable instances.
static java.util.List<SimpleInterval>	getAllIntervalsForReference(htsjdk.samtools.SAMSequenceDictionary sequenceDictionary) Builds a list of intervals that cover the whole given sequence.
static java.util.Map<java.lang.String,java.lang.Integer>	getContigSizes(java.nio.file.Path reference) Returns a map of contig names with their sizes.
static java.util.Comparator<htsjdk.samtools.util.Locatable>	getDictionaryOrderComparator(htsjdk.samtools.SAMSequenceDictionary dictionary) The order of contigs/sequences in the dictionary is the order of the sorting here.
static java.util.List<GenomeLoc>	getIntervalsWithFlanks(GenomeLocParser parser, java.util.List<GenomeLoc> locs, int basePairs) Returns a list of intervals between the passed int locs.
static java.util.List<SimpleInterval>	getIntervalsWithFlanks(java.util.List<SimpleInterval> intervals, int basePairs, htsjdk.samtools.SAMSequenceDictionary dictionary) Pads the provided intervals by the specified amount, sorts the resulting intervals, and merges intervals that are adjacent/overlapping after padding.
static java.util.List<SimpleInterval>	getResolvedIntervals(java.lang.String intervalQueryString, htsjdk.samtools.SAMSequenceDictionary sequenceDictionary) Given an interval query string and a sequence dictionary, determine if the query string can be resolved as a valid interval query against more than one contig in the dictionary, i.e., more than one of: prefix prefix:nnn prefix:nnn+ prefix:nnn-nnn and return the list of all possible interpretations (there can never be more than 2).
static SimpleInterval	getSpanningInterval(java.util.List<? extends htsjdk.samtools.util.Locatable> locations) getSpanningInterval returns interval that covers all of the locations passed in.
static java.util.List<SimpleInterval>	getSpanningIntervals(java.util.List<? extends htsjdk.samtools.util.Locatable> locations, htsjdk.samtools.SAMSequenceDictionary sequenceDictionary) Get a single interval per contig that includes all of the specified intervals (This is used to improve GenomicsDB performance for exomes)
static java.util.List<java.util.List<SimpleInterval>>	groupIntervalsByContig(java.util.List<SimpleInterval> sortedIntervals) Accepts a sorted List of intervals, and returns a List of Lists of intervals grouped by contig, one List per contig.
static java.util.List<GenomeLoc>	intervalFileToList(GenomeLocParser glParser, java.lang.String fileName) Read a file of genome locations to process.
static boolean	intervalIsOnDictionaryContig(SimpleInterval interval, htsjdk.samtools.SAMSequenceDictionary dictionary) Determines whether the provided interval is within the bounds of its assigned contig according to the provided dictionary
static long	intervalSize(java.util.List<GenomeLoc> locs)
static boolean	isAfter(htsjdk.samtools.util.Locatable first, htsjdk.samtools.util.Locatable second, htsjdk.samtools.SAMSequenceDictionary dictionary) Tests whether the first Locatable starts after the end of the second Locatable
static boolean	isBefore(htsjdk.samtools.util.Locatable first, htsjdk.samtools.util.Locatable second, htsjdk.samtools.SAMSequenceDictionary dictionary) Tests whether the first Locatable ends before the start of the second Locatable
static boolean	isIntervalFile(java.lang.String str) Check if string argument was intended as a file Accepted file extensions: .bed .list, .picard, .interval_list, .intervals.
static boolean	isIntervalFile(java.lang.String str, boolean checkExists) Check if string argument was intended as a file Accepted file extensions are defined in INTERVAL_FILE_EXTENSIONS
static boolean	isReciprocalOverlap(SimpleInterval interval1, SimpleInterval interval2, double reciprocalOverlapThreshold) Determine whether the two intervals specified overlap each other by at least the threshold proportion specified.
static GenomeLocSortedSet	loadIntervals(java.util.List<java.lang.String> intervalStrings, IntervalSetRule intervalSetRule, IntervalMergingRule intervalMergingRule, int padding, GenomeLocParser genomeLocParser)
static java.lang.String	locatableToString(htsjdk.samtools.util.Locatable interval)
static java.util.List<GenomeLoc>	mergeIntervalLocations(java.util.List<GenomeLoc> raw, IntervalMergingRule rule) merge a list of genome locs that may be overlapping, returning the list of unique genomic locations
static java.util.List<GenomeLoc>	mergeListsBySetOperator(java.util.List<GenomeLoc> setOne, java.util.List<GenomeLoc> setTwo, IntervalSetRule rule) merge two interval lists, using an interval set rule
static boolean	overlaps(htsjdk.samtools.util.Locatable left, htsjdk.samtools.util.Locatable right) Check whether two locatables overlap.
static java.util.List<GenomeLoc>	parseIntervalArguments(GenomeLocParser parser, java.util.List<java.lang.String> argList) Turns a set of strings describing intervals into a parsed set of intervals.
static java.util.List<GenomeLoc>	parseIntervalArguments(GenomeLocParser parser, java.lang.String arg)
static void	scatterContigIntervals(htsjdk.samtools.SAMFileHeader fileHeader, java.util.List<GenomeLoc> locs, java.util.List<java.io.File> scatterParts) Splits an interval list into multiple files.
static void	scatterFixedIntervals(htsjdk.samtools.SAMFileHeader fileHeader, java.util.List<java.util.List<GenomeLoc>> splits, java.util.List<java.io.File> scatterParts) Splits an interval list into multiple files.
static int	shardIndex(int oneBasedOffset, int shardSize) number of the shard this offset is in.
static GenomeLocSortedSet	sortAndMergeIntervals(GenomeLocParser parser, java.util.List<GenomeLoc> intervals, IntervalMergingRule mergingRule) Sorts and merges an interval list.
static <T extends htsjdk.samtools.util.Locatable> java.util.List<T>	sortLocatablesBySequenceDictionary(java.util.Collection<T> locatables, htsjdk.samtools.SAMSequenceDictionary dictionary) Sort by the contig then position as specified by the index order in the given sequence dictionary.
static java.util.List<java.util.List<GenomeLoc>>	splitFixedIntervals(java.util.List<GenomeLoc> locs, int numParts) Splits the genome locs up by size.
static java.util.List<java.util.List<GenomeLoc>>	splitIntervalsToSubLists(java.util.List<GenomeLoc> locs, java.util.List<java.lang.Integer> splits) Splits an interval list into multiple sublists.
static java.util.List<java.util.List<GenomeLoc>>	splitLocusIntervals(java.util.List<GenomeLoc> locs, int numParts)
static SimpleInterval	trimIntervalToContig(java.lang.String contig, int start, int stop, int contigLength) Create a new interval, bounding start and stop by the start and end of contig This function will return null if start and stop cannot be adjusted in any reasonable way to be on the contig.
static <T extends htsjdk.samtools.util.Locatable> void	validateNoOverlappingIntervals(java.util.List<T> locatables) Throws Bad Input exception if any overlaps are detected within the list of locatables.

Methods inherited from class java.lang.Object

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

Field Detail

INTERVAL_FILE_EXTENSIONS

public static final java.util.List<java.lang.String> INTERVAL_FILE_EXTENSIONS

Recognized extensions for interval files

LEXICOGRAPHICAL_ORDER_COMPARATOR

public static final java.util.Comparator<htsjdk.samtools.util.Locatable> LEXICOGRAPHICAL_ORDER_COMPARATOR

Lexicographical (contig) order comparator.

Intervals from different contigs order is according their enclosing contigs name ascending lexicographical order.

Intervals from the same contigs order is according to their start position ascending numerical order, and, in case of a tie, the stop position's.

The null contig is supported and comes last.

Constructor Detail

IntervalUtils

public IntervalUtils()

Method Detail

compareLocatables

public static final int compareLocatables(htsjdk.samtools.util.Locatable first,
                                          htsjdk.samtools.util.Locatable second,
                                          htsjdk.samtools.SAMSequenceDictionary dictionary)

Compare two locations using a SAMSequenceDictionary sequence ordering

Returns:

0 if first and second are equal, a negative value if first < second or a positive value if first > second, using the ordering in the provided dictionary

Throws:

java.lang.IllegalArgumentException - if either first or second contigs could not be found in the dictionary

isBefore

public static boolean isBefore(htsjdk.samtools.util.Locatable first,
                               htsjdk.samtools.util.Locatable second,
                               htsjdk.samtools.SAMSequenceDictionary dictionary)

Tests whether the first Locatable ends before the start of the second Locatable

Parameters:

first - first Locatable

second - second Locatable

dictionary - sequence dictionary used to determine contig ordering

Returns:

true if first ends before the start of second, otherwise false

isAfter

public static boolean isAfter(htsjdk.samtools.util.Locatable first,
                              htsjdk.samtools.util.Locatable second,
                              htsjdk.samtools.SAMSequenceDictionary dictionary)

Tests whether the first Locatable starts after the end of the second Locatable

Parameters:

first - first Locatable

second - second Locatable

dictionary - sequence dictionary used to determine contig ordering

Returns:

true if first starts after the end of second, otherwise false

compareContigs

public static int compareContigs(htsjdk.samtools.util.Locatable first,
                                 htsjdk.samtools.util.Locatable second,
                                 htsjdk.samtools.SAMSequenceDictionary dictionary)

Determines the relative contig ordering of first and second using the provided sequence dictionary

Parameters:

first - first Locatable

second - second Locatable

dictionary - sequence dictionary used to determine contig ordering

Returns:

0 if the two contigs are the same, a negative value if first's contig comes before second's contig, or a positive value if first's contig comes after second's contig

getSpanningInterval

public static SimpleInterval getSpanningInterval(java.util.List<? extends htsjdk.samtools.util.Locatable> locations)

getSpanningInterval returns interval that covers all of the locations passed in.

Parameters:

locations - the locations to be spanned (on a single contig)

Returns:

the minimal span that covers all locations (could be null if no locations are passed in).

Throws:

java.lang.IllegalArgumentException - if the argument is null or if the argument contains any null element or if the locations are not all on the same contig (compared by String.equals)

convertGenomeLocsToSimpleIntervals

public static java.util.List<SimpleInterval> convertGenomeLocsToSimpleIntervals(java.util.List<GenomeLoc> genomeLocIntervals)

Convert a List of intervals in GenomeLoc format into a List of intervals in SimpleInterval format.

Parameters:

genomeLocIntervals - list of GenomeLoc intervals to convert

Returns:

equivalent List of SimpleIntervals

convertSimpleIntervalToQueryInterval

public static htsjdk.samtools.QueryInterval convertSimpleIntervalToQueryInterval(SimpleInterval interval,
                                                                                 htsjdk.samtools.SAMSequenceDictionary sequenceDictionary)

Converts an interval in SimpleInterval format into an htsjdk QueryInterval. In doing so, a header lookup is performed to convert from contig name to index

Parameters:

interval - interval to convert

sequenceDictionary - sequence dictionary used to perform the conversion

Returns:

an equivalent interval in QueryInterval format

loadIntervals

public static GenomeLocSortedSet loadIntervals(java.util.List<java.lang.String> intervalStrings,
                                               IntervalSetRule intervalSetRule,
                                               IntervalMergingRule intervalMergingRule,
                                               int padding,
                                               GenomeLocParser genomeLocParser)

parseIntervalArguments

public static java.util.List<GenomeLoc> parseIntervalArguments(GenomeLocParser parser,
                                                               java.util.List<java.lang.String> argList)

Turns a set of strings describing intervals into a parsed set of intervals. Valid string elements can be files, intervals in samtools notation (chrA:B-C), or some combination of the above separated by semicolons. Additionally, 'all' can be supplied to indicate all possible intervals, but 'all' must be exclusive of all other interval specifications.

Parameters:

parser - Genome loc parser.

argList - A list of strings containing interval data.

Returns:

an unsorted, unmerged representation of the given intervals. Null is used to indicate that all intervals should be used.

parseIntervalArguments

public static java.util.List<GenomeLoc> parseIntervalArguments(GenomeLocParser parser,
                                                               java.lang.String arg)

featureFileToIntervals

public static java.util.List<GenomeLoc> featureFileToIntervals(GenomeLocParser parser,
                                                               java.lang.String featureFile)

Converts a Feature-containing file to a list of intervals

Parameters:

parser - GenomeLocParser for creating intervals

featureFile - file containing Features to convert to intervals

Returns:

a List of intervals corresponding to the locations of the Features in the provided file

Throws:

UserException.CouldNotReadInputFile - if the provided file is not in a supported Feature file format

intervalFileToList

public static java.util.List<GenomeLoc> intervalFileToList(GenomeLocParser glParser,
                                                           java.lang.String fileName)

Read a file of genome locations to process. The file may be in Picard or GATK interval format.

Parameters:

glParser - GenomeLocParser

fileName - interval file

Returns:

List List of Genome Locs that have been parsed from file

mergeListsBySetOperator

public static java.util.List<GenomeLoc> mergeListsBySetOperator(java.util.List<GenomeLoc> setOne,
                                                                java.util.List<GenomeLoc> setTwo,
                                                                IntervalSetRule rule)

merge two interval lists, using an interval set rule

Parameters:

setOne - a list of genomeLocs, in order (cannot be NULL)

setTwo - a list of genomeLocs, also in order (cannot be NULL)

rule - the rule to use for merging, i.e. union, intersection, etc

Returns:

a list, correctly merged using the specified rule

sortAndMergeIntervals

public static GenomeLocSortedSet sortAndMergeIntervals(GenomeLocParser parser,
                                                       java.util.List<GenomeLoc> intervals,
                                                       IntervalMergingRule mergingRule)

Sorts and merges an interval list. Multiple techniques are available for merging: ALL, which combines all overlapping and abutting intervals into an interval that spans the union of all covered bases, and OVERLAPPING_ONLY, which unions overlapping intervals but keeps abutting intervals separate.

Parameters:

parser - Genome loc parser for the intervals.

intervals - A collection of intervals to merge.

mergingRule - A descriptor for the type of merging to perform.

Returns:

A sorted, merged version of the intervals passed in.

equateIntervals

public static java.lang.String equateIntervals(java.util.List<GenomeLoc> masterArg,
                                               java.util.List<GenomeLoc> testArg)

computes whether the test interval list is equivalent to master. To be equivalent, test must contain GenomeLocs covering every base in master, exactly once. Note that this algorithm assumes that master genomelocs are all discontiguous (i.e., we don't have locs like 1-3 and 4-6 but rather just 1-6). In order to use this algorithm with contiguous genomelocs first merge them. The algorithm doesn't assume that test has discontinuous genomelocs. Returns a null string if there are no differences, otherwise returns a string describing the difference (useful for UnitTests). Assumes both lists are sorted

Parameters:

masterArg - sorted master genome locs

testArg - sorted test genome locs

Returns:

null string if there are no difference, otherwise a string describing the difference

isIntervalFile

public static boolean isIntervalFile(java.lang.String str)

Check if string argument was intended as a file Accepted file extensions: .bed .list, .picard, .interval_list, .intervals.

Parameters:

str - token to identify as a filename.

Returns:

true if the token looks like a filename, or false otherwise.

isIntervalFile

public static boolean isIntervalFile(java.lang.String str,
                                     boolean checkExists)

Check if string argument was intended as a file Accepted file extensions are defined in INTERVAL_FILE_EXTENSIONS

Parameters:

str - token to identify as a filename.

checkExists - if true throws an exception if the file doesn't exist and has an interval file extension

Returns:

true if the token looks like an interval file name, or false otherwise.

getContigSizes

public static java.util.Map<java.lang.String,java.lang.Integer> getContigSizes(java.nio.file.Path reference)

Returns a map of contig names with their sizes.

Parameters:

reference - The reference for the intervals.

Returns:

A map of contig names with their sizes.

scatterContigIntervals

public static void scatterContigIntervals(htsjdk.samtools.SAMFileHeader fileHeader,
                                          java.util.List<GenomeLoc> locs,
                                          java.util.List<java.io.File> scatterParts)

Splits an interval list into multiple files.

Parameters:

fileHeader - The sam file header.

locs - The genome locs to split.

scatterParts - The output interval lists to write to.

splitIntervalsToSubLists

public static java.util.List<java.util.List<GenomeLoc>> splitIntervalsToSubLists(java.util.List<GenomeLoc> locs,
                                                                                 java.util.List<java.lang.Integer> splits)

Splits an interval list into multiple sublists.

Parameters:

locs - The genome locs to split.

splits - The stop points for the genome locs returned by splitFixedIntervals.

Returns:

A list of lists of genome locs, split according to splits

scatterFixedIntervals

public static void scatterFixedIntervals(htsjdk.samtools.SAMFileHeader fileHeader,
                                         java.util.List<java.util.List<GenomeLoc>> splits,
                                         java.util.List<java.io.File> scatterParts)

Splits an interval list into multiple files.

Parameters:

fileHeader - The sam file header.

splits - Pre-divided genome locs returned by splitFixedIntervals.

scatterParts - The output interval lists to write to.

splitFixedIntervals

public static java.util.List<java.util.List<GenomeLoc>> splitFixedIntervals(java.util.List<GenomeLoc> locs,
                                                                            int numParts)

Splits the genome locs up by size.

Parameters:

locs - Genome locs to split.

numParts - Number of parts to split the locs into.

Returns:

The stop points to split the genome locs.

splitLocusIntervals

public static java.util.List<java.util.List<GenomeLoc>> splitLocusIntervals(java.util.List<GenomeLoc> locs,
                                                                            int numParts)

overlaps

public static boolean overlaps(htsjdk.samtools.util.Locatable left,
                               htsjdk.samtools.util.Locatable right)

Check whether two locatables overlap.

Two locatables overlap if the share the same contig and they have at least one base in common based on their start and end positions.

This method returns false if either input Locatable has a null contig.

Parameters:

left - first locatable.

right - second locatable.

Returns:

true iff there is an overlap between both locatables.

Throws:

java.lang.IllegalArgumentException - if either left or right locatable is null.

locatableToString

public static java.lang.String locatableToString(htsjdk.samtools.util.Locatable interval)

flattenSplitIntervals

public static java.util.List<GenomeLoc> flattenSplitIntervals(java.util.List<java.util.List<GenomeLoc>> splits)

mergeIntervalLocations

public static java.util.List<GenomeLoc> mergeIntervalLocations(java.util.List<GenomeLoc> raw,
                                                               IntervalMergingRule rule)

merge a list of genome locs that may be overlapping, returning the list of unique genomic locations

Parameters:

raw - the unchecked genome loc list

rule - the merging rule we're using

Returns:

the list of merged locations

intervalSize

public static long intervalSize(java.util.List<GenomeLoc> locs)

getIntervalsWithFlanks

public static java.util.List<GenomeLoc> getIntervalsWithFlanks(GenomeLocParser parser,
                                                               java.util.List<GenomeLoc> locs,
                                                               int basePairs)

Returns a list of intervals between the passed int locs. Does not extend UNMAPPED locs.

Parameters:

parser - A genome loc parser for creating the new intervals

locs - Original genome locs

basePairs - Number of base pairs on each side of loc

Returns:

The list of intervals between the locs

getIntervalsWithFlanks

public static java.util.List<SimpleInterval> getIntervalsWithFlanks(java.util.List<SimpleInterval> intervals,
                                                                    int basePairs,
                                                                    htsjdk.samtools.SAMSequenceDictionary dictionary)

Pads the provided intervals by the specified amount, sorts the resulting intervals, and merges intervals that are adjacent/overlapping after padding.

Parameters:

intervals - intervals to pad

basePairs - number of bases of padding to add to each side of each interval

dictionary - sequence dictionary used to restrict padded intervals to the bounds of their contig

Returns:

the provided intervals padded by the specified amount, sorted, with adjacent/overlapping intervals merged

groupIntervalsByContig

public static java.util.List<java.util.List<SimpleInterval>> groupIntervalsByContig(java.util.List<SimpleInterval> sortedIntervals)

Accepts a sorted List of intervals, and returns a List of Lists of intervals grouped by contig, one List per contig.

Parameters:

sortedIntervals - sorted List of intervals to group by contig

Returns:

A List of Lists of intervals, one List per contig

genomeLocsFromLocatables

public static java.util.List<GenomeLoc> genomeLocsFromLocatables(GenomeLocParser parser,
                                                                 java.util.Collection<? extends htsjdk.samtools.util.Locatable> locatables)

Generates a list of GenomeLoc instances given the appropriate GenomeLocParser factory and a collection of Locatable instances.

The order in the result list is will correspond to the traversal order in the input collection.

Parameters:

locatables - input locatable collection.

Returns:

never null. The result is an unmodifiable list.

Throws:

java.lang.IllegalArgumentException - if locatable is null or contains any null.

getAllIntervalsForReference

public static java.util.List<SimpleInterval> getAllIntervalsForReference(htsjdk.samtools.SAMSequenceDictionary sequenceDictionary)

Builds a list of intervals that cover the whole given sequence.

getResolvedIntervals

public static java.util.List<SimpleInterval> getResolvedIntervals(java.lang.String intervalQueryString,
                                                                  htsjdk.samtools.SAMSequenceDictionary sequenceDictionary)

Given an interval query string and a sequence dictionary, determine if the query string can be resolved as a valid interval query against more than one contig in the dictionary, i.e., more than one of: prefix prefix:nnn prefix:nnn+ prefix:nnn-nnn and return the list of all possible interpretations (there can never be more than 2). Note that for an ambiguity to exist, the query string must contain at least one colon.

Parameters:

intervalQueryString -

sequenceDictionary -

Returns:

List containing 0, 1, or 2 valid interpretations of {code queryString} given sequenceDictionary. If the list is empty, the query doesn't match any contig in the sequence dictionary. If the list contains more than one interval, the query string is ambiguous and should be rejected. If the list contains a single interval, the query is unambiguous and can be safely used to conduct a query.

Throws:

java.lang.NumberFormatException - if the query only matches a single contig in the dictionary, but the query interval paramaters (start, end) cannot be parsed

trimIntervalToContig

public static SimpleInterval trimIntervalToContig(java.lang.String contig,
                                                  int start,
                                                  int stop,
                                                  int contigLength)

Create a new interval, bounding start and stop by the start and end of contig This function will return null if start and stop cannot be adjusted in any reasonable way to be on the contig. For example, if start and stop are both past the end of the contig, there's no way to fix this, and null will be returned.

Parameters:

contig - our contig

start - our start as an arbitrary integer (may be negative, etc)

stop - our stop as an arbitrary integer (may be negative, etc)

contigLength - length of the contig

Returns:

a valid interval over contig, or null if a meaningful interval cannot be created

intervalIsOnDictionaryContig

public static boolean intervalIsOnDictionaryContig(SimpleInterval interval,
                                                   htsjdk.samtools.SAMSequenceDictionary dictionary)

Determines whether the provided interval is within the bounds of its assigned contig according to the provided dictionary

Parameters:

interval - interval to check

dictionary - dictionary to use to validate contig bounds

Returns:

true if the interval's contig exists in the dictionary, and the interval is within its bounds, otherwise false

cutToShards

public static java.util.List<SimpleInterval> cutToShards(java.lang.Iterable<SimpleInterval> intervals,
                                                         int shardSize)

Splits the given input intervals into shards of at most the requested size. The shard boundaries lie at integer multiples of shardSize. chr2:1-200 -> chr2:1-100,chr2:101-200 This method will return all intervals in RAM. If you need a solution that is light on RAM usage, though it returns an iterator, see ShardedIntervalIterator

shardIndex

public static int shardIndex(int oneBasedOffset,
                             int shardSize)

number of the shard this offset is in. Shards are numbered starting at zero.

beginOfShard

public static int beginOfShard(int shardIndex,
                               int shardSize)

first offset in this shard (1-based).

endOfShard

public static int endOfShard(int shardIndex,
                             int shardSize)

last offset in this shard (1-based).

getSpanningIntervals

public static java.util.List<SimpleInterval> getSpanningIntervals(java.util.List<? extends htsjdk.samtools.util.Locatable> locations,
                                                                  htsjdk.samtools.SAMSequenceDictionary sequenceDictionary)

Get a single interval per contig that includes all of the specified intervals (This is used to improve GenomicsDB performance for exomes)

Parameters:

locations - the intervals to be merged/spanned

sequenceDictionary - for contig sorting

Returns:

a sorted list intervals containing the input intervals, one per contig

combineAndSortBreakpoints

public static <T extends htsjdk.samtools.util.Locatable> java.util.List<htsjdk.samtools.util.Locatable> combineAndSortBreakpoints(java.util.List<T> unsortedLocatables1,
                                                                                                                                  java.util.List<T> unsortedLocatables2,
                                                                                                                                  htsjdk.samtools.SAMSequenceDictionary dictionary)

Combine the breakpoints of multiple intervals and return a list of locatables based on the updated breakpoints. Suppose we have two lists of locatables: List 1:

     1  1000  2000
 

List 2:

     1  500  2500
     1  2501  3000
     1  4000  5000
 

The result would be:

     1  500  999
     1  1000  2000
     1  2001  2500
     1  2501  3000
     1  4000  5000
 

Note that start breakpoints will always appear as starts of the resulting intervals.

Does not alter the input.

Any single list of input locatables containing duplicates or overlapping intervals will throw an exception. Intervals are assumed to include the start and end bases. This method performs all necessary sorting.

Parameters:

unsortedLocatables1 - list of locatables

unsortedLocatables2 - list of locatables

dictionary - Sequence dictionary to base the sort. The order of contigs/sequences in the dictionary is the order of the sorting here.

Returns:

Locatables from the combined breakpoints of unsortedLocatables1 and unsortedLocatables2. If both inputs are null, return an empty list. Please note that returned values are new copies. If exactly one of the inputs is null, this method returns a copy of of the non-null input.

validateNoOverlappingIntervals

public static <T extends htsjdk.samtools.util.Locatable> void validateNoOverlappingIntervals(java.util.List<T> locatables)

Throws Bad Input exception if any overlaps are detected within the list of locatables.

Type Parameters:

T - Locatable class

Parameters:

locatables - List of locatables to test. null will never throw an exception.

sortLocatablesBySequenceDictionary

public static <T extends htsjdk.samtools.util.Locatable> java.util.List<T> sortLocatablesBySequenceDictionary(java.util.Collection<T> locatables,
                                                                                                              htsjdk.samtools.SAMSequenceDictionary dictionary)

Sort by the contig then position as specified by the index order in the given sequence dictionary.

Type Parameters:

T - Locatable

Parameters:

locatables - list of locatables.

dictionary - Never null

Returns:

new list that is sorted using the sequence index of the given dictionary. Returns null if locatables is null. Instances in the list are not copies of input.

createOverlapMap

public static <T extends htsjdk.samtools.util.Locatable,U extends htsjdk.samtools.util.Locatable> java.util.Map<T,java.util.List<U>> createOverlapMap(java.util.List<T> keys,
                                                                                                                                                      java.util.List<U> vals,
                                                                                                                                                      htsjdk.samtools.SAMSequenceDictionary dictionary)

Creates a map of which locatables (keys) overlap the other list of locatables (vals) Input lists will be sorted sorted by the input dictionary. Within a single input list, segments cannot overlap (or duplicate). If this occurs, an exception is thrown. No copies of inputs are created.

Parameters:

keys - -- the intervals we wish to query. Sorted by interval. No intervals overlap. Never null

vals - -- the intervals that we wish to map to the keys. Sorted by interval. No intervals overlap. Never null

dictionary - -- the SAMSequenceDictionary that the intervals (and sorting) derive from. Never null

Returns:

a mapping of intervals from keys to the list of overlapping intervals in vals. All item in keys will have a key. Never null

getDictionaryOrderComparator

public static java.util.Comparator<htsjdk.samtools.util.Locatable> getDictionaryOrderComparator(htsjdk.samtools.SAMSequenceDictionary dictionary)

The order of contigs/sequences in the dictionary is the order of the sorting here.

Parameters:

dictionary - dictionary to use for the sorting. Intervals with sequences not in this dictionary will cause exceptions to be thrown. Never null.

Returns:

an instance of Comapator<Locatable> for use in sorting of Locatables.

isReciprocalOverlap

public static boolean isReciprocalOverlap(SimpleInterval interval1,
                                          SimpleInterval interval2,
                                          double reciprocalOverlapThreshold)

Determine whether the two intervals specified overlap each other by at least the threshold proportion specified. This is a commutative operation.

Parameters:

interval1 - Never null

interval2 - Never null

reciprocalOverlapThreshold - proportion of the segments that must overlap. Must be between 0.0 and 1.0 (inclusive).

Returns:

whether there is a reciprocal overlap exceeding the given threshold. If reciprocalOverlapThreshold is 0, always returns true, even if intervals do not overlap.