org.broadinstitute.hellbender.utils

Class GenomeLocParser

java.lang.Object

org.broadinstitute.hellbender.utils.GenomeLocParser

public final class GenomeLocParser
extends java.lang.Object

Factory class for creating GenomeLocs

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	GenomeLocParser.ValidationLevel How much validation should we do at runtime with this parser?

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	UNMAPPED_LOC_NAME

Constructor Summary

Constructors

Modifier	Constructor and Description
	GenomeLocParser(htsjdk.samtools.reference.ReferenceSequenceFile refFile) set our internal reference contig order
	GenomeLocParser(htsjdk.samtools.SAMSequenceDictionary seqDict) Create a new GenomeLocParser based on seqDictionary with the standard validation level
protected	GenomeLocParser(htsjdk.samtools.SAMSequenceDictionary seqDict, GenomeLocParser.ValidationLevel validationLevel) Create a genome loc parser based on seqDict with the specified level of validation

Method Summary

Modifier and Type	Method and Description
boolean	contigIsInDictionary(java.lang.String contig) Determines whether the given contig is valid with respect to the sequence dictionary already installed in the GenomeLoc.
GenomeLoc	createGenomeLoc(htsjdk.tribble.Feature feature) Creates a GenomeLoc from a Tribble feature
GenomeLoc	createGenomeLoc(GATKRead read)
GenomeLoc	createGenomeLoc(htsjdk.samtools.util.Locatable locatable) Creates a GenomeLoc from a Locatable.
GenomeLoc	createGenomeLoc(java.lang.String contig, int pos) Create a new GenomeLoc, on contig, including the single position pos.
GenomeLoc	createGenomeLoc(java.lang.String contig, int start, int stop)
GenomeLoc	createGenomeLoc(java.lang.String contig, int start, int stop, boolean mustBeOnReference)
GenomeLoc	createGenomeLoc(java.lang.String contig, int index, int start, int stop)
GenomeLoc	createGenomeLoc(java.lang.String contig, int index, int start, int stop, boolean mustBeOnReference) Create a GenomeLoc on contig, starting at start and ending (inclusive) at stop.
GenomeLoc	createGenomeLocAtStart(GenomeLoc loc, int maxBasePairs) Creates a loc to the left (starting at the loc start + 1) of maxBasePairs size.
GenomeLoc	createGenomeLocAtStop(GenomeLoc loc, int maxBasePairs) Creates a loc to the right (starting at the loc stop + 1) of maxBasePairs size.
GenomeLoc	createGenomeLocOnContig(java.lang.String contig, int start, int stop)
GenomeLoc	createGenomeLocOnContig(java.lang.String contig, int contigIndex, int start, int stop) Create a new genome loc, 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.
GenomeLoc	createOverEntireContig(java.lang.String contigName) Creates a GenomeLoc than spans the entire contig.
GenomeLoc	createPaddedGenomeLoc(GenomeLoc loc, int padding) Creates a loc padded in both directions by maxBasePairs size (if possible).
int	getContigIndex(java.lang.String contig) Returns the contig index of a specified string version of the contig
protected int	getContigIndexWithoutException(java.lang.String contig)
htsjdk.samtools.SAMSequenceRecord	getContigInfo(java.lang.String contig) get the contig's SAMSequenceRecord
htsjdk.samtools.SAMSequenceDictionary	getSequenceDictionary() Return the master sequence dictionary used within this GenomeLocParser
static boolean	isUnmappedGenomeLocString(java.lang.String str)
boolean	isValidGenomeLoc(java.lang.String contig, int start, int stop)
boolean	isValidGenomeLoc(java.lang.String contig, int start, int stop, boolean mustBeOnReference) Would a genome loc created with the given parameters be valid w.r.t.
GenomeLoc	parseGenomeLoc(java.lang.String rawStr) parse a genome interval, from a location string Performs interval-style validation: contig is valid; start and stop less than the end; start <= stop, and start/stop are on the contig
protected java.lang.String	validateGenomeLoc(java.lang.String contig, int contigIndex, int start, int stop, boolean mustBeOnReference) validate a position or interval on the genome as valid Requires that contig exist in the master sequence dictionary, and that contig index be valid as well.

