QualityUtils (gatk 4.2.0.0 API)

java.lang.Object
- org.broadinstitute.hellbender.utils.QualityUtils

```
public final class QualityUtils
extends java.lang.Object
```
QualityUtils is a static class with some utility methods for manipulating quality scores. The definition of a Phred-scaled quality Q in terms of an error probability P(error) is: Q = -10 log_10 P(error), which implies log P(error) = Q * (-log(10)/10)

Field Summary

Fields
Modifier and Type	Field and Description
`static double`	`LOG_PROB_TO_PHRED_MULTIPLIER`
`static int`	`MAPPING_QUALITY_UNAVAILABLE`
`static int`	`MAX_QUAL` Maximum sense quality value.
`static byte`	`MAX_REASONABLE_Q_SCORE` bams containing quals above this value are extremely suspicious and we should warn the user
`static byte`	`MAX_SAM_QUAL_SCORE` Maximum quality score that can be encoded in a SAM/BAM file
`protected static double`	`MIN_PHRED_SCALED_QUAL`
`static byte`	`MIN_USABLE_Q_SCORE` The lowest quality score for a base that is considered reasonable for statistical analysis.
`static double`	`PHRED_TO_LOG_PROB_MULTIPLIER` conversion factor from phred scaled quality to log error probability and vice versa

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static byte`	`boundQual(int qual)` Return a quality score that bounds qual by MAX_SAM_QUAL_SCORE and 1
`static byte`	`boundQual(int qual, byte maxQual)` Return a quality score that bounds qual by maxQual and 1 WARNING -- because this function takes a byte for maxQual, you must be careful in converting integers to byte.
`static byte`	`errorProbToQual(double errorRate)` Convert a probability of being wrong to a phred-scaled quality score (0.01 => 20).
`static byte`	`errorProbToQual(double errorRate, byte maxQual)` Convert a probability of being wrong to a phred-scaled quality score (0.01 => 20).
`static byte`	`errorProbToQual(double prob, int maxQual)`
`static double`	`logProbToPhred(double prob)` Convert a log-probability to a phred-scaled value ( log(0.001) => 30 )
`static double`	`phredScaleCorrectRate(double trueRate)` Convert a probability of being right to a phred-scaled quality score of being wrong as a double This is a very generic method, that simply computes a phred-scaled double quality score given an error rate.
`static double`	`phredScaleErrorRate(double errorRate)` Convert a probability of being wrong to a phred-scaled quality score as a double This is a very generic method, that simply computes a phred-scaled double quality score given an error rate.
`static double`	`phredScaleLog10CorrectRate(double trueRateLog10)` Convert a log10 probability of being right to a phred-scaled quality score of being wrong as a double This is a very generic method, that simply computes a phred-scaled double quality score given an error rate.
`static double`	`phredScaleLog10ErrorRate(double errorRateLog10)` Convert a log10 probability of being wrong to a phred-scaled quality score as a double This is a very generic method, that simply computes a phred-scaled double quality score given an error rate.
`static double`	`phredSum(double[] phreds)` Calculate the sum of phred scores.
`static double`	`phredSum(double a, double b)` Calculate the sum of two phred scores.
`static double`	`phredSum(double a, double b, double c)` Calculate the sum of three phred scores.
`static double`	`qualToErrorProb(byte qual)` v Convert a phred-scaled quality score to its probability of being wrong (Q30 => 0.001) This is the Phred-style conversion, not the Illumina-style conversion.
`static double`	`qualToErrorProb(double qual)` Convert a phred-scaled quality score to its probability of being wrong (Q30 => 0.001) This is the Phred-style conversion, not the Illumina-style conversion.
`static double`	`qualToErrorProbLog10(byte qual)` Convert a phred-scaled quality score to its log10 probability of being wrong (Q30 => log10(0.001)) This is the Phred-style conversion, not the Illumina-style conversion.
`static double`	`qualToErrorProbLog10(double qual)` Convert a phred-scaled quality score to its log10 probability of being wrong (Q30 => log10(0.001)) This is the Phred-style conversion, not the Illumina-style conversion.
`static double`	`qualToProb(byte qual)` Convert a phred-scaled quality score to its probability of being true (Q30 => 0.999) This is the Phred-style conversion, not the Illumina-style conversion.
`static double`	`qualToProb(double qual)` Convert a phred-scaled quality score to its probability of being true (Q30 => 0.999) This is the Phred-style conversion, not the Illumina-style conversion.
`static double`	`qualToProbLog10(byte qual)` Convert a phred-scaled quality score to its log10 probability of being true (Q30 => log10(0.999)) This is the Phred-style conversion, not the Illumina-style conversion.
`static byte`	`trueProbToQual(double prob)` Convert a probability of being right to a phred-scaled quality score (0.99 => 20).
`static byte`	`trueProbToQual(double trueProb, byte maxQual)` Convert a probability of being right to a phred-scaled quality score (0.99 => 20).
`static byte`	`trueProbToQual(double prob, int maxQual)`

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

- Field Detail
  - MAX_SAM_QUAL_SCORE
```
public static final byte MAX_SAM_QUAL_SCORE
```
    Maximum quality score that can be encoded in a SAM/BAM file
    
    See Also:
    
    Constant Field Values
  - PHRED_TO_LOG_PROB_MULTIPLIER
```
public static final double PHRED_TO_LOG_PROB_MULTIPLIER
```
    conversion factor from phred scaled quality to log error probability and vice versa
  - LOG_PROB_TO_PHRED_MULTIPLIER
```
public static final double LOG_PROB_TO_PHRED_MULTIPLIER
```
  - MIN_PHRED_SCALED_QUAL
```
protected static final double MIN_PHRED_SCALED_QUAL
```
  - MAX_REASONABLE_Q_SCORE
```
public static final byte MAX_REASONABLE_Q_SCORE
```
    bams containing quals above this value are extremely suspicious and we should warn the user
    
    See Also:
    
    Constant Field Values
  - MIN_USABLE_Q_SCORE
```
public static final byte MIN_USABLE_Q_SCORE
```
    The lowest quality score for a base that is considered reasonable for statistical analysis. This is because Q 6 => you stand a 25% of being right, which means all bases are equally likely
    
    See Also:
    
    Constant Field Values
  - MAPPING_QUALITY_UNAVAILABLE
```
public static final int MAPPING_QUALITY_UNAVAILABLE
```
    See Also:
    
    Constant Field Values
  - MAX_QUAL
```
public static final int MAX_QUAL
```
    Maximum sense quality value.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - qualToProb
```
public static double qualToProb(byte qual)
```
    Convert a phred-scaled quality score to its probability of being true (Q30 => 0.999) This is the Phred-style conversion, *not* the Illumina-style conversion. Because the input is a discretized byte value, this function uses a cache so is very efficient WARNING -- because this function takes a byte for maxQual, you must be careful in converting integers to byte. The appropriate way to do this is ((byte)(myInt & 0xFF))
    
    Parameters:
    
    qual - a quality score (0-255)
    
    Returns:
    
    a probability (0.0-1.0)
  - qualToProb
```
public static double qualToProb(double qual)
```
    Convert a phred-scaled quality score to its probability of being true (Q30 => 0.999) This is the Phred-style conversion, *not* the Illumina-style conversion. Because the input is a double value, this function must call Math.pow so can be quite expensive
    
    Parameters:
    
    qual - a phred-scaled quality score encoded as a double. Can be non-integer values (30.5)
    
    Returns:
    
    a probability (0.0-1.0)
  - qualToProbLog10
```
public static double qualToProbLog10(byte qual)
```
    Convert a phred-scaled quality score to its log10 probability of being true (Q30 => log10(0.999)) This is the Phred-style conversion, *not* the Illumina-style conversion. WARNING -- because this function takes a byte for maxQual, you must be careful in converting integers to byte. The appropriate way to do this is ((byte)(myInt & 0xFF))
    
    Parameters:
    
    qual - a phred-scaled quality score encoded as a double. Can be non-integer values (30.5)
    
    Returns:
    
    a probability (0.0-1.0)
  - logProbToPhred
```
public static double logProbToPhred(double prob)
```
    Convert a log-probability to a phred-scaled value ( log(0.001) => 30 )
    
    Parameters:
    
    prob - a log-probability
    
    Returns:
    
    a phred-scaled value, not necessarily integral or bounded by MAX_QUAL
  - qualToErrorProb
```
public static double qualToErrorProb(double qual)
```
    Convert a phred-scaled quality score to its probability of being wrong (Q30 => 0.001) This is the Phred-style conversion, *not* the Illumina-style conversion. Because the input is a double value, this function must call Math.pow so can be quite expensive
    
    Parameters:
    
    qual - a phred-scaled quality score encoded as a double. Can be non-integer values (30.5)
    
    Returns:
    
    a probability (0.0-1.0)
  - qualToErrorProb
```
public static double qualToErrorProb(byte qual)
```
    v Convert a phred-scaled quality score to its probability of being wrong (Q30 => 0.001) This is the Phred-style conversion, *not* the Illumina-style conversion. Because the input is a byte value, this function uses a cache so is very efficient WARNING -- because this function takes a byte for maxQual, you must be careful in converting integers to byte. The appropriate way to do this is ((byte)(myInt & 0xFF))
    
    Parameters:
    
    qual - a phred-scaled quality score encoded as a byte
    
    Returns:
    
    a probability (0.0-1.0)
  - qualToErrorProbLog10
```
public static double qualToErrorProbLog10(byte qual)
```
    Convert a phred-scaled quality score to its log10 probability of being wrong (Q30 => log10(0.001)) This is the Phred-style conversion, *not* the Illumina-style conversion. The calculation is extremely efficient WARNING -- because this function takes a byte for maxQual, you must be careful in converting integers to byte. The appropriate way to do this is ((byte)(myInt & 0xFF))
    
    Parameters:
    
    qual - a phred-scaled quality score encoded as a byte
    
    Returns:
    
    a probability (0.0-1.0)
  - qualToErrorProbLog10
```
public static double qualToErrorProbLog10(double qual)
```
    Convert a phred-scaled quality score to its log10 probability of being wrong (Q30 => log10(0.001)) This is the Phred-style conversion, *not* the Illumina-style conversion. The calculation is extremely efficient
    
    Parameters:
    
    qual - a phred-scaled quality score encoded as a double
    
    Returns:
    
    log of probability (0.0-1.0)
  - errorProbToQual
```
public static byte errorProbToQual(double errorRate)
```
    Convert a probability of being wrong to a phred-scaled quality score (0.01 => 20). Note, this function caps the resulting quality score by the public static value MAX_SAM_QUAL_SCORE and by 1 at the low-end.
    
    Parameters:
    
    errorRate - a probability (0.0-1.0) of being wrong (i.e., 0.01 is 1% change of being wrong)
    
    Returns:
    
    a quality score (0-MAX_SAM_QUAL_SCORE)
  - errorProbToQual
```
public static byte errorProbToQual(double errorRate,
                                   byte maxQual)
