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 MathUtil.LogMath` | `LOG_10_MATH` |
    `static MathUtil.LogMath` | `LOG_2_MATH` |
    `static double` | `LOG_4_BASE_E` | Constant to convert between the natural base e and 4.0.
    `static double` | `MAX_PROB_BELOW_ONE` | The double value closest to 1 while still being less than 1.
    `static MathUtil.LogMath` | `NATURAL_LOG_MATH` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    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 Detail

    - #### 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 Detail

    - #### 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.