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 }