ReadLikelihoods (gatk 4.0.5.0 API)

java.lang.Object
- org.broadinstitute.hellbender.utils.genotyper.ReadLikelihoods<A>

Type Parameters:

A - the type of the allele the likelihood makes reference to. Note: this class uses FastUtil collections for speed.

All Implemented Interfaces:

AlleleList<A>, SampleList

Direct Known Subclasses:

UnfilledReadsLikelihoods
```
public class ReadLikelihoods<A extends htsjdk.variant.variantcontext.Allele>
extends java.lang.Object
implements SampleList, AlleleList<A>
```
Read-likelihoods container implementation based on integer indexed arrays.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

class ReadLikelihoods.BestAllele
Contains information about the best allele for a read search result.
- Nested classes/interfaces inherited from interface org.broadinstitute.hellbender.utils.genotyper.AlleleList
  AlleleList.ActualPermutation<A extends htsjdk.variant.variantcontext.Allele>, AlleleList.NonPermutation<A extends htsjdk.variant.variantcontext.Allele>

Nested Classes
Modifier and Type	Class and Description
`class`	`ReadLikelihoods.BestAllele` Contains information about the best allele for a read search result.

Field Summary

Fields
Modifier and Type	Field and Description
`protected AlleleList<A>`	`alleles` Allele list
`protected GATKRead[][]`	`readsBySampleIndex` Reads by sample index.
`protected SampleList`	`samples` Sample list
`protected double[][][]`	`valuesBySampleIndex` Indexed per sample, allele and finally read (within sample).

Fields inherited from interface org.broadinstitute.hellbender.utils.genotyper.SampleList
EMPTY_LIST

Fields inherited from interface org.broadinstitute.hellbender.utils.genotyper.AlleleList
EMPTY_LIST

Constructor Summary

Constructors
Constructor and Description
`ReadLikelihoods(SampleList samples, AlleleList<A> alleles, java.util.Map<java.lang.String,java.util.List<GATKRead>> reads)` Constructs a new read-likelihood collection.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`addMissingAlleles(java.util.Collection<A> candidateAlleles, double defaultLikelihood)` Add alleles that are missing in the read-likelihoods collection giving all reads a default likelihood value.
`void`	`addNonReferenceAllele(A nonRefAllele)` Adds the non-reference allele to the read-likelihood collection setting each read likelihood to the second best found (or best one if only one allele has likelihood).
`void`	`addReads(java.util.Map<java.lang.String,java.util.List<GATKRead>> readsBySample, double initialLikelihood)` Add more reads to the collection.
`java.util.List<A>`	`alleles()` Returns the samples in this read-likelihood collection.
`java.util.Collection<ReadLikelihoods.BestAllele>`	`bestAlleles()` Returns the collection of best allele estimates for the reads based on the read-likelihoods.
`java.util.Collection<ReadLikelihoods.BestAllele>`	`bestAlleles(java.lang.String sample)` Returns the collection of best allele estimates for one sample's reads based on the read-likelihoods.
`void`	`changeReads(java.util.Map<GATKRead,GATKRead> readRealignments)`
`void`	`contaminationDownsampling(java.util.Map<java.lang.String,java.lang.Double> perSampleDownsamplingFraction)` Downsamples reads based on contamination fractions making sure that all alleles are affected proportionally.
`void`	`filterPoorlyModeledReads(double maximumErrorPerBase)` Removes those read that the best possible likelihood given any allele is just too low.
`void`	`filterToOnlyOverlappingUnclippedReads(SimpleInterval location)` Remove those reads that do not overlap certain genomic location.
`A`	`getAllele(int alleleIndex)` Returns the allele given its index.
`java.lang.String`	`getSample(int sampleIndex)` Returns sample name given its index.
`java.util.Map<java.lang.String,java.util.List<PileupElement>>`	`getStratifiedPileups(htsjdk.samtools.util.Locatable loc)` Collect a map stratified per-sample of the base pileups at the provided Location NOTE: Since we shouldn't need to use the pileup if we have more reliable liklihoods, we want to discourage their use
`boolean`	`hasFilledLikelihoods()` Is this container expected to have the per-allele liklihoods calculations filled in.
`int`	`indexOfAllele(A allele)` Returns the index of an allele within the likelihood collection.
`int`	`indexOfSample(java.lang.String sample)` Returns the index of a sample within the likelihood collection.
`<B extends htsjdk.variant.variantcontext.Allele> ReadLikelihoods<B>`	`marginalize(java.util.Map<B,java.util.List<A>> newToOldAlleleMap)` Perform marginalization from an allele set to another (smaller one) taking the maximum value for each read in the original allele subset.
`<B extends htsjdk.variant.variantcontext.Allele> ReadLikelihoods<B>`	`marginalize(java.util.Map<B,java.util.List<A>> newToOldAlleleMap, htsjdk.samtools.util.Locatable overlap)` Perform marginalization from an allele set to another (smaller one) taking the maximum value for each read in the original allele subset.
`void`	`normalizeLikelihoods(boolean bestToZero, double maximumLikelihoodDifferenceCap)` Adjusts likelihoods so that for each read, the best allele likelihood is 0 and caps the minimum likelihood of any allele for each read based on the maximum alternative allele likelihood.
`int`	`numberOfAlleles()` Returns number of alleles in the collection.
`int`	`numberOfSamples()` Number of samples included in the likelihood collection.
`int`	`readCount()` Returns the total number of reads in the read-likelihood collection.
`void`	`removeSampleReads(int sampleIndex, java.util.Collection<GATKRead> readsToRemove, int alleleCount)`
`LikelihoodMatrix<A>`	`sampleMatrix(int sampleIndex)` Returns a read vs allele likelihood matrix corresponding to a sample.
`int`	`sampleReadCount(int sampleIndex)` Returns the number of reads that belong to a sample in the read-likelihood collection.
`java.util.List<GATKRead>`	`sampleReads(int sampleIndex)` Returns the reads that belong to a sample sorted by their index (within that sample).
`java.util.List<java.lang.String>`	`samples()` Returns the samples in this read-likelihood collection.
`static boolean`	`unclippedReadOverlapsRegion(GATKRead read, htsjdk.samtools.util.Locatable region)`
`void`	`updateNonRefAlleleLikelihoods()` Updates the likelihoods of the non-ref allele, if present, considering all non-symbolic alleles avaialble.
`void`	`updateNonRefAlleleLikelihoods(AlleleList<A> allelesToConsider)` Updates the likelihood of the NonRef allele (if present) based on the likelihoods of a set of non-symbolic

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.broadinstitute.hellbender.utils.genotyper.SampleList
asListOfSamples, asSetOfSamples, emptySampleList, equals, singletonSampleList

