View Javadoc
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.rng.sampling.distribution;
18  
19  import org.apache.commons.rng.UniformRandomProvider;
20  
21  /**
22   * Distribution sampler that uses the
23   * <a href="https://en.wikipedia.org/wiki/Inverse_transform_sampling">
24   * inversion method</a>.
25   *
26   * It can be used to sample any distribution that provides access to its
27   * <em>inverse cumulative probabilty function</em>.
28   *
29   * <p>Example:</p>
30   * <pre><code>
31   * import org.apache.commons.math3.distribution.IntegerDistribution;
32   * import org.apache.commons.math3.distribution.BinomialDistribution;
33   *
34   * import org.apache.commons.rng.simple.RandomSource;
35   * import org.apache.commons.rng.sampling.distribution.DiscreteSampler;
36   * import org.apache.commons.rng.sampling.distribution.InverseTransformDiscreteSampler;
37   * import org.apache.commons.rng.sampling.distribution.DiscreteInverseCumulativeProbabilityFunction;
38   *
39   * // Distribution to sample.
40   * final IntegerDistribution dist = new BinomialDistribution(11, 0.56);
41   * // Create the sampler.
42   * final DiscreteSampler binomialSampler =
43   *     new InverseTransformDiscreteSampler(RandomSource.create(RandomSource.MT),
44   *                                         new DiscreteInverseCumulativeProbabilityFunction() {
45   *                                             public int inverseCumulativeProbability(double p) {
46   *                                                 return dist.inverseCumulativeProbability(p);
47   *                                             }
48   *                                         });
49   *
50   * // Generate random deviate.
51   * int random = binomialSampler.sample();
52   * </code></pre>
53   *
54   * @since 1.0
55   */
56  public class InverseTransformDiscreteSampler
57      extends SamplerBase
58      implements DiscreteSampler {
59      /** Inverse cumulative probability function. */
60      private final DiscreteInverseCumulativeProbabilityFunction function;
61      /** Underlying source of randomness. */
62      private final UniformRandomProvider rng;
63  
64      /**
65       * @param rng Generator of uniformly distributed random numbers.
66       * @param function Inverse cumulative probability function.
67       */
68      public InverseTransformDiscreteSampler(UniformRandomProvider rng,
69                                             DiscreteInverseCumulativeProbabilityFunction function) {
70          super(null);
71          this.rng = rng;
72          this.function = function;
73      }
74  
75      /** {@inheritDoc} */
76      @Override
77      public int sample() {
78          return function.inverseCumulativeProbability(rng.nextDouble());
79      }
80  
81      /** {@inheritDoc} */
82      @Override
83      public String toString() {
84          return function.toString() + " (inverse method) [" + rng.toString() + "]";
85      }
86  }