```
    Convert a probability of being wrong to a phred-scaled quality score (0.01 => 20). Note, this function caps the resulting quality score by the public static value MIN_REASONABLE_ERROR and by 1 at the low-end. WARNING -- because this function takes a byte for maxQual, you must be careful in converting integers to byte. The appropriate way to do this is ((byte)(myInt & 0xFF))
    
    Parameters:
    
    errorRate - a probability (0.0-1.0) of being wrong (i.e., 0.01 is 1% change of being wrong)
    
    Returns:
    
    a quality score (0-maxQual)
  - errorProbToQual
```
public static byte errorProbToQual(double prob,
                                   int maxQual)
```
    See Also:
    
    with proper conversion of maxQual integer to a byte
  - trueProbToQual
```
public static byte trueProbToQual(double prob)
```
    Convert a probability of being right to a phred-scaled quality score (0.99 => 20). Note, this function caps the resulting quality score by the public static value MAX_SAM_QUAL_SCORE and by 1 at the low-end.
    
    Parameters:
    
    prob - a probability (0.0-1.0) of being right
    
    Returns:
    
    a quality score (0-MAX_SAM_QUAL_SCORE)
  - trueProbToQual
```
public static byte trueProbToQual(double trueProb,
                                  byte maxQual)
```
    Convert a probability of being right to a phred-scaled quality score (0.99 => 20). Note, this function caps the resulting quality score by the min probability allowed (EPS). So for example, if prob is 1e-6, which would imply a Q-score of 60, and EPS is 1e-4, the result of this function is actually Q40. Note that the resulting quality score, regardless of EPS, is capped by MAX_SAM_QUAL_SCORE and bounded on the low-side by 1. WARNING -- because this function takes a byte for maxQual, you must be careful in converting integers to byte. The appropriate way to do this is ((byte)(myInt & 0xFF))
    
    Parameters:
    
    trueProb - a probability (0.0-1.0) of being right
    
    maxQual - the maximum quality score we are allowed to emit here, regardless of the error rate
    
    Returns:
    
    a phred-scaled quality score (0-maxQualScore) as a byte
  - trueProbToQual
```
public static byte trueProbToQual(double prob,
                                  int maxQual)
