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  
18  package org.apache.commons.math.distribution;
19  
20  /**
21   * This factory provids the means to create common statistical distributions.
22   * The following distributions are supported:
23   * <ul>
24   * <li>Binomial</li>
25   * <li>Cauchy</li>
26   * <li>Chi-Squared</li>
27   * <li>Exponential</li>
28   * <li>F</li>
29   * <li>Gamma</li>
30   * <li>HyperGeometric</li>
31   * <li>Poisson</li>
32   * <li>Normal</li>
33   * <li>Student's t</li>
34   * <li>Weibull</li>
35   * <li>Pascal</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: 545192 $ $Date: 2007-06-07 07:35:04 -0700 (Thu, 07 Jun 2007) $
46   * @deprecated pluggability of distribution instances is now provided through
47   *             constructors and setters.
48   */
49  public abstract class DistributionFactory {
50      /**
51       * Default constructor.
52       */
53      protected DistributionFactory() {
54          super();
55      }
56      
57      /**
58       * Create an instance of a <code>DistributionFactory</code>
59       * @return a new factory. 
60       */
61      public static DistributionFactory newInstance() {
62          return new DistributionFactoryImpl();
63      }
64  
65      /**
66       * Create a binomial distribution with the given number of trials and
67       * probability of success.
68       * 
69       * @param numberOfTrials the number of trials.
70       * @param probabilityOfSuccess the probability of success
71       * @return a new binomial distribution
72       */
73      public abstract BinomialDistribution createBinomialDistribution(
74          int numberOfTrials, double probabilityOfSuccess);
75      
76      /**
77       * Create a Pascal distribution with the given number of successes and
78       * probability of success.
79       * 
80       * @param numberOfSuccesses the number of successes.
81       * @param probabilityOfSuccess the probability of success
82       * @return a new Pascal distribution
83       * @since 1.2
84       */
85      public PascalDistribution createPascalDistribution(
86          int numberOfSuccesses, double probabilityOfSuccess) {
87          return new PascalDistributionImpl(numberOfSuccesses, probabilityOfSuccess);
88      }
89      
90      /**
91       * Create a new cauchy distribution with the given median and scale.
92       * @param median the median of the distribution
93       * @param scale the scale
94       * @return a new cauchy distribution  
95       * @since 1.1
96       */           
97      public CauchyDistribution createCauchyDistribution(
98          double median, double scale)
99      {
100         return new CauchyDistributionImpl(median, scale);
101     }
102         
103     /**
104      * Create a new chi-square distribution with the given degrees of freedom.
105      * 
106      * @param degreesOfFreedom degrees of freedom
107      * @return a new chi-square distribution  
108      */
109     public abstract ChiSquaredDistribution createChiSquareDistribution(
110         double degreesOfFreedom);
111     
112     /**
113      * Create a new exponential distribution with the given degrees of freedom.
114      * 
115      * @param mean mean
116      * @return a new exponential distribution  
117      */
118     public abstract ExponentialDistribution createExponentialDistribution(
119         double mean);
120     
121     /**
122      * Create a new F-distribution with the given degrees of freedom.
123      * 
124      * @param numeratorDegreesOfFreedom numerator degrees of freedom
125      * @param denominatorDegreesOfFreedom denominator degrees of freedom
126      * @return a new F-distribution 
127      */
128     public abstract FDistribution createFDistribution(
129         double numeratorDegreesOfFreedom, double denominatorDegreesOfFreedom);
130     
131     /**
132      * Create a new gamma distribution with the given shape and scale
133      * parameters.
134      * 
135      * @param alpha the shape parameter
136      * @param beta the scale parameter
137      * 
138      * @return a new gamma distribution  
139      */
140     public abstract GammaDistribution createGammaDistribution(
141         double alpha, double beta);
142 
143     /**
144      * Create a new t distribution with the given degrees of freedom.
145      * 
146      * @param degreesOfFreedom degrees of freedom
147      * @return a new t distribution  
148      */
149     public abstract TDistribution createTDistribution(double degreesOfFreedom);
150     
151     /**
152      * Create a new hypergeometric distribution with the given the population
153      * size, the number of successes in the population, and the sample size.
154      * 
155      * @param populationSize the population size
156      * @param numberOfSuccesses number of successes in the population
157      * @param sampleSize the sample size
158      * @return a new hypergeometric desitribution
159      */
160     public abstract HypergeometricDistribution
161         createHypergeometricDistribution(int populationSize,
162             int numberOfSuccesses, int sampleSize);
163  
164     /**
165      * Create a new normal distribution with the given mean and standard
166      * deviation.
167      * 
168      * @param mean the mean of the distribution
169      * @param sd standard deviation
170      * @return a new normal distribution  
171      */           
172     public abstract NormalDistribution 
173         createNormalDistribution(double mean, double sd);
174         
175     /**
176      * Create a new normal distribution with mean zero and standard
177      * deviation one.
178      * 
179      * @return a new normal distribution.  
180      */               
181     public abstract NormalDistribution createNormalDistribution();
182     
183     /**
184      * Create a new Poisson distribution with poisson parameter lambda.
185      * 
186      * @param lambda poisson parameter
187      * @return a new poisson distribution.  
188      */               
189     public abstract PoissonDistribution 
190         createPoissonDistribution(double lambda);
191     
192     /**
193      * Create a new Weibull distribution with the given shape and scale
194      * parameters.
195      * 
196      * @param alpha the shape parameter.
197      * @param beta the scale parameter.
198      * @return a new Weibull distribution.  
199      * @since 1.1
200      */               
201     public WeibullDistribution createWeibullDistribution(
202         double alpha, double beta)
203     {
204         return new WeibullDistributionImpl(alpha, beta);
205     }
206 }