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 java.io.Serializable;
020    
021    import org.apache.commons.math.FunctionEvaluationException;
022    import org.apache.commons.math.MathException;
023    import org.apache.commons.math.MathRuntimeException;
024    
025    
026    /**
027     * Base class for integer-valued discrete distributions.  Default
028     * implementations are provided for some of the methods that do not vary
029     * from distribution to distribution.
030     *
031     * @version $Revision: 920558 $ $Date: 2010-03-08 17:57:32 -0500 (Mon, 08 Mar 2010) $
032     */
033    public abstract class AbstractIntegerDistribution extends AbstractDistribution
034        implements IntegerDistribution, Serializable {
035    
036        /** Message for endpoints in wrong order. */
037        private static final String WRONG_ORDER_ENDPOINTS_MESSAGE =
038            "lower endpoint ({0}) must be less than or equal to upper endpoint ({1})";
039    
040        /** Message for out of range point. */
041        private static final String OUT_OF_RANGE_POINT =
042            "{0} out of [{1}, {2}] range";
043    
044        /** Serializable version identifier */
045        private static final long serialVersionUID = -1146319659338487221L;
046    
047        /**
048         * Default constructor.
049         */
050        protected AbstractIntegerDistribution() {
051            super();
052        }
053    
054        /**
055         * For a random variable X whose values are distributed according
056         * to this distribution, this method returns P(X ≤ x).  In other words,
057         * this method represents the  (cumulative) distribution function, or
058         * CDF, for this distribution.
059         * <p>
060         * If <code>x</code> does not represent an integer value, the CDF is
061         * evaluated at the greatest integer less than x.
062         *
063         * @param x the value at which the distribution function is evaluated.
064         * @return cumulative probability that a random variable with this
065         * distribution takes a value less than or equal to <code>x</code>
066         * @throws MathException if the cumulative probability can not be
067         * computed due to convergence or other numerical errors.
068         */
069        public double cumulativeProbability(double x) throws MathException {
070            return cumulativeProbability((int) Math.floor(x));
071        }
072    
073        /**
074         * For a random variable X whose values are distributed according
075         * to this distribution, this method returns P(x0 &le; X &le; x1).
076         *
077         * @param x0 the (inclusive) lower bound
078         * @param x1 the (inclusive) upper bound
079         * @return the probability that a random variable with this distribution
080         * will take a value between <code>x0</code> and <code>x1</code>,
081         * including the endpoints.
082         * @throws MathException if the cumulative probability can not be
083         * computed due to convergence or other numerical errors.
084         * @throws IllegalArgumentException if <code>x0 > x1</code>
085         */
086        @Override
087        public double cumulativeProbability(double x0, double x1)
088            throws MathException {
089            if (x0 > x1) {
090                throw MathRuntimeException.createIllegalArgumentException(
091                      WRONG_ORDER_ENDPOINTS_MESSAGE, x0, x1);
092            }
093            if (Math.floor(x0) < x0) {
094                return cumulativeProbability(((int) Math.floor(x0)) + 1,
095                   (int) Math.floor(x1)); // don't want to count mass below x0
096            } else { // x0 is mathematical integer, so use as is
097                return cumulativeProbability((int) Math.floor(x0),
098                    (int) Math.floor(x1));
099            }
100        }
101    
102        /**
103         * For a random variable X whose values are distributed according
104         * to this distribution, this method returns P(X &le; x).  In other words,
105         * this method represents the probability distribution function, or PDF,
106         * for this distribution.
107         *
108         * @param x the value at which the PDF is evaluated.
109         * @return PDF for this distribution.
110         * @throws MathException if the cumulative probability can not be
111         *            computed due to convergence or other numerical errors.
112         */
113        public abstract double cumulativeProbability(int x) throws MathException;
114    
115        /**
116         * For a random variable X whose values are distributed according
117         * to this distribution, this method returns P(X = x). In other words, this
118         * method represents the probability mass function,  or PMF, for the distribution.
119         * <p>
120         * If <code>x</code> does not represent an integer value, 0 is returned.
121         *
122         * @param x the value at which the probability density function is evaluated
123         * @return the value of the probability density function at x
124         */
125        public double probability(double x) {
126            double fl = Math.floor(x);
127            if (fl == x) {
128                return this.probability((int) x);
129            } else {
130                return 0;
131            }
132        }
133    
134        /**
135        * For a random variable X whose values are distributed according
136         * to this distribution, this method returns P(x0 &le; X &le; x1).
137         *
138         * @param x0 the inclusive, lower bound
139         * @param x1 the inclusive, upper bound
140         * @return the cumulative probability.
141         * @throws MathException if the cumulative probability can not be
142         *            computed due to convergence or other numerical errors.
143         * @throws IllegalArgumentException if x0 > x1
144         */
145        public double cumulativeProbability(int x0, int x1) throws MathException {
146            if (x0 > x1) {
147                throw MathRuntimeException.createIllegalArgumentException(
148                      WRONG_ORDER_ENDPOINTS_MESSAGE, x0, x1);
149            }
150            return cumulativeProbability(x1) - cumulativeProbability(x0 - 1);
151        }
152    
153        /**
154         * For a random variable X whose values are distributed according
155         * to this distribution, this method returns the largest x, such
156         * that P(X &le; x) &le; <code>p</code>.
157         *
158         * @param p the desired probability
159         * @return the largest x such that P(X &le; x) <= p
160         * @throws MathException if the inverse cumulative probability can not be
161         *            computed due to convergence or other numerical errors.
162         * @throws IllegalArgumentException if p < 0 or p > 1
163         */
164        public int inverseCumulativeProbability(final double p) throws MathException{
165            if (p < 0.0 || p > 1.0) {
166                throw MathRuntimeException.createIllegalArgumentException(
167                      OUT_OF_RANGE_POINT, p, 0.0, 1.0);
168            }
169    
170            // by default, do simple bisection.
171            // subclasses can override if there is a better method.
172            int x0 = getDomainLowerBound(p);
173            int x1 = getDomainUpperBound(p);
174            double pm;
175            while (x0 < x1) {
176                int xm = x0 + (x1 - x0) / 2;
177                pm = checkedCumulativeProbability(xm);
178                if (pm > p) {
179                    // update x1
180                    if (xm == x1) {
181                        // this can happen with integer division
182                        // simply decrement x1
183                        --x1;
184                    } else {
185                        // update x1 normally
186                        x1 = xm;
187                    }
188                } else {
189                    // update x0
190                    if (xm == x0) {
191                        // this can happen with integer division
192                        // simply increment x0
193                        ++x0;
194                    } else {
195                        // update x0 normally
196                        x0 = xm;
197                    }
198                }
199            }
200    
201            // insure x0 is the correct critical point
202            pm = checkedCumulativeProbability(x0);
203            while (pm > p) {
204                --x0;
205                pm = checkedCumulativeProbability(x0);
206            }
207    
208            return x0;
209        }
210    
211        /**
212         * Computes the cumulative probablity function and checks for NaN values returned.
213         * Throws MathException if the value is NaN. Wraps and rethrows any MathException encountered
214         * evaluating the cumulative probability function in a FunctionEvaluationException. Throws
215         * FunctionEvaluationException of the cumulative probability function returns NaN.
216         *
217         * @param argument input value
218         * @return cumulative probability
219         * @throws FunctionEvaluationException if a MathException occurs computing the cumulative probability
220         */
221        private double checkedCumulativeProbability(int argument) throws FunctionEvaluationException {
222            double result = Double.NaN;
223            try {
224                result = cumulativeProbability(argument);
225            } catch (MathException ex) {
226                throw new FunctionEvaluationException(ex, argument, ex.getPattern(), ex.getArguments());
227            }
228            if (Double.isNaN(result)) {
229                throw new FunctionEvaluationException(argument,
230                    "Discrete cumulative probability function returned NaN for argument {0}", argument);
231            }
232            return result;
233        }
234    
235        /**
236         * Access the domain value lower bound, based on <code>p</code>, used to
237         * bracket a PDF root.  This method is used by
238         * {@link #inverseCumulativeProbability(double)} to find critical values.
239         *
240         * @param p the desired probability for the critical value
241         * @return domain value lower bound, i.e.
242         *         P(X &lt; <i>lower bound</i>) &lt; <code>p</code>
243         */
244        protected abstract int getDomainLowerBound(double p);
245    
246        /**
247         * Access the domain value upper bound, based on <code>p</code>, used to
248         * bracket a PDF root.  This method is used by
249         * {@link #inverseCumulativeProbability(double)} to find critical values.
250         *
251         * @param p the desired probability for the critical value
252         * @return domain value upper bound, i.e.
253         *         P(X &lt; <i>upper bound</i>) &gt; <code>p</code>
254         */
255        protected abstract int getDomainUpperBound(double p);
256    }