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<=x) >= p}</code> for {@code 0 < p <= 1},</li>
88 * <li><code>inf{x in Z | P(X<=x) > 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 <= x) > 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 <= 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 }