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.math3.distribution;
18  
19  import org.apache.commons.math3.exception.NumberIsTooLargeException;
20  import org.apache.commons.math3.exception.OutOfRangeException;
21  
22  /**
23   * Interface for distributions on the integers.
24   *
25   * @version $Id: IntegerDistribution.java 1416643 2012-12-03 19:37:14Z tn $
26   */
27  public interface IntegerDistribution {
28      /**
29       * For a random variable {@code X} whose values are distributed according
30       * to this distribution, this method returns {@code P(X = x)}. In other
31       * words, this method represents the probability mass function (PMF)
32       * for the distribution.
33       *
34       * @param x the point at which the PMF is evaluated
35       * @return the value of the probability mass function at {@code x}
36       */
37      double probability(int x);
38  
39      /**
40       * For a random variable {@code X} whose values are distributed according
41       * to this distribution, this method returns {@code P(X <= x)}.  In other
42       * words, this method represents the (cumulative) distribution function
43       * (CDF) for this distribution.
44       *
45       * @param x the point at which the CDF is evaluated
46       * @return the probability that a random variable with this
47       * distribution takes a value less than or equal to {@code x}
48       */
49      double cumulativeProbability(int x);
50  
51      /**
52       * For a random variable {@code X} whose values are distributed according
53       * to this distribution, this method returns {@code P(x0 < X <= x1)}.
54       *
55       * @param x0 the exclusive lower bound
56       * @param x1 the inclusive upper bound
57       * @return the probability that a random variable with this distribution
58       * will take a value between {@code x0} and {@code x1},
59       * excluding the lower and including the upper endpoint
60       * @throws NumberIsTooLargeException if {@code x0 > x1}
61       */
62      double cumulativeProbability(int x0, int x1) throws NumberIsTooLargeException;
63  
64      /**
65       * Computes the quantile function of this distribution.
66       * For a random variable {@code X} distributed according to this distribution,
67       * the returned value is
68       * <ul>
69       * <li><code>inf{x in Z | P(X<=x) >= p}</code> for {@code 0 < p <= 1},</li>
70       * <li><code>inf{x in Z | P(X<=x) > 0}</code> for {@code p = 0}.</li>
71       * </ul>
72       * If the result exceeds the range of the data type {@code int},
73       * then {@code Integer.MIN_VALUE} or {@code Integer.MAX_VALUE} is returned.
74       *
75       * @param p the cumulative probability
76       * @return the smallest {@code p}-quantile of this distribution
77       * (largest 0-quantile for {@code p = 0})
78       * @throws OutOfRangeException if {@code p < 0} or {@code p > 1}
79       */
80      int inverseCumulativeProbability(double p) throws OutOfRangeException;
81  
82      /**
83       * Use this method to get the numerical value of the mean of this
84       * distribution.
85       *
86       * @return the mean or {@code Double.NaN} if it is not defined
87       */
88      double getNumericalMean();
89  
90      /**
91       * Use this method to get the numerical value of the variance of this
92       * distribution.
93       *
94       * @return the variance (possibly {@code Double.POSITIVE_INFINITY} or
95       * {@code Double.NaN} if it is not defined)
96       */
97      double getNumericalVariance();
98  
99      /**
100      * Access the lower bound of the support. This method must return the same
101      * value as {@code inverseCumulativeProbability(0)}. In other words, this
102      * method must return
103      * <p><code>inf {x in Z | P(X <= x) > 0}</code>.</p>
104      *
105      * @return lower bound of the support ({@code Integer.MIN_VALUE}
106      * for negative infinity)
107      */
108     int getSupportLowerBound();
109 
110     /**
111      * Access the upper bound of the support. This method must return the same
112      * value as {@code inverseCumulativeProbability(1)}. In other words, this
113      * method must return
114      * <p><code>inf {x in R | P(X <= x) = 1}</code>.</p>
115      *
116      * @return upper bound of the support ({@code Integer.MAX_VALUE}
117      * for positive infinity)
118      */
119     int getSupportUpperBound();
120 
121     /**
122      * Use this method to get information about whether the support is
123      * connected, i.e. whether all integers between the lower and upper bound of
124      * the support are included in the support.
125      *
126      * @return whether the support is connected or not
127      */
128     boolean isSupportConnected();
129 
130     /**
131      * Reseed the random generator used to generate samples.
132      *
133      * @param seed the new seed
134      * @since 3.0
135      */
136     void reseedRandomGenerator(long seed);
137 
138     /**
139      * Generate a random value sampled from this distribution.
140      *
141      * @return a random value
142      * @since 3.0
143      */
144     int sample();
145 
146     /**
147      * Generate a random sample from the distribution.
148      *
149      * @param sampleSize the number of random values to generate
150      * @return an array representing the random sample
151      * @throws org.apache.commons.math3.exception.NotStrictlyPositiveException
152      * if {@code sampleSize} is not positive
153      * @since 3.0
154      */
155     int[] sample(int sampleSize);
156 }