View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.math.distribution;
18  
19  import java.io.Serializable;
20  
21  import org.apache.commons.math.MathException;
22  import org.apache.commons.math.MathRuntimeException;
23  
24  /**
25   * The default implementation of {@link ExponentialDistribution}.
26   *
27   * @version $Revision: 772119 $ $Date: 2009-05-06 05:43:28 -0400 (Wed, 06 May 2009) $
28   */
29  public class ExponentialDistributionImpl extends AbstractContinuousDistribution
30      implements ExponentialDistribution, Serializable {
31  
32      /** Serializable version identifier */
33      private static final long serialVersionUID = 2401296428283614780L;
34      
35      /** The mean of this distribution. */
36      private double mean;
37      
38      /**
39       * Create a exponential distribution with the given mean.
40       * @param mean mean of this distribution.
41       */
42      public ExponentialDistributionImpl(double mean) {
43          super();
44          setMean(mean);
45      }
46  
47      /**
48       * Modify the mean.
49       * @param mean the new mean.
50       * @throws IllegalArgumentException if <code>mean</code> is not positive.
51       */
52      public void setMean(double mean) {
53          if (mean <= 0.0) {
54              throw MathRuntimeException.createIllegalArgumentException(
55                    "mean must be positive ({0})", mean);
56          }
57          this.mean = mean;
58      }
59  
60      /**
61       * Access the mean.
62       * @return the mean.
63       */
64      public double getMean() {
65          return mean;
66      }
67  
68      /**
69       * Return the probability density for a particular point.
70       *
71       * @param x The point at which the density should be computed.
72       * @return The pdf at point x.
73       */
74      public double density(Double x) {
75          if (x < 0) {
76              return 0;
77          }
78          return Math.exp(-x / getMean()) / getMean();
79      }
80  
81      /**
82       * For this distribution, X, this method returns P(X &lt; x).
83       * 
84       * The implementation of this method is based on:
85       * <ul>
86       * <li>
87       * <a href="http://mathworld.wolfram.com/ExponentialDistribution.html">
88       * Exponential Distribution</a>, equation (1).</li>
89       * </ul>
90       * 
91       * @param x the value at which the CDF is evaluated.
92       * @return CDF for this distribution.
93       * @throws MathException if the cumulative probability can not be
94       *            computed due to convergence or other numerical errors.
95       */
96      public double cumulativeProbability(double x) throws MathException{
97          double ret;
98          if (x <= 0.0) {
99              ret = 0.0;
100         } else {
101             ret = 1.0 - Math.exp(-x / getMean());
102         }
103         return ret;
104     }
105     
106     /**
107      * For this distribution, X, this method returns the critical point x, such
108      * that P(X &lt; x) = <code>p</code>.
109      * <p>
110      * Returns 0 for p=0 and <code>Double.POSITIVE_INFINITY</code> for p=1.</p>
111      * 
112      * @param p the desired probability
113      * @return x, such that P(X &lt; x) = <code>p</code>
114      * @throws MathException if the inverse cumulative probability can not be
115      *            computed due to convergence or other numerical errors.
116      * @throws IllegalArgumentException if p < 0 or p > 1.
117      */
118     @Override
119     public double inverseCumulativeProbability(double p) throws MathException {
120         double ret;
121         
122         if (p < 0.0 || p > 1.0) {
123             throw MathRuntimeException.createIllegalArgumentException(
124                   "{0} out of [{1}, {2}] range", p, 0.0, 1.0);
125         } else if (p == 1.0) {
126             ret = Double.POSITIVE_INFINITY;
127         } else {
128             ret = -getMean() * Math.log(1.0 - p);
129         }
130         
131         return ret;
132     }
133     
134     /**
135      * Access the domain value lower bound, based on <code>p</code>, used to
136      * bracket a CDF root.   
137      * 
138      * @param p the desired probability for the critical value
139      * @return domain value lower bound, i.e.
140      *         P(X &lt; <i>lower bound</i>) &lt; <code>p</code>
141      */
142     @Override
143     protected double getDomainLowerBound(double p) {
144         return 0;
145     }
146     
147     /**
148      * Access the domain value upper bound, based on <code>p</code>, used to
149      * bracket a CDF root.   
150      * 
151      * @param p the desired probability for the critical value
152      * @return domain value upper bound, i.e.
153      *         P(X &lt; <i>upper bound</i>) &gt; <code>p</code> 
154      */
155     @Override
156     protected double getDomainUpperBound(double p) {
157         // NOTE: exponential is skewed to the left
158         // NOTE: therefore, P(X < &mu;) > .5
159 
160         if (p < .5) {
161             // use mean
162             return getMean();
163         } else {
164             // use max
165             return Double.MAX_VALUE;
166         }
167     }
168     
169     /**
170      * Access the initial domain value, based on <code>p</code>, used to
171      * bracket a CDF root.   
172      * 
173      * @param p the desired probability for the critical value
174      * @return initial domain value
175      */
176     @Override
177     protected double getInitialDomain(double p) {
178         // TODO: try to improve on this estimate
179         // TODO: what should really happen here is not derive from AbstractContinuousDistribution
180         // TODO: because the inverse cumulative distribution is simple.
181         // Exponential is skewed to the left, therefore, P(X < &mu;) > .5
182         if (p < .5) {
183             // use 1/2 mean
184             return getMean() * .5;
185         } else {
186             // use mean
187             return getMean();
188         }
189     }
190 }