001: /*
002: * Copyright 2003-2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.apache.commons.math.random;
018:
019: import java.io.IOException;
020: import java.io.File;
021: import java.net.URL;
022: import java.util.List;
023:
024: import org.apache.commons.math.stat.descriptive.StatisticalSummary;
025:
026: /**
027: * Represents an <a href="http://random.mat.sbg.ac.at/~ste/dipl/node11.html">
028: * empirical probability distribution</a> -- a probability distribution derived
029: * from observed data without making any assumptions about the functional form
030: * of the population distribution that the data come from.<p>
031: * Implementations of this interface maintain data structures, called
032: * <i>distribution digests</i>, that describe empirical distributions and
033: * support the following operations: <ul>
034: * <li>loading the distribution from a file of observed data values</li>
035: * <li>dividing the input data into "bin ranges" and reporting bin frequency
036: * counts (data for histogram)</li>
037: * <li>reporting univariate statistics describing the full set of data values
038: * as well as the observations within each bin</li>
039: * <li>generating random values from the distribution</li>
040: * </ul>
041: * Applications can use <code>EmpiricalDistribution</code> implementations to
042: * build grouped frequnecy histograms representing the input data or to
043: * generate random values "like" those in the input file -- i.e., the values
044: * generated will follow the distribution of the values in the file.
045: *
046: * @version $Revision: 155427 $ $Date: 2005-02-26 06:11:52 -0700 (Sat, 26 Feb 2005) $
047: */
048: public interface EmpiricalDistribution {
049:
050: /**
051: * Computes the empirical distribution from the provided
052: * array of numbers.
053: *
054: * @param dataArray the data array
055: */
056: void load(double[] dataArray);
057:
058: /**
059: * Computes the empirical distribution from the input file.
060: *
061: * @param file the input file
062: * @throws IOException if an IO error occurs
063: */
064: void load(File file) throws IOException;
065:
066: /**
067: * Computes the empirical distribution using data read from a URL.
068: *
069: * @param url url of the input file
070: * @throws IOException if an IO error occurs
071: */
072: void load(URL url) throws IOException;
073:
074: /**
075: * Generates a random value from this distribution.
076: * <strong>Preconditions:</strong><ul>
077: * <li>the distribution must be loaded before invoking this method</li></ul>
078: * @return the random value.
079: *
080: * @throws IllegalStateException if the distribution has not been loaded
081: */
082: double getNextValue() throws IllegalStateException;
083:
084: /**
085: * Returns a
086: * {@link org.apache.commons.math.stat.descriptive.StatisticalSummary}
087: * describing this distribution.
088: * <strong>Preconditions:</strong><ul>
089: * <li>the distribution must be loaded before invoking this method</li>
090: * </ul>
091: *
092: * @return the sample statistics
093: * @throws IllegalStateException if the distribution has not been loaded
094: */
095: StatisticalSummary getSampleStats() throws IllegalStateException;
096:
097: /**
098: * Property indicating whether or not the distribution has been loaded.
099: *
100: * @return true if the distribution has been loaded
101: */
102: boolean isLoaded();
103:
104: /**
105: * Returns the number of bins.
106: *
107: * @return the number of bins
108: */
109: int getBinCount();
110:
111: /**
112: * Returns a list of
113: * {@link org.apache.commons.math.stat.descriptive.SummaryStatistics}
114: * containing statistics describing the values in each of the bins. The
115: * List is indexed on the bin number.
116: *
117: * @return List of bin statistics
118: */
119: List getBinStats();
120:
121: /**
122: * Returns the array of upper bounds for the bins. Bins are: <br/>
123: * [min,upperBounds[0]],(upperBounds[0],upperBounds[1]],...,
124: * (upperBounds[binCount-1],max].
125: *
126: * @return array of bin upper bounds
127: */
128: double[] getUpperBounds();
129:
130: }
|