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
9
* http://www.apache.org/licenses/LICENSE-2.0
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.
18
package org.apache.commons.math.random;
20
import java.io.IOException;
23
import java.util.List;
25
import org.apache.commons.math.stat.descriptive.StatisticalSummary;
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>
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>
47
* @version $Revision: 615734 $ $Date: 2008-01-27 23:10:03 -0700 (Sun, 27 Jan 2008) $
49
public interface EmpiricalDistribution {
52
* Computes the empirical distribution from the provided
55
* @param dataArray the data array
57
void load(double[] dataArray);
60
* Computes the empirical distribution from the input file.
62
* @param file the input file
63
* @throws IOException if an IO error occurs
65
void load(File file) throws IOException;
68
* Computes the empirical distribution using data read from a URL.
70
* @param url url of the input file
71
* @throws IOException if an IO error occurs
73
void load(URL url) throws IOException;
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.
81
* @throws IllegalStateException if the distribution has not been loaded
83
double getNextValue() throws IllegalStateException;
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>
94
* @return the sample statistics
95
* @throws IllegalStateException if the distribution has not been loaded
97
StatisticalSummary getSampleStats() throws IllegalStateException;
100
* Property indicating whether or not the distribution has been loaded.
102
* @return true if the distribution has been loaded
107
* Returns the number of bins.
109
* @return the number of bins
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.
119
* @return List of bin statistics
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].
128
* @return array of bin upper bounds
130
double[] getUpperBounds();