View Javadoc

1   /*
2    * Copyright 2003-2005 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.apache.commons.math.distribution;
18  
19  import org.apache.commons.discovery.tools.DiscoverClass;
20  
21  /**
22   * This factory provids the means to create common statistical distributions.
23   * The following distributions are supported:
24   * <ul>
25   * <li>Binomial</li>
26   * <li>Cauchy</li>
27   * <li>Chi-Squared</li>
28   * <li>Exponential</li>
29   * <li>F</li>
30   * <li>Gamma</li>
31   * <li>HyperGeometric</li>
32   * <li>Poisson</li>
33   * <li>Normal</li>
34   * <li>Student's t</li>
35   * <li>Weibull</li>
36   * </ul>
37   *
38   * Common usage:<pre>
39   * DistributionFactory factory = DistributionFactory.newInstance();
40   *
41   * // create a Chi-Square distribution with 5 degrees of freedom.
42   * ChiSquaredDistribution chi = factory.createChiSquareDistribution(5.0);
43   * </pre>
44   *
45   * @version $Revision: 201915 $ $Date: 2005-06-26 15:20:57 -0700 (Sun, 26 Jun 2005) $
46   */
47  public abstract class DistributionFactory {
48      /**
49       * Default constructor.
50       */
51      protected DistributionFactory() {
52          super();
53      }
54      
55      /**
56       * Create an instance of a <code>DistributionFactory</code>
57       * @return a new factory. 
58       */
59      public static DistributionFactory newInstance() {
60          DistributionFactory factory = null;
61          try {
62              DiscoverClass dc = new DiscoverClass();
63              factory = (DistributionFactory) dc.newInstance(
64                  DistributionFactory.class,
65                  "org.apache.commons.math.distribution.DistributionFactoryImpl");
66          } catch(Throwable t) {
67              return new DistributionFactoryImpl();
68          }
69          return factory;
70      }
71  
72      /**
73       * Create a binomial distribution with the given number of trials and
74       * probability of success.
75       * 
76       * @param numberOfTrials the number of trials.
77       * @param probabilityOfSuccess the probability of success
78       * @return a new binomial distribution
79       */
80      public abstract BinomialDistribution createBinomialDistribution(
81          int numberOfTrials, double probabilityOfSuccess);
82      
83      /**
84       * Create a new cauchy distribution with the given median and scale.
85       * @param median the median of the distribution
86       * @param scale the scale
87       * @return a new cauchy distribution  
88       * @since 1.1
89       */           
90      public CauchyDistribution createCauchyDistribution(
91          double median, double scale)
92      {
93          return new CauchyDistributionImpl(median, scale);
94      }
95          
96      /**
97       * Create a new chi-square distribution with the given degrees of freedom.
98       * 
99       * @param degreesOfFreedom degrees of freedom
100      * @return a new chi-square distribution  
101      */
102     public abstract ChiSquaredDistribution createChiSquareDistribution(
103         double degreesOfFreedom);
104     
105     /**
106      * Create a new exponential distribution with the given degrees of freedom.
107      * 
108      * @param mean mean
109      * @return a new exponential distribution  
110      */
111     public abstract ExponentialDistribution createExponentialDistribution(
112         double mean);
113     
114     /**
115      * Create a new F-distribution with the given degrees of freedom.
116      * 
117      * @param numeratorDegreesOfFreedom numerator degrees of freedom
118      * @param denominatorDegreesOfFreedom denominator degrees of freedom
119      * @return a new F-distribution 
120      */
121     public abstract FDistribution createFDistribution(
122         double numeratorDegreesOfFreedom, double denominatorDegreesOfFreedom);
123     
124     /**
125      * Create a new gamma distribution with the given shape and scale
126      * parameters.
127      * 
128      * @param alpha the shape parameter
129      * @param beta the scale parameter
130      * 
131      * @return a new gamma distribution  
132      */
133     public abstract GammaDistribution createGammaDistribution(
134         double alpha, double beta);
135 
136     /**
137      * Create a new t distribution with the given degrees of freedom.
138      * 
139      * @param degreesOfFreedom degrees of freedom
140      * @return a new t distribution  
141      */
142     public abstract TDistribution createTDistribution(double degreesOfFreedom);
143     
144     /**
145      * Create a new hypergeometric distribution with the given the population
146      * size, the number of successes in the population, and the sample size.
147      * 
148      * @param populationSize the population size
149      * @param numberOfSuccesses number of successes in the population
150      * @param sampleSize the sample size
151      * @return a new hypergeometric desitribution
152      */
153     public abstract HypergeometricDistribution
154         createHypergeometricDistribution(int populationSize,
155             int numberOfSuccesses, int sampleSize);
156  
157     /**
158      * Create a new normal distribution with the given mean and standard
159      * deviation.
160      * 
161      * @param mean the mean of the distribution
162      * @param sd standard deviation
163      * @return a new normal distribution  
164      */           
165     public abstract NormalDistribution 
166         createNormalDistribution(double mean, double sd);
167         
168     /**
169      * Create a new normal distribution with mean zero and standard
170      * deviation one.
171      * 
172      * @return a new normal distribution.  
173      */               
174     public abstract NormalDistribution createNormalDistribution();
175     
176     /**
177      * Create a new Poisson distribution with poisson parameter lambda.
178      * 
179      * @param lambda poisson parameter
180      * @return a new poisson distribution.  
181      */               
182     public abstract PoissonDistribution 
183         createPoissonDistribution(double lambda);
184     
185     /**
186      * Create a new Weibull distribution with the given shape and scale
187      * parameters.
188      * 
189      * @param alpha the shape parameter.
190      * @param beta the scale parameter.
191      * @return a new Weibull distribution.  
192      * @since 1.1
193      */               
194     public WeibullDistribution createWeibullDistribution(
195         double alpha, double beta)
196     {
197         return new WeibullDistributionImpl(alpha, beta);
198     }
199 }