```
    See Also:
    
    with proper conversion of maxQual to a byte
  - phredScaleCorrectRate
```
public static double phredScaleCorrectRate(double trueRate)
```
    Convert a probability of being right to a phred-scaled quality score of being wrong as a double This is a very generic method, that simply computes a phred-scaled double quality score given an error rate. It has the same precision as a normal double operation
    
    Parameters:
    
    trueRate - the probability of being right (0.0-1.0)
    
    Returns:
    
    a phred-scaled version of the error rate implied by trueRate
  - phredScaleErrorRate
```
public static double phredScaleErrorRate(double errorRate)
```
    Convert a probability of being wrong to a phred-scaled quality score as a double This is a very generic method, that simply computes a phred-scaled double quality score given an error rate. It has the same precision as a normal double operation
    
    Parameters:
    
    errorRate - the probability of being wrong (0.0-1.0)
    
    Returns:
    
    a phred-scaled version of the error rate
  - phredScaleLog10ErrorRate
```
public static double phredScaleLog10ErrorRate(double errorRateLog10)
```
    Convert a log10 probability of being wrong to a phred-scaled quality score as a double This is a very generic method, that simply computes a phred-scaled double quality score given an error rate. It has the same precision as a normal double operation
    
    Parameters:
    
    errorRateLog10 - the log10 probability of being wrong (0.0-1.0). Can be -Infinity, in which case the result is MIN_PHRED_SCALED_QUAL
    
    Returns:
    
    a phred-scaled version of the error rate
  - phredScaleLog10CorrectRate
```
public static double phredScaleLog10CorrectRate(double trueRateLog10)
```
    Convert a log10 probability of being right to a phred-scaled quality score of being wrong as a double This is a very generic method, that simply computes a phred-scaled double quality score given an error rate. It has the same precision as a normal double operation
    
    Parameters:
    
    trueRateLog10 - the log10 probability of being right (0.0-1.0). Can be -Infinity to indicate that the result is impossible in which MIN_PHRED_SCALED_QUAL is returned
    
    Returns:
    
    a phred-scaled version of the error rate implied by trueRate
  - boundQual
```
public static byte boundQual(int qual)
```
    Return a quality score that bounds qual by MAX_SAM_QUAL_SCORE and 1
    
    Parameters:
    
    qual - the uncapped quality score as an integer
    
    Returns:
    
    the bounded quality score
  - boundQual
```
public static byte boundQual(int qual,
                             byte maxQual)