Methods inherited from interface org.broadinstitute.hellbender.utils.genotyper.AlleleList
asListOfAlleles, containsAllele, emptyAlleleList, equals, indexOfReference, permutation

- Field Detail
  - readsBySampleIndex
```
protected final GATKRead[][] readsBySampleIndex
```
    Reads by sample index. Each sub array contains reference to the reads of the ith sample.
  - valuesBySampleIndex
```
protected final double[][][] valuesBySampleIndex
```
    Indexed per sample, allele and finally read (within sample).
    valuesBySampleIndex[s][a][r] == lnLk(R_r | A_a) where R_r comes from Sample s.
  - samples
```
protected final SampleList samples
```
    Sample list
  - alleles
```
protected AlleleList<A extends htsjdk.variant.variantcontext.Allele> alleles
```
    Allele list
- Constructor Detail
  - ReadLikelihoods
```
public ReadLikelihoods(SampleList samples,
                       AlleleList<A> alleles,
                       java.util.Map<java.lang.String,java.util.List<GATKRead>> reads)
```
    Constructs a new read-likelihood collection.
    The initial likelihoods for all allele-read combinations are 0.
    
    Parameters:
    
    samples - all supported samples in the collection.
    
    alleles - all supported alleles in the collection.
    
    reads - reads stratified per sample.
    
    Throws:
    
    java.lang.IllegalArgumentException - if any of allele, samples or reads is null, or if they contain null values.
- Method Detail
  - hasFilledLikelihoods
```
public boolean hasFilledLikelihoods()
```
    Is this container expected to have the per-allele liklihoods calculations filled in.
  - indexOfSample
```
public int indexOfSample(java.lang.String sample)
```
    Returns the index of a sample within the likelihood collection.
    
    Specified by:
    
    indexOfSample in interface SampleList
    
    Parameters:
    
    sample - the query sample.
    
    Returns:
    
    -1 if the allele is not included, 0 or greater otherwise.
    
    Throws:
    
    java.lang.IllegalArgumentException - if sample is null.
  - numberOfSamples