Methods inherited from class java.lang.Object

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

Field Detail

UNMAPPED_LOC_NAME

public static final java.lang.String UNMAPPED_LOC_NAME

See Also:

Constant Field Values

Constructor Detail

GenomeLocParser

public GenomeLocParser(htsjdk.samtools.reference.ReferenceSequenceFile refFile)

set our internal reference contig order

Parameters:

refFile - the reference file

GenomeLocParser

public GenomeLocParser(htsjdk.samtools.SAMSequenceDictionary seqDict)

Create a new GenomeLocParser based on seqDictionary with the standard validation level

Parameters:

seqDict - a non-null sequence dictionary

GenomeLocParser

protected GenomeLocParser(htsjdk.samtools.SAMSequenceDictionary seqDict,
                          GenomeLocParser.ValidationLevel validationLevel)

Create a genome loc parser based on seqDict with the specified level of validation

Parameters:

seqDict - the sequence dictionary to use when creating genome locs

validationLevel - how much validation should we do of the genome locs at runtime? Purely for testing purposes

Method Detail

contigIsInDictionary

public final boolean contigIsInDictionary(java.lang.String contig)

Determines whether the given contig is valid with respect to the sequence dictionary already installed in the GenomeLoc.

Parameters:

contig - a potentially null string name for the contig

Returns:

True if the contig is valid. False otherwise.

getContigInfo

public final htsjdk.samtools.SAMSequenceRecord getContigInfo(java.lang.String contig)

get the contig's SAMSequenceRecord

Parameters:

contig - the string name of the contig

Returns:

the sam sequence record

getContigIndex

public final int getContigIndex(java.lang.String contig)

Returns the contig index of a specified string version of the contig

Parameters:

contig - the contig string

Returns:

the contig index, -1 if not found

getContigIndexWithoutException

protected int getContigIndexWithoutException(java.lang.String contig)

getSequenceDictionary

public final htsjdk.samtools.SAMSequenceDictionary getSequenceDictionary()

Return the master sequence dictionary used within this GenomeLocParser

Returns:

createGenomeLoc

public GenomeLoc createGenomeLoc(java.lang.String contig,
                                 int start,
                                 int stop)

See Also:

for exact details of the creation. Note that because this function doesn't take the contig index as an argument for contig, it has a slight performance penalty over the version that does take the contig index. Does not require the created genome loc on the reference genome

createGenomeLoc

public GenomeLoc createGenomeLoc(java.lang.String contig,
                                 int start,
                                 int stop,
                                 boolean mustBeOnReference)

See Also:

for exact details of the creation. Note that because this function doesn't take the contig index as an argument for contig, it has a slight performance penalty over the version that does take the contig index.

createGenomeLoc

public GenomeLoc createGenomeLoc(java.lang.String contig,
                                 int index,
                                 int start,
                                 int stop)

See Also:

for exact details of the creation. Doesn't require the start and stop to be on the genome

createGenomeLoc

public GenomeLoc createGenomeLoc(java.lang.String contig,
                                 int index,
                                 int start,
                                 int stop,
                                 boolean mustBeOnReference)

Create a GenomeLoc on contig, starting at start and ending (inclusive) at stop.

Parameters:

contig - the contig name

index - the index into the GATK's SAMSequencingDictionary of contig (passed for efficiency to avoid the lookup)

start - the starting position

stop - the stop position of this loc, inclusive

mustBeOnReference - if true, this factory will throw a UserException.MalformedGenomeLoc if start or stop isn't on the contig

Returns:

a non-null GenomeLoc

createGenomeLoc

public GenomeLoc createGenomeLoc(java.lang.String contig,
                                 int pos)

Create a new GenomeLoc, on contig, including the single position pos. Pos is not required to be on the reference

Parameters:

contig - the contig name

pos - the start and stop of the created genome loc

Returns:

a genome loc representing a single base at the specified postion on the contig

See Also:

for exact details of the creation.

validateGenomeLoc

