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 < <i>lower bound</i>) < <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 < <i>upper bound</i>) > <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 ≤ 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 ≤ x) ≤ <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 ≤ 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 }