```
public int numberOfSamples()
```
    Number of samples included in the likelihood collection.
    
    Specified by:
    
    numberOfSamples in interface SampleList
    
    Returns:
    
    0 or greater.
  - getSample
```
public java.lang.String getSample(int sampleIndex)
```
    Returns sample name given its index.
    
    Specified by:
    
    getSample in interface SampleList
    
    Parameters:
    
    sampleIndex - query index.
    
    Returns:
    
    never null.
    
    Throws:
    
    java.lang.IllegalArgumentException - if sampleIndex is negative.
  - indexOfAllele
```
public int indexOfAllele(A allele)
```
    Returns the index of an allele within the likelihood collection.
    
    Specified by:
    
    indexOfAllele in interface AlleleList<A extends htsjdk.variant.variantcontext.Allele>
    
    Parameters:
    
    allele - the query allele.
    
    Returns:
    
    -1 if the allele is not included, 0 or greater otherwise.
    
    Throws:
    
    java.lang.IllegalArgumentException - if allele is null.
  - numberOfAlleles
```
public int numberOfAlleles()
```
    Returns number of alleles in the collection.
    
    Specified by:
    
    numberOfAlleles in interface AlleleList<A extends htsjdk.variant.variantcontext.Allele>
    
    Returns:
    
    0 or greater.
  - getAllele
```
public A getAllele(int alleleIndex)
```
    Returns the allele given its index.
    
    Specified by:
    
    getAllele in interface AlleleList<A extends htsjdk.variant.variantcontext.Allele>
    
    Parameters:
    
    alleleIndex - the allele index.
    
    Returns:
    
    never null.
    
    Throws:
    
    java.lang.IllegalArgumentException - the allele index is null.
  - sampleReads
```
public java.util.List<GATKRead> sampleReads(int sampleIndex)
```
    Returns the reads that belong to a sample sorted by their index (within that sample).
    
    Parameters:
    
    sampleIndex - the requested sample.
    
    Returns:
    
    never null but perhaps a zero-length array if there is no reads in sample. No element in the array will be null.
  - sampleMatrix
```
public LikelihoodMatrix<A> sampleMatrix(int sampleIndex)
```
    Returns a read vs allele likelihood matrix corresponding to a sample.
    
    Parameters:
    
    sampleIndex - target sample.
    
    Returns:
    
    never null
    
    Throws:
    
    java.lang.IllegalArgumentException - if sampleIndex is not null.
  - normalizeLikelihoods
```
public void normalizeLikelihoods(boolean bestToZero,
                                 double maximumLikelihoodDifferenceCap)
```
    Adjusts likelihoods so that for each read, the best allele likelihood is 0 and caps the minimum likelihood of any allele for each read based on the maximum alternative allele likelihood.
    
    Parameters:
    
    bestToZero - set the best likelihood to 0, others will be subtracted the same amount.
    
    maximumLikelihoodDifferenceCap - maximum difference between the best alternative allele likelihood and any other likelihood.
    
    Throws:
    
    java.lang.IllegalArgumentException - if maximumDifferenceWithBestAlternative is not 0 or less.
  - samples
```
public java.util.List<java.lang.String> samples()
```
    Returns the samples in this read-likelihood collection.
    Samples are sorted by their index in the collection.
    
    The returned list is an unmodifiable view on the read-likelihoods sample list.
    
    Returns:
    
    never null.
  - alleles
```
public java.util.List<A> alleles()
```
    Returns the samples in this read-likelihood collection.
    Samples are sorted by their index in the collection.
    
    The returned list is an unmodifiable. It will not be updated if the collection allele list changes.
    
    Returns:
    
    never null.
  - changeReads
```
public void changeReads(java.util.Map<GATKRead,GATKRead> readRealignments)
```
  - addMissingAlleles
```
public boolean addMissingAlleles(java.util.Collection<A> candidateAlleles,
                                 double defaultLikelihood)
```
    Add alleles that are missing in the read-likelihoods collection giving all reads a default likelihood value.
    
    Parameters:
    
    candidateAlleles - the potentially missing alleles.
    
    defaultLikelihood - the default read likelihood value for that allele.
    
    Returns:
    
    true iff the the read-likelihood collection was modified by the addition of the input alleles. So if all the alleles in the input collection were already present in the read-likelihood collection this method will return false.
    
    Throws:
    
    java.lang.IllegalArgumentException - if candidateAlleles is null or there is more than one missing allele that is a reference or there is one but the collection already has a reference allele.
  - marginalize