protected java.lang.String validateGenomeLoc(java.lang.String contig,
                                             int contigIndex,
                                             int start,
                                             int stop,
                                             boolean mustBeOnReference)

validate a position or interval on the genome as valid Requires that contig exist in the master sequence dictionary, and that contig index be valid as well. Requires that start <= stop. if mustBeOnReference is true, performs boundary validation for genome loc INTERVALS: start and stop are on contig and start <= stop

Parameters:

contig - the contig name

start - the start position

stop - the stop position

Returns:

the interned contig name, an optimization that ensures that contig == the string in the sequence dictionary

isValidGenomeLoc

public boolean isValidGenomeLoc(java.lang.String contig,
                                int start,
                                int stop,
                                boolean mustBeOnReference)

Would a genome loc created with the given parameters be valid w.r.t. the master sequence dictionary?

Parameters:

contig - the contig we'd use

start - the start position

stop - the stop

mustBeOnReference - should we require the resulting genome loc to be completely on the reference genome?

Returns:

true if this would produce a valid genome loc, false otherwise

isValidGenomeLoc

public boolean isValidGenomeLoc(java.lang.String contig,
                                int start,
                                int stop)

See Also:

with mustBeOnReference == true

parseGenomeLoc

public GenomeLoc parseGenomeLoc(java.lang.String rawStr)

parse a genome interval, from a location string Performs interval-style validation: contig is valid; start and stop less than the end; start <= stop, and start/stop are on the contig

Parameters:

rawStr - the string to parse

Returns:

a GenomeLoc representing the String

isUnmappedGenomeLocString

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

Parameters:

str - String to check

Returns:

true if str equals UNMAPPED_LOC_NAME (ignoring case)

createGenomeLoc

public GenomeLoc createGenomeLoc(GATKRead read)

createGenomeLoc

public GenomeLoc createGenomeLoc(htsjdk.tribble.Feature feature)

Creates a GenomeLoc from a Tribble feature

Parameters:

feature -

Returns:

createGenomeLoc

public GenomeLoc createGenomeLoc(htsjdk.samtools.util.Locatable locatable)

Creates a GenomeLoc from a Locatable.

Parameters:

locatable - the input locatable.

Returns:

never null.

Throws:

java.lang.IllegalArgumentException - if locatable is null.

createOverEntireContig

public GenomeLoc createOverEntireContig(java.lang.String contigName)

Creates a GenomeLoc than spans the entire contig.

Parameters:

contigName - Name of the contig.

Returns:

A locus spanning the entire contig.

createGenomeLocAtStart

public GenomeLoc createGenomeLocAtStart(GenomeLoc loc,
                                        int maxBasePairs)

Creates a loc to the left (starting at the loc start + 1) of maxBasePairs size.

Parameters:

loc - The original loc

maxBasePairs - The maximum number of basePairs

Returns:

The contiguous loc of up to maxBasePairs length or null if the loc is already at the start of the contig.

createPaddedGenomeLoc

public GenomeLoc createPaddedGenomeLoc(GenomeLoc loc,
                                       int padding)

Creates a loc padded in both directions by maxBasePairs size (if possible).

Parameters:

loc - The original loc

padding - The number of base pairs to pad on either end

Returns:

The contiguous loc of length up to the original length + 2*padding (depending on the start/end of the contig).

createGenomeLocAtStop

public GenomeLoc createGenomeLocAtStop(GenomeLoc loc,
                                       int maxBasePairs)

Creates a loc to the right (starting at the loc stop + 1) of maxBasePairs size.

Parameters:

loc - The original loc

maxBasePairs - The maximum number of basePairs

Returns:

The contiguous loc of up to maxBasePairs length or null if the loc is already at the end of the contig.

createGenomeLocOnContig

public GenomeLoc createGenomeLocOnContig(java.lang.String contig,
                                         int start,
                                         int stop)

See Also:

with the contig index looked up from contig

createGenomeLocOnContig

public GenomeLoc createGenomeLocOnContig(java.lang.String contig,
                                         int contigIndex,
                                         int start,
                                         int stop)

Create a new genome loc, 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)

Returns:

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