EnumeratedRealDistribution.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.math4.legacy.distribution;

  18. import java.util.ArrayList;
  19. import java.util.LinkedHashMap;
  20. import java.util.List;
  21. import java.util.Map;
  22. import java.util.Map.Entry;

  23. import org.apache.commons.statistics.distribution.ContinuousDistribution;
  24. import org.apache.commons.math4.legacy.exception.DimensionMismatchException;
  25. import org.apache.commons.math4.legacy.exception.MathArithmeticException;
  26. import org.apache.commons.math4.legacy.exception.NotANumberException;
  27. import org.apache.commons.math4.legacy.exception.NotFiniteNumberException;
  28. import org.apache.commons.math4.legacy.exception.NotPositiveException;
  29. import org.apache.commons.math4.legacy.exception.OutOfRangeException;
  30. import org.apache.commons.rng.UniformRandomProvider;
  31. import org.apache.commons.math4.legacy.core.Pair;

  32. /**
  33.  * <p>Implementation of a real-valued {@link EnumeratedDistribution}.
  34.  *
  35.  * <p>Values with zero-probability are allowed but they do not extend the
  36.  * support.<br>
  37.  * Duplicate values are allowed. Probabilities of duplicate values are combined
  38.  * when computing cumulative probabilities and statistics.</p>
  39.  *
  40.  * @since 3.2
  41.  */
  42. public class EnumeratedRealDistribution
  43.     implements ContinuousDistribution {
  44.     /**
  45.      * {@link EnumeratedDistribution} (using the {@link Double} wrapper)
  46.      * used to generate the pmf.
  47.      */
  48.     protected final EnumeratedDistribution<Double> innerDistribution;

  49.     /**
  50.      * Create a discrete real-valued distribution using the given random number generator
  51.      * and probability mass function enumeration.
  52.      *
  53.      * @param singletons array of random variable values.
  54.      * @param probabilities array of probabilities.
  55.      * @throws DimensionMismatchException if
  56.      * {@code singletons.length != probabilities.length}
  57.      * @throws NotPositiveException if any of the probabilities are negative.
  58.      * @throws NotFiniteNumberException if any of the probabilities are infinite.
  59.      * @throws NotANumberException if any of the probabilities are NaN.
  60.      * @throws MathArithmeticException all of the probabilities are 0.
  61.      */
  62.     public EnumeratedRealDistribution(final double[] singletons,
  63.                                       final double[] probabilities)
  64.         throws DimensionMismatchException,
  65.                NotPositiveException,
  66.                MathArithmeticException,
  67.                NotFiniteNumberException,
  68.                NotANumberException {
  69.         innerDistribution = new EnumeratedDistribution<>(createDistribution(singletons, probabilities));
  70.     }

  71.     /**
  72.      * Creates a discrete real-valued distribution from the input data.
  73.      * Values are assigned mass based on their frequency.
  74.      *
  75.      * @param data input dataset
  76.      */
  77.     public EnumeratedRealDistribution(final double[] data) {
  78.         final Map<Double, Integer> dataMap = new LinkedHashMap<>();
  79.         for (double value : data) {
  80.             dataMap.merge(value, 1, Integer::sum);
  81.         }
  82.         final int massPoints = dataMap.size();
  83.         final double denom = data.length;
  84.         final double[] values = new double[massPoints];
  85.         final double[] probabilities = new double[massPoints];
  86.         int index = 0;
  87.         for (Entry<Double, Integer> entry : dataMap.entrySet()) {
  88.             values[index] = entry.getKey();
  89.             probabilities[index] = entry.getValue().intValue() / denom;
  90.             index++;
  91.         }
  92.         innerDistribution = new EnumeratedDistribution<>(createDistribution(values, probabilities));
  93.     }

  94.     /**
  95.      * Create the list of Pairs representing the distribution from singletons and probabilities.
  96.      *
  97.      * @param singletons values
  98.      * @param probabilities probabilities
  99.      * @return list of value/probability pairs
  100.      */
  101.     private static List<Pair<Double, Double>>  createDistribution(double[] singletons, double[] probabilities) {
  102.         if (singletons.length != probabilities.length) {
  103.             throw new DimensionMismatchException(probabilities.length, singletons.length);
  104.         }

  105.         final List<Pair<Double, Double>> samples = new ArrayList<>(singletons.length);

  106.         for (int i = 0; i < singletons.length; i++) {
  107.             samples.add(new Pair<>(singletons[i], probabilities[i]));
  108.         }
  109.         return samples;
  110.     }

  111.     /**
  112.      * For a random variable {@code X} whose values are distributed according to
  113.      * this distribution, this method returns {@code P(X = x)}. In other words,
  114.      * this method represents the probability mass function (PMF) for the
  115.      * distribution.
  116.      *
  117.      * @param x the point at which the PMF is evaluated
  118.      * @return the value of the probability mass function at point {@code x}
  119.      */
  120.     @Override
  121.     public double density(final double x) {
  122.         return innerDistribution.probability(x);
  123.     }

  124.     /**
  125.      * {@inheritDoc}
  126.      */
  127.     @Override
  128.     public double cumulativeProbability(final double x) {
  129.         double probability = 0;

  130.         for (final Pair<Double, Double> sample : innerDistribution.getPmf()) {
  131.             if (sample.getKey() <= x) {
  132.                 probability += sample.getValue();
  133.             }
  134.         }

  135.         return probability;
  136.     }

  137.     /**
  138.      * {@inheritDoc}
  139.      */
  140.     @Override
  141.     public double inverseCumulativeProbability(final double p) throws OutOfRangeException {
  142.         if (p < 0.0 || p > 1.0) {
  143.             throw new OutOfRangeException(p, 0, 1);
  144.         }

  145.         double probability = 0;
  146.         double x = getSupportLowerBound();
  147.         for (final Pair<Double, Double> sample : innerDistribution.getPmf()) {
  148.             if (sample.getValue() == 0.0) {
  149.                 continue;
  150.             }

  151.             probability += sample.getValue();
  152.             x = sample.getKey();

  153.             if (probability >= p) {
  154.                 break;
  155.             }
  156.         }

  157.         return x;
  158.     }

  159.     /**
  160.      * {@inheritDoc}
  161.      *
  162.      * @return {@code sum(singletons[i] * probabilities[i])}
  163.      */
  164.     @Override
  165.     public double getMean() {
  166.         double mean = 0;

  167.         for (final Pair<Double, Double> sample : innerDistribution.getPmf()) {
  168.             mean += sample.getValue() * sample.getKey();
  169.         }

  170.         return mean;
  171.     }

  172.     /**
  173.      * {@inheritDoc}
  174.      *
  175.      * @return {@code sum((singletons[i] - mean) ^ 2 * probabilities[i])}
  176.      */
  177.     @Override
  178.     public double getVariance() {
  179.         double mean = 0;
  180.         double meanOfSquares = 0;

  181.         for (final Pair<Double, Double> sample : innerDistribution.getPmf()) {
  182.             mean += sample.getValue() * sample.getKey();
  183.             meanOfSquares += sample.getValue() * sample.getKey() * sample.getKey();
  184.         }

  185.         return meanOfSquares - mean * mean;
  186.     }

  187.     /**
  188.      * {@inheritDoc}
  189.      *
  190.      * Returns the lowest value with non-zero probability.
  191.      *
  192.      * @return the lowest value with non-zero probability.
  193.      */
  194.     @Override
  195.     public double getSupportLowerBound() {
  196.         double min = Double.POSITIVE_INFINITY;
  197.         for (final Pair<Double, Double> sample : innerDistribution.getPmf()) {
  198.             if (sample.getKey() < min && sample.getValue() > 0) {
  199.                 min = sample.getKey();
  200.             }
  201.         }

  202.         return min;
  203.     }

  204.     /**
  205.      * {@inheritDoc}
  206.      *
  207.      * Returns the highest value with non-zero probability.
  208.      *
  209.      * @return the highest value with non-zero probability.
  210.      */
  211.     @Override
  212.     public double getSupportUpperBound() {
  213.         double max = Double.NEGATIVE_INFINITY;
  214.         for (final Pair<Double, Double> sample : innerDistribution.getPmf()) {
  215.             if (sample.getKey() > max && sample.getValue() > 0) {
  216.                 max = sample.getKey();
  217.             }
  218.         }

  219.         return max;
  220.     }

  221.     /** {@inheritDoc} */
  222.     @Override
  223.     public ContinuousDistribution.Sampler createSampler(final UniformRandomProvider rng) {
  224.         return innerDistribution.createSampler(rng)::sample;
  225.     }
  226. }