View Javadoc

1   /*
2    * Copyright 2004 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.math.distribution;
17  
18  import org.apache.commons.math.MathException;
19  
20  /**
21   * Interface for discrete distributions of integer-valued random variables.
22   *
23   * @version $Revision: 155427 $ $Date: 2005-02-26 06:11:52 -0700 (Sat, 26 Feb 2005) $
24   */
25  public interface IntegerDistribution extends DiscreteDistribution {
26      /**
27       * For a random variable X whose values are distributed according
28       * to this distribution, this method returns P(X = x). In other words, this
29       * method represents the probability mass function for the distribution.
30       * 
31       * @param x the value at which the probability density function is evaluated.
32       * @return the value of the probability density function at x
33       */
34      double probability(int x);
35  
36      /**
37       * For a random variable X whose values are distributed according
38       * to this distribution, this method returns P(X ≤ x).  In other words,
39       * this method represents the probability distribution function, or PDF
40       * for the distribution.
41       * 
42       * @param x the value at which the PDF is evaluated.
43       * @return PDF for this distribution. 
44       * @throws MathException if the cumulative probability can not be
45       *            computed due to convergence or other numerical errors.
46       */
47      double cumulativeProbability(int x) throws MathException;
48      
49      /**
50       * For this distribution, X, this method returns P(x0 ≤ X ≤ x1).
51       * @param x0 the inclusive, lower bound
52       * @param x1 the inclusive, upper bound
53       * @return the cumulative probability. 
54       * @throws MathException if the cumulative probability can not be
55       *            computed due to convergence or other numerical errors.
56       * @throws IllegalArgumentException if x0 > x1
57       */
58      double cumulativeProbability(int x0, int x1) throws MathException;
59      
60      /**
61       * For this distribution, X, this method returns the largest x such that
62       * P(X &le; x) <= p.
63       * <p>
64       * Note that this definition implies: <ul>
65       * <li> If there is a minimum value, <code>m</code>, with postive
66       * probablility under (the density of) X, then <code>m - 1</code> is
67       * returned by <code>inverseCumulativeProbability(0).</code>  If there is
68       * no such value <code>m,  Integer.MIN_VALUE</code> is 
69       * returned.</li>
70       * <li> If there is a maximum value, <code>M</code>, such that
71       * P(X &le; M) =1, then <code>M</code> is returned by 
72       * <code>inverseCumulativeProbability(1).</code>
73       * If there is no such value, <code>M, Integer.MAX_VALUE</code> is 
74       * returned.</li></ul>
75       * 
76       * @param p the cumulative probability.
77       * @return the largest x such that P(X &le; x) <= p
78       * @throws MathException if the inverse cumulative probability can not be
79       *            computed due to convergence or other numerical errors.
80       * @throws IllegalArgumentException if p is not between 0 and 1 (inclusive)
81       */
82      int inverseCumulativeProbability(double p) throws MathException;
83  }