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    *      https://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  /*
19   * This is not the original file distributed by the Apache Software Foundation
20   * It has been modified by the Hipparchus project
21   */
22  package org.hipparchus.distribution;
23  
24  import org.hipparchus.exception.MathIllegalArgumentException;
25  
26  /**
27   * Interface for discrete distributions.
28   */
29  public interface IntegerDistribution {
30  
31      /**
32       * For a random variable {@code X} whose values are distributed according to
33       * this distribution, this method returns {@code log(P(X = x))}, where
34       * {@code log} is the natural logarithm. In other words, this method
35       * represents the logarithm of the probability mass function (PMF) for the
36       * distribution. Note that due to the floating point precision and
37       * under/overflow issues, this method will for some distributions be more
38       * precise and faster than computing the logarithm of
39       * {@link #probability(int)}.
40       *
41       * @param x the point at which the PMF is evaluated
42       * @return the logarithm of the value of the probability mass function at {@code x}
43       */
44      double logProbability(int x);
45  
46      /**
47       * For a random variable {@code X} whose values are distributed according
48       * to this distribution, this method returns {@code P(X = x)}. In other
49       * words, this method represents the probability mass function (PMF)
50       * for the distribution.
51       *
52       * @param x the point at which the PMF is evaluated
53       * @return the value of the probability mass function at {@code x}
54       */
55      double probability(int x);
56  
57      /**
58       * For a random variable {@code X} whose values are distributed according
59       * to this distribution, this method returns {@code P(x0 < X <= x1)}.
60       *
61       * @param x0 the exclusive lower bound
62       * @param x1 the inclusive upper bound
63       * @return the probability that a random variable with this distribution
64       * will take a value between {@code x0} and {@code x1},
65       * excluding the lower and including the upper endpoint
66       * @throws MathIllegalArgumentException if {@code x0 > x1}
67       */
68      double probability(int x0, int x1) throws MathIllegalArgumentException;
69  
70      /**
71       * For a random variable {@code X} whose values are distributed according
72       * to this distribution, this method returns {@code P(X <= x)}.  In other
73       * words, this method represents the (cumulative) distribution function
74       * (CDF) for this distribution.
75       *
76       * @param x the point at which the CDF is evaluated
77       * @return the probability that a random variable with this
78       * distribution takes a value less than or equal to {@code x}
79       */
80      double cumulativeProbability(int x);
81  
82      /**
83       * Computes the quantile function of this distribution.
84       * For a random variable {@code X} distributed according to this distribution,
85       * the returned value is
86       * <ul>
87       * <li><code>inf{x in Z | P(X&lt;=x) &gt;= p}</code> for {@code 0 < p <= 1},</li>
88       * <li><code>inf{x in Z | P(X&lt;=x) &gt; 0}</code> for {@code p = 0}.</li>
89       * </ul>
90       * If the result exceeds the range of the data type {@code int},
91       * then {@code Integer.MIN_VALUE} or {@code Integer.MAX_VALUE} is returned.
92       *
93       * @param p the cumulative probability
94       * @return the smallest {@code p}-quantile of this distribution
95       * (largest 0-quantile for {@code p = 0})
96       * @throws MathIllegalArgumentException if {@code p < 0} or {@code p > 1}
97       */
98      int inverseCumulativeProbability(double p) throws MathIllegalArgumentException;
99  
100     /**
101      * Use this method to get the numerical value of the mean of this
102      * distribution.
103      *
104      * @return the mean or {@code Double.NaN} if it is not defined
105      */
106     double getNumericalMean();
107 
108     /**
109      * Use this method to get the numerical value of the variance of this
110      * distribution.
111      *
112      * @return the variance (possibly {@code Double.POSITIVE_INFINITY} or
113      * {@code Double.NaN} if it 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 Z | P(X &lt;= x) &gt; 0}</code>.</p>
122      *
123      * @return lower bound of the support ({@code Integer.MIN_VALUE}
124      * for negative infinity)
125      */
126     int 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 &lt;= x) = 1}</code>.</p>
133      *
134      * @return upper bound of the support ({@code Integer.MAX_VALUE}
135      * for positive infinity)
136      */
137     int getSupportUpperBound();
138 
139     /**
140      * Use this method to get information about whether the support is
141      * connected, i.e. whether all integers between the lower and upper bound of
142      * the support are included in the support.
143      *
144      * @return whether the support is connected or not
145      */
146     boolean isSupportConnected();
147 
148 }