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.exception.util.LocalizedFormats; 024 import org.apache.commons.math.special.Beta; 025 import org.apache.commons.math.util.FastMath; 026 027 /** 028 * The default implementation of {@link BinomialDistribution}. 029 * 030 * @version $Revision: 1054524 $ $Date: 2011-01-03 05:59:18 +0100 (lun. 03 janv. 2011) $ 031 */ 032 public class BinomialDistributionImpl 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 * 048 * @param trials the number of trials. 049 * @param p the probability of success. 050 */ 051 public BinomialDistributionImpl(int trials, double p) { 052 super(); 053 setNumberOfTrialsInternal(trials); 054 setProbabilityOfSuccessInternal(p); 055 } 056 057 /** 058 * Access the number of trials for this distribution. 059 * 060 * @return the number of trials. 061 */ 062 public int getNumberOfTrials() { 063 return numberOfTrials; 064 } 065 066 /** 067 * Access the probability of success for this distribution. 068 * 069 * @return the probability of success. 070 */ 071 public double getProbabilityOfSuccess() { 072 return probabilityOfSuccess; 073 } 074 075 /** 076 * Change the number of trials for this distribution. 077 * 078 * @param trials the new number of trials. 079 * @throws IllegalArgumentException if <code>trials</code> is not a valid 080 * number of trials. 081 * @deprecated as of 2.1 (class will become immutable in 3.0) 082 */ 083 @Deprecated 084 public void setNumberOfTrials(int trials) { 085 setNumberOfTrialsInternal(trials); 086 } 087 088 /** 089 * Change the number of trials for this distribution. 090 * 091 * @param trials the new number of trials. 092 * @throws IllegalArgumentException if <code>trials</code> is not a valid 093 * number of trials. 094 */ 095 private void setNumberOfTrialsInternal(int trials) { 096 if (trials < 0) { 097 throw MathRuntimeException.createIllegalArgumentException( 098 LocalizedFormats.NEGATIVE_NUMBER_OF_TRIALS, trials); 099 } 100 numberOfTrials = trials; 101 } 102 103 /** 104 * Change the probability of success for this distribution. 105 * 106 * @param p the new probability of success. 107 * @throws IllegalArgumentException if <code>p</code> is not a valid 108 * probability. 109 * @deprecated as of 2.1 (class will become immutable in 3.0) 110 */ 111 @Deprecated 112 public void setProbabilityOfSuccess(double p) { 113 setProbabilityOfSuccessInternal(p); 114 } 115 116 /** 117 * Change the probability of success for this distribution. 118 * 119 * @param p the new probability of success. 120 * @throws IllegalArgumentException if <code>p</code> is not a valid 121 * probability. 122 */ 123 private void setProbabilityOfSuccessInternal(double p) { 124 if (p < 0.0 || p > 1.0) { 125 throw MathRuntimeException.createIllegalArgumentException( 126 LocalizedFormats.OUT_OF_RANGE_SIMPLE, p, 0.0, 1.0); 127 } 128 probabilityOfSuccess = p; 129 } 130 131 /** 132 * Access the domain value lower bound, based on <code>p</code>, used to 133 * bracket a PDF root. 134 * 135 * @param p the desired probability for the critical value 136 * @return domain value lower bound, i.e. P(X < <i>lower bound</i>) < 137 * <code>p</code> 138 */ 139 @Override 140 protected int getDomainLowerBound(double p) { 141 return -1; 142 } 143 144 /** 145 * Access the domain value upper bound, based on <code>p</code>, used to 146 * bracket a PDF root. 147 * 148 * @param p the desired probability for the critical value 149 * @return domain value upper bound, i.e. P(X < <i>upper bound</i>) > 150 * <code>p</code> 151 */ 152 @Override 153 protected int getDomainUpperBound(double p) { 154 return numberOfTrials; 155 } 156 157 /** 158 * For this distribution, X, this method returns P(X ≤ x). 159 * 160 * @param x the value at which the PDF is evaluated. 161 * @return PDF for this distribution. 162 * @throws MathException if the cumulative probability can not be computed 163 * due to convergence or other numerical errors. 164 */ 165 @Override 166 public double cumulativeProbability(int x) throws MathException { 167 double ret; 168 if (x < 0) { 169 ret = 0.0; 170 } else if (x >= numberOfTrials) { 171 ret = 1.0; 172 } else { 173 ret = 1.0 - Beta.regularizedBeta(getProbabilityOfSuccess(), 174 x + 1.0, numberOfTrials - x); 175 } 176 return ret; 177 } 178 179 /** 180 * For this distribution, X, this method returns P(X = x). 181 * 182 * @param x the value at which the PMF is evaluated. 183 * @return PMF for this distribution. 184 */ 185 public double probability(int x) { 186 double ret; 187 if (x < 0 || x > numberOfTrials) { 188 ret = 0.0; 189 } else { 190 ret = FastMath.exp(SaddlePointExpansion.logBinomialProbability(x, 191 numberOfTrials, probabilityOfSuccess, 192 1.0 - probabilityOfSuccess)); 193 } 194 return ret; 195 } 196 197 /** 198 * For this distribution, X, this method returns the largest x, such that 199 * P(X ≤ x) ≤ <code>p</code>. 200 * <p> 201 * Returns <code>-1</code> for p=0 and <code>Integer.MAX_VALUE</code> for 202 * p=1. 203 * </p> 204 * 205 * @param p the desired probability 206 * @return the largest x such that P(X ≤ x) <= p 207 * @throws MathException if the inverse cumulative probability can not be 208 * computed due to convergence or other numerical errors. 209 * @throws IllegalArgumentException if p < 0 or p > 1 210 */ 211 @Override 212 public int inverseCumulativeProbability(final double p) 213 throws MathException { 214 // handle extreme values explicitly 215 if (p == 0) { 216 return -1; 217 } 218 if (p == 1) { 219 return Integer.MAX_VALUE; 220 } 221 222 // use default bisection impl 223 return super.inverseCumulativeProbability(p); 224 } 225 226 /** 227 * Returns the lower bound of the support for the distribution. 228 * 229 * The lower bound of the support is always 0 no matter the number of trials 230 * and probability parameter. 231 * 232 * @return lower bound of the support (always 0) 233 * @since 2.2 234 */ 235 public int getSupportLowerBound() { 236 return 0; 237 } 238 239 /** 240 * Returns the upper bound of the support for the distribution. 241 * 242 * The upper bound of the support is the number of trials. 243 * 244 * @return upper bound of the support (equal to number of trials) 245 * @since 2.2 246 */ 247 public int getSupportUpperBound() { 248 return getNumberOfTrials(); 249 } 250 251 /** 252 * Returns the mean. 253 * 254 * For <code>n</code> number of trials and 255 * probability parameter <code>p</code>, the mean is 256 * <code>n * p</code> 257 * 258 * @return the mean 259 * @since 2.2 260 */ 261 public double getNumericalMean() { 262 return (double)getNumberOfTrials() * getProbabilityOfSuccess(); 263 } 264 265 /** 266 * Returns the variance. 267 * 268 * For <code>n</code> number of trials and 269 * probability parameter <code>p</code>, the variance is 270 * <code>n * p * (1 - p)</code> 271 * 272 * @return the variance 273 * @since 2.2 274 */ 275 public double getNumericalVariance() { 276 final double p = getProbabilityOfSuccess(); 277 return (double)getNumberOfTrials() * p * (1 - p); 278 } 279 }