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  package org.apache.commons.math3.distribution;
18  
19  import org.apache.commons.math3.exception.NumberIsTooLargeException;
20  import org.apache.commons.math3.exception.OutOfRangeException;
21  
22  /**
23   * Base interface for distributions on the reals.
24   *
25   * @version $Id: RealDistribution.java 1499808 2013-07-04 17:00:42Z sebb $
26   * @since 3.0
27   */
28  public interface RealDistribution {
29      /**
30       * For a random variable {@code X} whose values are distributed according
31       * to this distribution, this method returns {@code P(X = x)}. In other
32       * words, this method represents the probability mass function (PMF)
33       * for the distribution.
34       *
35       * @param x the point at which the PMF is evaluated
36       * @return the value of the probability mass function at point {@code x}
37       */
38      double probability(double x);
39  
40      /**
41       * Returns the probability density function (PDF) of this distribution
42       * evaluated at the specified point {@code x}. In general, the PDF is
43       * the derivative of the {@link #cumulativeProbability(double) CDF}.
44       * If the derivative does not exist at {@code x}, then an appropriate
45       * replacement should be returned, e.g. {@code Double.POSITIVE_INFINITY},
46       * {@code Double.NaN}, or  the limit inferior or limit superior of the
47       * difference quotient.
48       *
49       * @param x the point at which the PDF is evaluated
50       * @return the value of the probability density function at point {@code x}
51       */
52      double density(double x);
53  
54      /**
55       * For a random variable {@code X} whose values are distributed according
56       * to this distribution, this method returns {@code P(X <= x)}. In other
57       * words, this method represents the (cumulative) distribution function
58       * (CDF) for this distribution.
59       *
60       * @param x the point at which the CDF is evaluated
61       * @return the probability that a random variable with this
62       * distribution takes a value less than or equal to {@code x}
63       */
64      double cumulativeProbability(double x);
65  
66      /**
67       * For a random variable {@code X} whose values are distributed according
68       * to this distribution, this method returns {@code P(x0 < X <= x1)}.
69       *
70       * @param x0 the exclusive lower bound
71       * @param x1 the inclusive upper bound
72       * @return the probability that a random variable with this distribution
73       * takes a value between {@code x0} and {@code x1},
74       * excluding the lower and including the upper endpoint
75       * @throws NumberIsTooLargeException if {@code x0 > x1}
76       *
77       * @deprecated As of 3.1. In 4.0, this method will be renamed
78       * {@code probability(double x0, double x1)}.
79       */
80      @Deprecated
81      double cumulativeProbability(double x0, double x1) throws NumberIsTooLargeException;
82  
83      /**
84       * Computes the quantile function of this distribution. For a random
85       * variable {@code X} distributed according to this distribution, the
86       * returned value is
87       * <ul>
88       * <li><code>inf{x in R | P(X<=x) >= p}</code> for {@code 0 < p <= 1},</li>
89       * <li><code>inf{x in R | P(X<=x) > 0}</code> for {@code p = 0}.</li>
90       * </ul>
91       *
92       * @param p the cumulative probability
93       * @return the smallest {@code p}-quantile of this distribution
94       * (largest 0-quantile for {@code p = 0})
95       * @throws OutOfRangeException if {@code p < 0} or {@code p > 1}
96       */
97      double inverseCumulativeProbability(double p) throws OutOfRangeException;
98  
99      /**
100      * Use this method to get the numerical value of the mean of this
101      * distribution.
102      *
103      * @return the mean or {@code Double.NaN} if it is not defined
104      */
105     double getNumericalMean();
106 
107     /**
108      * Use this method to get the numerical value of the variance of this
109      * distribution.
110      *
111      * @return the variance (possibly {@code Double.POSITIVE_INFINITY} as
112      * for certain cases in {@link TDistribution}) or {@code Double.NaN} if it
113      * is not defined
114      */
115     double getNumericalVariance();
116 
117     /**
118      * Access the lower bound of the support. This method must return the same
119      * value as {@code inverseCumulativeProbability(0)}. In other words, this
120      * method must return
121      * <p><code>inf {x in R | P(X <= x) > 0}</code>.</p>
122      *
123      * @return lower bound of the support (might be
124      * {@code Double.NEGATIVE_INFINITY})
125      */
126     double getSupportLowerBound();
127 
128     /**
129      * Access the upper bound of the support. This method must return the same
130      * value as {@code inverseCumulativeProbability(1)}. In other words, this
131      * method must return
132      * <p><code>inf {x in R | P(X <= x) = 1}</code>.</p>
133      *
134      * @return upper bound of the support (might be
135      * {@code Double.POSITIVE_INFINITY})
136      */
137     double getSupportUpperBound();
138 
139     /**
140      * Whether or not the lower bound of support is in the domain of the density
141      * function.  Returns true iff {@code getSupporLowerBound()} is finite and
142      * {@code density(getSupportLowerBound())} returns a non-NaN, non-infinite
143      * value.
144      *
145      * @return true if the lower bound of support is finite and the density
146      * function returns a non-NaN, non-infinite value there
147      * @deprecated to be removed in 4.0
148      */
149     @Deprecated
150     boolean isSupportLowerBoundInclusive();
151 
152     /**
153      * Whether or not the upper bound of support is in the domain of the density
154      * function.  Returns true iff {@code getSupportUpperBound()} is finite and
155      * {@code density(getSupportUpperBound())} returns a non-NaN, non-infinite
156      * value.
157      *
158      * @return true if the upper bound of support is finite and the density
159      * function returns a non-NaN, non-infinite value there
160      * @deprecated to be removed in 4.0
161      */
162     @Deprecated
163     boolean isSupportUpperBoundInclusive();
164 
165     /**
166      * Use this method to get information about whether the support is connected,
167      * i.e. whether all values between the lower and upper bound of the support
168      * are included in the support.
169      *
170      * @return whether the support is connected or not
171      */
172     boolean isSupportConnected();
173 
174     /**
175      * Reseed the random generator used to generate samples.
176      *
177      * @param seed the new seed
178      */
179     void reseedRandomGenerator(long seed);
180 
181     /**
182      * Generate a random value sampled from this distribution.
183      *
184      * @return a random value.
185      */
186     double sample();
187 
188     /**
189      * Generate a random sample from the distribution.
190      *
191      * @param sampleSize the number of random values to generate
192      * @return an array representing the random sample
193      * @throws org.apache.commons.math3.exception.NotStrictlyPositiveException
194      * if {@code sampleSize} is not positive
195      */
196     double[] sample(int sampleSize);
197 }