```
    Return a quality score that bounds qual by maxQual and 1 WARNING -- because this function takes a byte for maxQual, you must be careful in converting integers to byte. The appropriate way to do this is ((byte)(myInt & 0xFF))
    
    Parameters:
    
    qual - the uncapped quality score as an integer. Can be < 0 (which may indicate an error in the client code), which will be brought back to 1, but this isn't an error, as some routines may use this functionality (BaseRecalibrator, for example)
    
    maxQual - the maximum quality score, must be less < 255
    
    Returns:
    
    the bounded quality score
  - phredSum
```
public static double phredSum(double[] phreds)
```
    Calculate the sum of phred scores.
    
    Parameters:
    
    phreds - the phred score values.
    
    Returns:
    
    the sum.
  - phredSum
```
public static double phredSum(double a,
                              double b)
```
    Calculate the sum of two phred scores.
    As any sum, this operation is commutative.
    
    Parameters:
    
    a - first phred score value.
    
    b - second phred score value.
    
    Returns:
    
    the sum.
  - phredSum
```
public static double phredSum(double a,
                              double b,
                              double c)
```
    Calculate the sum of three phred scores.
    As any sum, this operation is commutative.
    
    Parameters:
    
    a - first phred score value.
    
    b - second phred score value.
    
    c - thrid phred score value.
    
    Returns:
    
    the sum.

Class QualityUtils

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MAX_SAM_QUAL_SCORE

PHRED_TO_LOG_PROB_MULTIPLIER

LOG_PROB_TO_PHRED_MULTIPLIER

MIN_PHRED_SCALED_QUAL

MAX_REASONABLE_Q_SCORE

MIN_USABLE_Q_SCORE

MAPPING_QUALITY_UNAVAILABLE

MAX_QUAL

Method Detail

qualToProb

qualToProb

qualToProbLog10

logProbToPhred

qualToErrorProb

qualToErrorProb

qualToErrorProbLog10

qualToErrorProbLog10

errorProbToQual

errorProbToQual

errorProbToQual

trueProbToQual

trueProbToQual

trueProbToQual

phredScaleCorrectRate

phredScaleErrorRate

phredScaleLog10ErrorRate

phredScaleLog10CorrectRate

boundQual

boundQual

phredSum

phredSum

phredSum