    001    /*
    002     * Licensed to the Apache Software Foundation (ASF) under one or more
    003     * contributor license agreements.  See the NOTICE file distributed with
    004     * this work for additional information regarding copyright ownership.
    005     * The ASF licenses this file to You under the Apache License, Version 2.0
    006     * (the "License"); you may not use this file except in compliance with
    007     * the License.  You may obtain a copy of the License at
    008     *
    009     *      http://www.apache.org/licenses/LICENSE-2.0
    010     *
    011     * Unless required by applicable law or agreed to in writing, software
    012     * distributed under the License is distributed on an "AS IS" BASIS,
    013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014     * See the License for the specific language governing permissions and
    015     * limitations under the License.
    016     */
    017    package org.apache.commons.math3.distribution;
    018
    019    import org.apache.commons.math3.exception.NumberIsTooLargeException;
    020    import org.apache.commons.math3.exception.OutOfRangeException;
    021
    022    /**
    023     * Interface for distributions on the integers.
    024     *
    025     * @version $Id: IntegerDistribution.java 1416643 2012-12-03 19:37:14Z tn $
    026     */
    027    public interface IntegerDistribution {
    028        /**
    029         * For a random variable {@code X} whose values are distributed according
    030         * to this distribution, this method returns {@code P(X = x)}. In other
    031         * words, this method represents the probability mass function (PMF)
    032         * for the distribution.
    033         *
    034         * @param x the point at which the PMF is evaluated
    035         * @return the value of the probability mass function at {@code x}
    036         */
    037        double probability(int x);
    038
    039        /**
    040         * For a random variable {@code X} whose values are distributed according
    041         * to this distribution, this method returns {@code P(X <= x)}.  In other
    042         * words, this method represents the (cumulative) distribution function
    043         * (CDF) for this distribution.
    044         *
    045         * @param x the point at which the CDF is evaluated
    046         * @return the probability that a random variable with this
    047         * distribution takes a value less than or equal to {@code x}
    048         */
    049        double cumulativeProbability(int x);
    050
    051        /**
    052         * For a random variable {@code X} whose values are distributed according
    053         * to this distribution, this method returns {@code P(x0 < X <= x1)}.
    054         *
    055         * @param x0 the exclusive lower bound
    056         * @param x1 the inclusive upper bound
    057         * @return the probability that a random variable with this distribution
    058         * will take a value between {@code x0} and {@code x1},
    059         * excluding the lower and including the upper endpoint
    060         * @throws NumberIsTooLargeException if {@code x0 > x1}
    061         */
    062        double cumulativeProbability(int x0, int x1) throws NumberIsTooLargeException;
    063
    064        /**
    065         * Computes the quantile function of this distribution.
    066         * For a random variable {@code X} distributed according to this distribution,
    067         * the returned value is
    068         * <ul>
    069         * <li><code>inf{x in Z | P(X<=x) >= p}</code> for {@code 0 < p <= 1},</li>
    070         * <li><code>inf{x in Z | P(X<=x) > 0}</code> for {@code p = 0}.</li>
    071         * </ul>
    072         * If the result exceeds the range of the data type {@code int},
    073         * then {@code Integer.MIN_VALUE} or {@code Integer.MAX_VALUE} is returned.
    074         *
    075         * @param p the cumulative probability
    076         * @return the smallest {@code p}-quantile of this distribution
    077         * (largest 0-quantile for {@code p = 0})
    078         * @throws OutOfRangeException if {@code p < 0} or {@code p > 1}
    079         */
    080        int inverseCumulativeProbability(double p) throws OutOfRangeException;
    081
    082        /**
    083         * Use this method to get the numerical value of the mean of this
    084         * distribution.
    085         *
    086         * @return the mean or {@code Double.NaN} if it is not defined
    087         */
    088        double getNumericalMean();
    089
    090        /**
    091         * Use this method to get the numerical value of the variance of this
    092         * distribution.
    093         *
    094         * @return the variance (possibly {@code Double.POSITIVE_INFINITY} or
    095         * {@code Double.NaN} if it is not defined)
    096         */
    097        double getNumericalVariance();
    098
    099        /**
    100         * Access the lower bound of the support. This method must return the same
    101         * value as {@code inverseCumulativeProbability(0)}. In other words, this
    102         * method must return
    103         * <p><code>inf {x in Z | P(X <= x) > 0}</code>.</p>
    104         *
    105         * @return lower bound of the support ({@code Integer.MIN_VALUE}
    106         * for negative infinity)
    107         */
    108        int getSupportLowerBound();
    109
    110        /**
    111         * Access the upper bound of the support. This method must return the same
    112         * value as {@code inverseCumulativeProbability(1)}. In other words, this
    113         * method must return
    114         * <p><code>inf {x in R | P(X <= x) = 1}</code>.</p>
    115         *
    116         * @return upper bound of the support ({@code Integer.MAX_VALUE}
    117         * for positive infinity)
    118         */
    119        int getSupportUpperBound();
    120
    121        /**
    122         * Use this method to get information about whether the support is
    123         * connected, i.e. whether all integers between the lower and upper bound of
    124         * the support are included in the support.
    125         *
    126         * @return whether the support is connected or not
    127         */
    128        boolean isSupportConnected();
    129
    130        /**
    131         * Reseed the random generator used to generate samples.
    132         *
    133         * @param seed the new seed
    134         * @since 3.0
    135         */
    136        void reseedRandomGenerator(long seed);
    137
    138        /**
    139         * Generate a random value sampled from this distribution.
    140         *
    141         * @return a random value
    142         * @since 3.0
    143         */
    144        int sample();
    145
    146        /**
    147         * Generate a random sample from the distribution.
    148         *
    149         * @param sampleSize the number of random values to generate
    150         * @return an array representing the random sample
    151         * @throws org.apache.commons.math3.exception.NotStrictlyPositiveException
    152         * if {@code sampleSize} is not positive
    153         * @since 3.0
    154         */
    155        int[] sample(int sampleSize);
    156    }