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.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 }