```
public <B extends htsjdk.variant.variantcontext.Allele> ReadLikelihoods<B> marginalize(java.util.Map<B,java.util.List<A>> newToOldAlleleMap)
```
    Perform marginalization from an allele set to another (smaller one) taking the maximum value for each read in the original allele subset.
    
    Parameters:
    
    newToOldAlleleMap - map where the keys are the new alleles and the value list the original alleles that correspond to the new one.
    
    Returns:
    
    never null. The result will have the requested set of new alleles (keys in newToOldAlleleMap, and the same set of samples and reads as the original.
    
    Throws:
    
    java.lang.IllegalArgumentException - is newToOldAlleleMap is null or contains null values, or its values contain reference to non-existing alleles in this read-likelihood collection. Also no new allele can have zero old alleles mapping nor two new alleles can make reference to the same old allele.
  - marginalize
```
public <B extends htsjdk.variant.variantcontext.Allele> ReadLikelihoods<B> marginalize(java.util.Map<B,java.util.List<A>> newToOldAlleleMap,
                                                                                       htsjdk.samtools.util.Locatable overlap)
```
    Perform marginalization from an allele set to another (smaller one) taking the maximum value for each read in the original allele subset.
    
    Parameters:
    
    newToOldAlleleMap - map where the keys are the new alleles and the value list the original alleles that correspond to the new one.
    
    overlap - if not null, only reads that overlap the location (with unclipping) will be present in the output read-collection.
    
    Returns:
    
    never null. The result will have the requested set of new alleles (keys in newToOldAlleleMap, and the same set of samples and reads as the original.
    
    Throws:
    
    java.lang.IllegalArgumentException - is newToOldAlleleMap is null or contains null values, or its values contain reference to non-existing alleles in this read-likelihood collection. Also no new allele can have zero old alleles mapping nor two new alleles can make reference to the same old allele.
  - unclippedReadOverlapsRegion
```
public static boolean unclippedReadOverlapsRegion(GATKRead read,
                                                  htsjdk.samtools.util.Locatable region)
```
  - filterPoorlyModeledReads
```
public void filterPoorlyModeledReads(double maximumErrorPerBase)
```
    Removes those read that the best possible likelihood given any allele is just too low.
    This is determined by a maximum error per read-base against the best likelihood possible.
    
    Parameters:
    
    maximumErrorPerBase - the minimum acceptable error rate per read base, must be a positive number.
    
    Throws:
    
    java.lang.IllegalStateException - is not supported for read-likelihood that do not contain alleles.
    
    java.lang.IllegalArgumentException - if maximumErrorPerBase is negative.
  - addReads
```
public void addReads(java.util.Map<java.lang.String,java.util.List<GATKRead>> readsBySample,
                     double initialLikelihood)
```
    Add more reads to the collection.
    
    Parameters:
    
    readsBySample - reads to add.
    
    initialLikelihood - the likelihood for the new entries.
    
    Throws:
    
    java.lang.IllegalArgumentException - if readsBySample is null or readsBySample contains null reads, or readsBySample contains read that are already present in the read-likelihood collection.
  - addNonReferenceAllele
```
public void addNonReferenceAllele(A nonRefAllele)
```
    Adds the non-reference allele to the read-likelihood collection setting each read likelihood to the second best found (or best one if only one allele has likelihood).
    Nothing will happen if the read-likelihoods collection already includes the non-ref allele
    
    Implementation note: even when strictly speaking we do not need to demand the calling code to pass the reference the non-ref allele, we still demand it in order to lead the the calling code to use the right generic type for this likelihoods collection Allele.
    
    Parameters:
    
    nonRefAllele - the non-ref allele.
    
    Throws:
    
    java.lang.IllegalArgumentException - if nonRefAllele is anything but the designated <NON_REF> symbolic allele Allele.NON_REF_ALLELE.
  - updateNonRefAlleleLikelihoods
```
public void updateNonRefAlleleLikelihoods()
```
    Updates the likelihoods of the non-ref allele, if present, considering all non-symbolic alleles avaialble.
  - updateNonRefAlleleLikelihoods
```
public void updateNonRefAlleleLikelihoods(AlleleList<A> allelesToConsider)
```
    Updates the likelihood of the NonRef allele (if present) based on the likelihoods of a set of non-symbolic
    This method does
    
    Parameters:
    
    allelesToConsider -
  - contaminationDownsampling
```
public void contaminationDownsampling(java.util.Map<java.lang.String,java.lang.Double> perSampleDownsamplingFraction)
```
    Downsamples reads based on contamination fractions making sure that all alleles are affected proportionally.
    
    Parameters:
    
    perSampleDownsamplingFraction - contamination sample map where the sample name are the keys and the fractions are the values.
    
    Throws:
    
    java.lang.IllegalArgumentException - if perSampleDownsamplingFraction is null.
  - bestAlleles
```
public java.util.Collection<ReadLikelihoods.BestAllele> bestAlleles()
```
    Returns the collection of best allele estimates for the reads based on the read-likelihoods.
    
    Returns:
    
    never null, one element per read in the read-likelihoods collection.
    
    Throws:
    
    java.lang.IllegalStateException - if there is no alleles.
  - bestAlleles
```
public java.util.Collection<ReadLikelihoods.BestAllele> bestAlleles(java.lang.String sample)
```
    Returns the collection of best allele estimates for one sample's reads based on the read-likelihoods.
    
    Returns:
    
    never null, one element per read in the read-likelihoods collection.
    
    Throws:
    
    java.lang.IllegalStateException - if there is no alleles.
  - readCount
```
public int readCount()
```
    Returns the total number of reads in the read-likelihood collection.
    
    Returns:
    
    never null
  - sampleReadCount
```
public int sampleReadCount(int sampleIndex)
```
    Returns the number of reads that belong to a sample in the read-likelihood collection.
    
    Parameters:
    
    sampleIndex - the query sample index.
    
    Returns:
    
    0 or greater.
    
    Throws:
    
    java.lang.IllegalArgumentException - if sampleIndex is not a valid sample index.
  - filterToOnlyOverlappingUnclippedReads
```
public void filterToOnlyOverlappingUnclippedReads(SimpleInterval location)
```
    Remove those reads that do not overlap certain genomic location.
    This method modifies the current read-likelihoods collection.
    
    Parameters:
    
    location - the target location.
    
    Throws:
    
    java.lang.IllegalArgumentException - the location cannot be null nor unmapped.
  - removeSampleReads
```
public void removeSampleReads(int sampleIndex,
                              java.util.Collection<GATKRead> readsToRemove,
                              int alleleCount)
```
  - getStratifiedPileups
```
public java.util.Map<java.lang.String,java.util.List<PileupElement>> getStratifiedPileups(htsjdk.samtools.util.Locatable loc)
```
    Collect a map stratified per-sample of the base pileups at the provided Location NOTE: Since we shouldn't need to use the pileup if we have more reliable liklihoods, we want to discourage their use
    
    Parameters:
    
    loc - reference location to construct pileups for
    
    Returns:

Class ReadLikelihoods<A extends htsjdk.variant.variantcontext.Allele>

Nested Class Summary

Nested classes/interfaces inherited from interface org.broadinstitute.hellbender.utils.genotyper.AlleleList

Field Summary

Fields inherited from interface org.broadinstitute.hellbender.utils.genotyper.SampleList

Fields inherited from interface org.broadinstitute.hellbender.utils.genotyper.AlleleList

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface org.broadinstitute.hellbender.utils.genotyper.SampleList

Methods inherited from interface org.broadinstitute.hellbender.utils.genotyper.AlleleList

Field Detail

readsBySampleIndex

valuesBySampleIndex

samples

alleles

Constructor Detail

ReadLikelihoods

Method Detail

hasFilledLikelihoods

indexOfSample

numberOfSamples

getSample

indexOfAllele

numberOfAlleles

getAllele

sampleReads

sampleMatrix

normalizeLikelihoods

samples

alleles

changeReads

addMissingAlleles

marginalize

marginalize

unclippedReadOverlapsRegion

filterPoorlyModeledReads

addReads

addNonReferenceAllele

updateNonRefAlleleLikelihoods

updateNonRefAlleleLikelihoods

contaminationDownsampling

bestAlleles

bestAlleles

readCount

sampleReadCount

filterToOnlyOverlappingUnclippedReads

removeSampleReads

getStratifiedPileups