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 }