001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.math.distribution;
018
019 import org.apache.commons.math.MathException;
020
021 /**
022 * Interface for discrete distributions of integer-valued random variables.
023 *
024 * @version $Revision: 949535 $ $Date: 2010-05-30 19:00:15 +0200 (dim. 30 mai 2010) $
025 */
026 public interface IntegerDistribution extends DiscreteDistribution {
027 /**
028 * For a random variable X whose values are distributed according
029 * to this distribution, this method returns P(X = x). In other words, this
030 * method represents the probability mass function for the distribution.
031 *
032 * @param x the value at which the probability density function is evaluated.
033 * @return the value of the probability density function at x
034 */
035 double probability(int x);
036
037 /**
038 * For a random variable X whose values are distributed according
039 * to this distribution, this method returns P(X ≤ x). In other words,
040 * this method represents the probability distribution function, or PDF
041 * for the distribution.
042 *
043 * @param x the value at which the PDF is evaluated.
044 * @return PDF for this distribution.
045 * @throws MathException if the cumulative probability can not be
046 * computed due to convergence or other numerical errors.
047 */
048 double cumulativeProbability(int x) throws MathException;
049
050 /**
051 * For this distribution, X, this method returns P(x0 ≤ X ≤ x1).
052 * @param x0 the inclusive, lower bound
053 * @param x1 the inclusive, upper bound
054 * @return the cumulative probability.
055 * @throws MathException if the cumulative probability can not be
056 * computed due to convergence or other numerical errors.
057 * @throws IllegalArgumentException if x0 > x1
058 */
059 double cumulativeProbability(int x0, int x1) throws MathException;
060
061 /**
062 * For this distribution, X, this method returns the largest x such that
063 * P(X ≤ x) <= p.
064 * <p>
065 * Note that this definition implies: <ul>
066 * <li> If there is a minimum value, <code>m</code>, with positive
067 * probability under (the density of) X, then <code>m - 1</code> is
068 * returned by <code>inverseCumulativeProbability(0).</code> If there is
069 * no such value <code>m, Integer.MIN_VALUE</code> is
070 * returned.</li>
071 * <li> If there is a maximum value, <code>M</code>, such that
072 * P(X ≤ M) =1, then <code>M</code> is returned by
073 * <code>inverseCumulativeProbability(1).</code>
074 * If there is no such value, <code>M, Integer.MAX_VALUE</code> is
075 * returned.</li></ul></p>
076 *
077 * @param p the cumulative probability.
078 * @return the largest x such that P(X ≤ x) <= p
079 * @throws MathException if the inverse cumulative probability can not be
080 * computed due to convergence or other numerical errors.
081 * @throws IllegalArgumentException if p is not between 0 and 1 (inclusive)
082 */
083 int inverseCumulativeProbability(double p) throws MathException;
084 }