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.MathException;
022    import org.apache.commons.math.MathRuntimeException;
023    import org.apache.commons.math.special.Beta;
024    import org.apache.commons.math.util.MathUtils;
025    
026    /**
027     * The default implementation of {@link BinomialDistribution}.
028     *
029     * @version $Revision: 772119 $ $Date: 2009-05-06 05:43:28 -0400 (Wed, 06 May 2009) $
030     */
031    public class BinomialDistributionImpl
032        extends AbstractIntegerDistribution
033        implements BinomialDistribution, Serializable {
034    
035        /** Serializable version identifier */
036        private static final long serialVersionUID = 6751309484392813623L;
037    
038        /** The number of trials. */
039        private int numberOfTrials;
040    
041        /** The probability of success. */
042        private double probabilityOfSuccess;
043    
044        /**
045         * Create a binomial distribution with the given number of trials and
046         * probability of success.
047         * @param trials the number of trials.
048         * @param p the probability of success.
049         */
050        public BinomialDistributionImpl(int trials, double p) {
051            super();
052            setNumberOfTrials(trials);
053            setProbabilityOfSuccess(p);
054        }
055    
056        /**
057         * Access the number of trials for this distribution.
058         * @return the number of trials.
059         */
060        public int getNumberOfTrials() {
061            return numberOfTrials;
062        }
063    
064        /**
065         * Access the probability of success for this distribution.
066         * @return the probability of success.
067         */
068        public double getProbabilityOfSuccess() {
069            return probabilityOfSuccess;
070        }
071    
072        /**
073         * Change the number of trials for this distribution.
074         * @param trials the new number of trials.
075         * @throws IllegalArgumentException if <code>trials</code> is not a valid
076         *         number of trials.
077         */
078        public void setNumberOfTrials(int trials) {
079            if (trials < 0) {
080                throw MathRuntimeException.createIllegalArgumentException(
081                      "number of trials must be non-negative ({0})", trials);
082            }
083            numberOfTrials = trials;
084        }
085    
086        /**
087         * Change the probability of success for this distribution.
088         * @param p the new probability of success.
089         * @throws IllegalArgumentException if <code>p</code> is not a valid
090         *         probability.
091         */
092        public void setProbabilityOfSuccess(double p) {
093            if (p < 0.0 || p > 1.0) {
094                throw MathRuntimeException.createIllegalArgumentException(
095                      "{0} out of [{1}, {2}] range", p, 0.0, 1.0);
096            }
097            probabilityOfSuccess = p;
098        }
099    
100        /**
101         * Access the domain value lower bound, based on <code>p</code>, used to
102         * bracket a PDF root.
103         * 
104         * @param p the desired probability for the critical value
105         * @return domain value lower bound, i.e.
106         *         P(X &lt; <i>lower bound</i>) &lt; <code>p</code> 
107         */
108        @Override
109        protected int getDomainLowerBound(double p) {
110            return -1;
111        }
112    
113        /**
114         * Access the domain value upper bound, based on <code>p</code>, used to
115         * bracket a PDF root.
116         * 
117         * @param p the desired probability for the critical value
118         * @return domain value upper bound, i.e.
119         *         P(X &lt; <i>upper bound</i>) &gt; <code>p</code> 
120         */
121        @Override
122        protected int getDomainUpperBound(double p) {
123            return getNumberOfTrials();
124        }
125    
126        /**
127         * For this distribution, X, this method returns P(X &le; x).
128         * @param x the value at which the PDF is evaluated.
129         * @return PDF for this distribution. 
130         * @throws MathException if the cumulative probability can not be
131         *            computed due to convergence or other numerical errors.
132         */
133        @Override
134        public double cumulativeProbability(int x) throws MathException {
135            double ret;
136            if (x < 0) {
137                ret = 0.0;
138            } else if (x >= getNumberOfTrials()) {
139                ret = 1.0;
140            } else {
141                ret =
142                    1.0 - Beta.regularizedBeta(
143                            getProbabilityOfSuccess(),
144                            x + 1.0,
145                            getNumberOfTrials() - x);
146            }
147            return ret;
148        }
149    
150        /**
151         * For this distribution, X, this method returns P(X = x).
152         * 
153         * @param x the value at which the PMF is evaluated.
154         * @return PMF for this distribution. 
155         */
156        public double probability(int x) {
157            double ret;
158            if (x < 0 || x > getNumberOfTrials()) {
159                ret = 0.0;
160            } else {
161                ret = MathUtils.binomialCoefficientDouble(
162                        getNumberOfTrials(), x) *
163                      Math.pow(getProbabilityOfSuccess(), x) *
164                      Math.pow(1.0 - getProbabilityOfSuccess(),
165                            getNumberOfTrials() - x);
166            }
167            return ret;
168        }
169        
170        /**
171         * For this distribution, X, this method returns the largest x, such
172         * that P(X &le; x) &le; <code>p</code>.
173         * <p>
174         * Returns <code>-1</code> for p=0 and <code>Integer.MAX_VALUE</code> for
175         * p=1.</p>
176         *
177         * @param p the desired probability
178         * @return the largest x such that P(X &le; x) <= p
179         * @throws MathException if the inverse cumulative probability can not be
180         *            computed due to convergence or other numerical errors.
181         * @throws IllegalArgumentException if p < 0 or p > 1
182         */
183        @Override
184        public int inverseCumulativeProbability(final double p) throws MathException {
185            // handle extreme values explicitly
186            if (p == 0) {
187                return -1;
188            } 
189            if (p == 1) {
190                return Integer.MAX_VALUE; 
191            }
192            
193            // use default bisection impl
194            return super.inverseCumulativeProbability(p);
195        }
196    }