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.math3.distribution;

  19. import java.util.ArrayList;
  20. import java.util.List;

  22. import org.apache.commons.math3.exception.DimensionMismatchException;
  23. import org.apache.commons.math3.exception.MathArithmeticException;
  24. import org.apache.commons.math3.exception.NotANumberException;
  25. import org.apache.commons.math3.exception.NotFiniteNumberException;
  26. import org.apache.commons.math3.exception.NotPositiveException;
  27. import org.apache.commons.math3.exception.OutOfRangeException;
  28. import org.apache.commons.math3.random.RandomGenerator;
  29. import org.apache.commons.math3.random.Well19937c;
  30. import org.apache.commons.math3.util.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 extends AbstractRealDistribution {

  44.     /** Serializable UID. */
  45.     private static final long serialVersionUID = 20130308L;

  47.     /**
  48.      * {@link EnumeratedDistribution} (using the {@link Double} wrapper)
  49.      * used to generate the pmf.
  50.      */
  51.     protected final EnumeratedDistribution<Double> innerDistribution;

  53.     /**
  54.      * Create a discrete distribution using the given probability mass function
  55.      * enumeration.
  56.      * <p>
  57.      * <b>Note:</b> this constructor will implicitly create an instance of
  58.      * {@link Well19937c} as random generator to be used for sampling only (see
  59.      * {@link #sample()} and {@link #sample(int)}). In case no sampling is
  60.      * needed for the created distribution, it is advised to pass {@code null}
  61.      * as random generator via the appropriate constructors to avoid the
  62.      * additional initialisation overhead.
  63.      *
  64.      * @param singletons array of random variable values.
  65.      * @param probabilities array of probabilities.
  66.      * @throws DimensionMismatchException if
  67.      * {@code singletons.length != probabilities.length}
  68.      * @throws NotPositiveException if any of the probabilities are negative.
  69.      * @throws NotFiniteNumberException if any of the probabilities are infinite.
  70.      * @throws NotANumberException if any of the probabilities are NaN.
  71.      * @throws MathArithmeticException all of the probabilities are 0.
  72.      */
  73.     public EnumeratedRealDistribution(final double[] singletons, final double[] probabilities)
  74.     throws DimensionMismatchException, NotPositiveException, MathArithmeticException,
  75.            NotFiniteNumberException, NotANumberException {
  76.         this(new Well19937c(), singletons, probabilities);
  77.     }

  79.     /**
  80.      * Create a discrete distribution using the given random number generator
  81.      * and probability mass function enumeration.
  82.      *
  83.      * @param rng random number generator.
  84.      * @param singletons array of random variable values.
  85.      * @param probabilities array of probabilities.
  86.      * @throws DimensionMismatchException if
  87.      * {@code singletons.length != probabilities.length}
  88.      * @throws NotPositiveException if any of the probabilities are negative.
  89.      * @throws NotFiniteNumberException if any of the probabilities are infinite.
  90.      * @throws NotANumberException if any of the probabilities are NaN.
  91.      * @throws MathArithmeticException all of the probabilities are 0.
  92.      */
  93.     public EnumeratedRealDistribution(final RandomGenerator rng,
  94.                                     final double[] singletons, final double[] probabilities)
  95.         throws DimensionMismatchException, NotPositiveException, MathArithmeticException,
  96.                NotFiniteNumberException, NotANumberException {
  97.         super(rng);
  98.         if (singletons.length != probabilities.length) {
  99.             throw new DimensionMismatchException(probabilities.length, singletons.length);
  100.         }

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

  104.         for (int i = 0; i < singletons.length; i++) {
  105.             samples.add(new Pair<Double, Double>(singletons[i], probabilities[i]));
  106.         }

  108.         innerDistribution = new EnumeratedDistribution<Double>(rng, samples);
  109.     }

  111.     /**
  112.      * {@inheritDoc}
  113.      */
  114.     @Override
  115.     public double probability(final double x) {
  116.         return innerDistribution.probability(x);
  117.     }

  119.     /**
  120.      * For a random variable {@code X} whose values are distributed according to
  121.      * this distribution, this method returns {@code P(X = x)}. In other words,
  122.      * this method represents the probability mass function (PMF) for the
  123.      * distribution.
  124.      *
  125.      * @param x the point at which the PMF is evaluated
  126.      * @return the value of the probability mass function at point {@code x}
  127.      */
  128.     public double density(final double x) {
  129.         return probability(x);
  130.     }

  132.     /**
  133.      * {@inheritDoc}
  134.      */
  135.     public double cumulativeProbability(final double x) {
  136.         double probability = 0;

  138.         for (final Pair<Double, Double> sample : innerDistribution.getPmf()) {
  139.             if (sample.getKey() <= x) {
  140.                 probability += sample.getValue();
  141.             }
  142.         }

  144.         return probability;
  145.     }

  147.     /**
  148.      * {@inheritDoc}
  149.      */
  150.     @Override
  151.     public double inverseCumulativeProbability(final double p) throws OutOfRangeException {
  152.         if (p < 0.0 || p > 1.0) {
  153.             throw new OutOfRangeException(p, 0, 1);
  154.         }

  156.         double probability = 0;
  157.         double x = getSupportLowerBound();
  158.         for (final Pair<Double, Double> sample : innerDistribution.getPmf()) {
  159.             if (sample.getValue() == 0.0) {
  160.                 continue;
  161.             }

  163.             probability += sample.getValue();
  164.             x = sample.getKey();

  166.             if (probability >= p) {
  167.                 break;
  168.             }
  169.         }

  171.         return x;
  172.     }

  174.     /**
  175.      * {@inheritDoc}
  176.      *
  177.      * @return {@code sum(singletons[i] * probabilities[i])}
  178.      */
  179.     public double getNumericalMean() {
  180.         double mean = 0;

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

  186.         return mean;
  187.     }

  189.     /**
  190.      * {@inheritDoc}
  191.      *
  192.      * @return {@code sum((singletons[i] - mean) ^ 2 * probabilities[i])}
  193.      */
  194.     public double getNumericalVariance() {
  195.         double mean = 0;
  196.         double meanOfSquares = 0;

  198.         for (final Pair<Double, Double> sample : innerDistribution.getPmf()) {
  199.             mean += sample.getValue() * sample.getKey();
  200.             meanOfSquares += sample.getValue() * sample.getKey() * sample.getKey();
  201.         }

  203.         return meanOfSquares - mean * mean;
  204.     }

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

  221.         return min;
  222.     }

  224.     /**
  225.      * {@inheritDoc}
  226.      *
  227.      * Returns the highest value with non-zero probability.
  228.      *
  229.      * @return the highest value with non-zero probability.
  230.      */
  231.     public double getSupportUpperBound() {
  232.         double max = Double.NEGATIVE_INFINITY;
  233.         for (final Pair<Double, Double> sample : innerDistribution.getPmf()) {
  234.             if (sample.getKey() > max && sample.getValue() > 0) {
  235.                 max = sample.getKey();
  236.             }
  237.         }

  239.         return max;
  240.     }

  242.     /**
  243.      * {@inheritDoc}
  244.      *
  245.      * The support of this distribution includes the lower bound.
  246.      *
  247.      * @return {@code true}
  248.      */
  249.     public boolean isSupportLowerBoundInclusive() {
  250.         return true;
  251.     }

  253.     /**
  254.      * {@inheritDoc}
  255.      *
  256.      * The support of this distribution includes the upper bound.
  257.      *
  258.      * @return {@code true}
  259.      */
  260.     public boolean isSupportUpperBoundInclusive() {
  261.         return true;
  262.     }

  264.     /**
  265.      * {@inheritDoc}
  266.      *
  267.      * The support of this distribution is connected.
  268.      *
  269.      * @return {@code true}
  270.      */
  271.     public boolean isSupportConnected() {
  272.         return true;
  273.     }

  275.     /**
  276.      * {@inheritDoc}
  277.      */
  278.     @Override
  279.     public double sample() {
  280.         return innerDistribution.sample();
  281.     }
  282. }
Created with JaCoCo 0.7.2.201409121644