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 }