Package picard.util

# Class MathUtil

java.lang.Object
picard.util.MathUtil

public final class MathUtil extends Object
General math utilities

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`MathUtil.LogMath`
A collection of common math operations that work with log values.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final MathUtil.LogMath`
`LOG_10_MATH`
`static final MathUtil.LogMath`
`LOG_2_MATH`
`static final double`
`LOG_4_BASE_E`
Constant to convert between the natural base e and 4.0.
`static final double`
`MAX_PROB_BELOW_ONE`
The double value closest to 1 while still being less than 1.
`static final MathUtil.LogMath`
`NATURAL_LOG_MATH`

## Method Summary

Modifier and Type
Method
Description
`static double[]`
`capFromAbove(double[] nums, double top)`
Returns the array capped (from above) by the value of top
`static double[]`
`capFromBelow(double[] nums, double floor)`
Returns the array capped (from below) by the value of floor
`static int`
`compare(int v1, int v2)`
`static double[]`
`divide(double[] numerators, double[] denominators)`
Calculates the ratio of two arrays of the same length.
`static double`
`divide(double numerator, double denominator)`
Divide two Doubles but return 0.0 if the denominator is 0
`static double[]`
`getLogFromProbability(double[] likelihood)`
Takes a complete set of mutually exclusive Likelihoods and converts them to logLikelihoods.
`static double[]`
`getProbabilityFromLog(double[] lLikelihood)`
Takes a complete set of mutually exclusive logLikelihoods and converts them to probabilities with no rescaling.
`static int`
`indexOfMax(double[] nums)`
Returns the index of the largest element in the array.
`static int`
`indexOfMax(long[] nums)`
Returns the index of the largest element in the array.
`static int`
`indexOfMin(double[] nums)`
Returns the index of the smallest element in the array.
`static int`
`indexOfMin(int[] nums)`
Returns the index of the smallest element in the array.
`static double`
`klDivergance(double[] measured, double[] distribution)`
Calculate the KL divergence from measured to distribution // https://en.wikipedia.org/wiki/Kullback%E2%80%93Leibler_divergence
`static double`
`log10_1p(double x)`
this function mimics the behavior of log_1p but resulting in log _base 10_ of (1+x) instead of natural log of 1+x
`static double[]`
`logLikelihoodsToProbs(double[] likelihoods)`
Deprecated.
`static double`
`max(double[] nums)`
Returns the largest value stored in the array.
`static long`
`max(long[] nums)`
Returns the largest value stored in the array.
`static double`
`mean(double[] in)`
`static double`
`mean(double[] in, int start, int stop)`
Calculated the mean of an array of doubles.
`static double`
`median(double... in)`
Calculate the median of an array of doubles.
`static byte`
`min(byte[] nums)`
Returns the smallest value stored in the array.
`static double`
`min(double[] nums)`
Returns the smallest value stored in the array.
`static int`
`min(int[] nums)`
Returns the smallest value stored in the array.
`static short`
`min(short[] nums)`
Returns the smallest value stored in the array.
`static double[]`
`multiply(double[] lhs, double[] rhs)`
Calculates the product of two arrays of the same length.
`static Double`
`percentageOrNull(Long numerator, Long denominator)`
Obtains percentage of two Longs
`static double[]`
`permute(double[] array, org.apache.commons.math3.random.RandomDataGenerator rdg)`
permute the input array randomly (using a RandomDataGenerator)
`static double[]`
`pNormalizeLogProbability(double[] lPosterior)`
Takes a complete set of mutually exclusive logPosteriors and converts them to probabilities that sum to 1 with as much fidelity as possible.
`static double[]`
`pNormalizeVector(double[] pPosterior)`
Takes a vector of numbers and converts it to a vector of probabilities that sum to 1 with as much fidelity as possible.
`static double[]`
`promote(int[] is)`
"Promotes" an int[] into a double array with the same values (or as close as precision allows).
`static <T> List<T>`
`randomSublist(List<T> list, int n, Random random)`
A small utility function to choose n random elements (un-shuffled) from a list
`static long[]`
`round(double... input)`
returns a long array containing the rounded values of the input array
`static double`
`round(double num, int precision)`
Round off the value to the specified precision.
`static double[]`
`seq(double from, double to, double by)`
Mimic's R's seq() function to produce a sequence of equally spaced numbers.
`static double`
`stddev(double[] in, double mean)`
Calculated the standard deviation of an array of doubles.
`static double`
`stddev(double[] in, int start, int length)`
Calculated the standard deviation of an array of doubles.
`static double`
`stddev(double[] in, int start, int stop, double mean)`
Calculated the standard deviation of an array of doubles.
`static double[]`
`subtractMax(double[] logLikelihoods)`
`static double`
`sum(double[] arr)`
Returns the sum of the elements in the array.
`static double[]`
`sum(double[] lhs, double rhs)`
calculates the sum of an array and a double.
`static double[]`
`sum(double[] lhs, double[] rhs)`
calculates the sum of the arrays as a third array.
`static long`
`sum(long[] arr, int start, int stop)`
Returns the sum of the elements in the array starting with start and ending before stop.

### Methods inherited from class java.lang.Object

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

## Field Details

### MAX_PROB_BELOW_ONE

public static final double MAX_PROB_BELOW_ONE
The double value closest to 1 while still being less than 1.

See Also:
  - Constant Field Values

### LOG_4_BASE_E

public static final double LOG_4_BASE_E
Constant to convert between the natural base e and 4.0. Useful for entropy calculations on DNA.

### LOG_2_MATH

public static final MathUtil.LogMath LOG_2_MATH

### NATURAL_LOG_MATH

public static final MathUtil.LogMath NATURAL_LOG_MATH

### LOG_10_MATH

public static final MathUtil.LogMath LOG_10_MATH

## Method Details

### log10_1p

public static double log10_1p(double x)
this function mimics the behavior of log_1p but resulting in log _base 10_ of (1+x) instead of natural log of 1+x

### mean

public static double mean(double[] in, int start, int stop)
Calculated the mean of an array of doubles.

### mean

public static double mean(double[] in)

### stddev

public static double stddev(double[] in, int start, int length)
Calculated the standard deviation of an array of doubles.

### stddev

public static double stddev(double[] in, int start, int stop, double mean)
Calculated the standard deviation of an array of doubles.

### stddev

public static double stddev(double[] in, double mean)
Calculated the standard deviation of an array of doubles.

### compare

public static int compare(int v1, int v2)

### median

public static double median(double... in)
Calculate the median of an array of doubles. Assumes that the input is sorted

### percentageOrNull

public static Double percentageOrNull(Long numerator, Long denominator)
Obtains percentage of two Longs

Parameters:
  `numerator` - dividend
  `denominator` - divisor
Returns:
  numerator/(double)denominator if both are non-null and denominator != 0, else returns null.

### round

public static double round(double num, int precision)
Round off the value to the specified precision.

### divide

public static double divide(double numerator, double denominator)
Divide two Doubles but return 0.0 if the denominator is 0

Parameters:
  `numerator` - dividend
  `denominator` - divisor
Returns:
  numerator/denominator unless denominator is 0, in which case returns 0

### max

public static double max(double[] nums)
Returns the largest value stored in the array.

### capFromBelow

public static double[] capFromBelow(double[] nums, double floor)
Returns the array capped (from below) by the value of floor

### indexOfMax

public static int indexOfMax(double[] nums)
Returns the index of the largest element in the array. If there are multiple equal maxima then the earliest one in the array is returned.

### max

public static long max(long[] nums)
Returns the largest value stored in the array.

### indexOfMax

public static int indexOfMax(long[] nums)
Returns the index of the largest element in the array. If there are multiple equal maxima then the earliest one in the array is returned.

### subtractMax

public static double[] subtractMax(double[] logLikelihoods)

### min

public static double min(double[] nums)
Returns the smallest value stored in the array.

### min

public static int min(int[] nums)
Returns the smallest value stored in the array.

### min

public static short min(short[] nums)
Returns the smallest value stored in the array.

### min

public static byte min(byte[] nums)
Returns the smallest value stored in the array.

### capFromAbove

public static double[] capFromAbove(double[] nums, double top)
Returns the array capped (from above) by the value of top

### indexOfMin

public static int indexOfMin(int[] nums)
Returns the index of the smallest element in the array. If there are multiple equal minima then the earliest one in the array is returned.

### indexOfMin

public static int indexOfMin(double[] nums)
Returns the index of the smallest element in the array. If there are multiple equal minima then the earliest one in the array is returned.

### seq

public static double[] seq(double from, double to, double by)
Mimic's R's seq() function to produce a sequence of equally spaced numbers.

### promote

public static double[] promote(int[] is)
"Promotes" an int[] into a double array with the same values (or as close as precision allows).

### logLikelihoodsToProbs

@Deprecated public static double[] logLikelihoodsToProbs(double[] likelihoods)
Deprecated.

### getProbabilityFromLog

public static double[] getProbabilityFromLog(double[] lLikelihood)
Takes a complete set of mutually exclusive logLikelihoods and converts them to probabilities with no rescaling. Will throw if underflow is detected (if all the likelihoods are less than -300)

### getLogFromProbability

public static double[] getLogFromProbability(double[] likelihood)
Takes a complete set of mutually exclusive Likelihoods and converts them to logLikelihoods.

### pNormalizeLogProbability

public static double[] pNormalizeLogProbability(double[] lPosterior)
Takes a complete set of mutually exclusive logPosteriors and converts them to probabilities that sum to 1 with as much fidelity as possible. Limits probabilities to be in the space: 0.9999999999999999 >= p >= (1-0.9999999999999999)/(lPosteriors.length-1)

### divide

public static double[] divide(double[] numerators, double[] denominators)
Calculates the ratio of two arrays of the same length.

### pNormalizeVector

public static double[] pNormalizeVector(double[] pPosterior)
Takes a vector of numbers and converts it to a vector of probabilities that sum to 1 with as much fidelity as possible. Limits probabilities to be in the space: 0.9999999999999999 >= p >= (1-0.9999999999999999)/(likelihoods.length-1)

### multiply

public static double[] multiply(double[] lhs, double[] rhs)
Calculates the product of two arrays of the same length.

### sum

public static double[] sum(double[] lhs, double[] rhs)
calculates the sum of the arrays as a third array.

### sum

public static double[] sum(double[] lhs, double rhs)
calculates the sum of an array and a double.

### sum

public static double sum(double[] arr)
Returns the sum of the elements in the array.

### sum

public static long sum(long[] arr, int start, int stop)
Returns the sum of the elements in the array starting with start and ending before stop.

### round

public static long[] round(double... input)
returns a long array containing the rounded values of the input array

### klDivergance

public static double klDivergance(double[] measured, double[] distribution)
Calculate the KL divergence from measured to distribution // https://en.wikipedia.org/wiki/Kullback%E2%80%93Leibler_divergence

### permute

public static double[] permute(double[] array, org.apache.commons.math3.random.RandomDataGenerator rdg)
permute the input array randomly (using a RandomDataGenerator)

Parameters:
  `array` - input array
  `rdg` - a RandomDataGenerator for drawing a permutation from
Returns:
  a newly allocated array with a permuted version of the original data.

### randomSublist

public static <T> List<T> randomSublist(List<T> list, int n, Random random)
A small utility function to choose n random elements (un-shuffled) from a list

Parameters:
  `list` - A list of elements
  `n` - a number of elements requested from list
  `random` - a Random object to use for subsetting
Returns:
  a list of n randomly chosen (but in the original order) elements from list. If the list has less than n elements it is returned in its entirety.