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