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.random;
19
20 import java.io.IOException;
21 import java.io.File;
22 import java.net.URL;
23 import java.util.List;
24
25 import org.apache.commons.math.stat.descriptive.StatisticalSummary;
26
27 /**
28 * Represents an <a href="http://random.mat.sbg.ac.at/~ste/dipl/node11.html">
29 * empirical probability distribution</a> -- a probability distribution derived
30 * from observed data without making any assumptions about the functional form
31 * of the population distribution that the data come from.<p>
32 * Implementations of this interface maintain data structures, called
33 * <i>distribution digests</i>, that describe empirical distributions and
34 * support the following operations: <ul>
35 * <li>loading the distribution from a file of observed data values</li>
36 * <li>dividing the input data into "bin ranges" and reporting bin frequency
37 * counts (data for histogram)</li>
38 * <li>reporting univariate statistics describing the full set of data values
39 * as well as the observations within each bin</li>
40 * <li>generating random values from the distribution</li>
41 * </ul>
42 * Applications can use <code>EmpiricalDistribution</code> implementations to
43 * build grouped frequency histograms representing the input data or to
44 * generate random values "like" those in the input file -- i.e., the values
45 * generated will follow the distribution of the values in the file.</p>
46 *
47 * @version $Revision: 615734 $ $Date: 2008-01-27 23:10:03 -0700 (Sun, 27 Jan 2008) $
48 */
49 public interface EmpiricalDistribution {
50
51 /**
52 * Computes the empirical distribution from the provided
53 * array of numbers.
54 *
55 * @param dataArray the data array
56 */
57 void load(double[] dataArray);
58
59 /**
60 * Computes the empirical distribution from the input file.
61 *
62 * @param file the input file
63 * @throws IOException if an IO error occurs
64 */
65 void load(File file) throws IOException;
66
67 /**
68 * Computes the empirical distribution using data read from a URL.
69 *
70 * @param url url of the input file
71 * @throws IOException if an IO error occurs
72 */
73 void load(URL url) throws IOException;
74
75 /**
76 * Generates a random value from this distribution.
77 * <strong>Preconditions:</strong><ul>
78 * <li>the distribution must be loaded before invoking this method</li></ul>
79 * @return the random value.
80 *
81 * @throws IllegalStateException if the distribution has not been loaded
82 */
83 double getNextValue() throws IllegalStateException;
84
85
86 /**
87 * Returns a
88 * {@link org.apache.commons.math.stat.descriptive.StatisticalSummary}
89 * describing this distribution.
90 * <strong>Preconditions:</strong><ul>
91 * <li>the distribution must be loaded before invoking this method</li>
92 * </ul>
93 *
94 * @return the sample statistics
95 * @throws IllegalStateException if the distribution has not been loaded
96 */
97 StatisticalSummary getSampleStats() throws IllegalStateException;
98
99 /**
100 * Property indicating whether or not the distribution has been loaded.
101 *
102 * @return true if the distribution has been loaded
103 */
104 boolean isLoaded();
105
106 /**
107 * Returns the number of bins.
108 *
109 * @return the number of bins
110 */
111 int getBinCount();
112
113 /**
114 * Returns a list of
115 * {@link org.apache.commons.math.stat.descriptive.SummaryStatistics}
116 * containing statistics describing the values in each of the bins. The
117 * List is indexed on the bin number.
118 *
119 * @return List of bin statistics
120 */
121 List getBinStats();
122
123 /**
124 * Returns the array of upper bounds for the bins. Bins are: <br/>
125 * [min,upperBounds[0]],(upperBounds[0],upperBounds[1]],...,
126 * (upperBounds[binCount-1],max].
127 *
128 * @return array of bin upper bounds
129 */
130 double[] getUpperBounds();
131
132 }