    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     * Base interface for distributions on the reals.
    024     *
    025     * @version $Id: RealDistribution.java 1416643 2012-12-03 19:37:14Z tn $
    026     * @since 3.0
    027     */
    028    public interface RealDistribution {
    029        /**
    030         * For a random variable {@code X} whose values are distributed according
    031         * to this distribution, this method returns {@code P(X = x)}. In other
    032         * words, this method represents the probability mass function (PMF)
    033         * for the distribution.
    034         *
    035         * @param x the point at which the PMF is evaluated
    036         * @return the value of the probability mass function at point {@code x}
    037         */
    038        double probability(double x);
    039
    040        /**
    041         * Returns the probability density function (PDF) of this distribution
    042         * evaluated at the specified point {@code x}. In general, the PDF is
    043         * the derivative of the {@link #cumulativeProbability(double) CDF}.
    044         * If the derivative does not exist at {@code x}, then an appropriate
    045         * replacement should be returned, e.g. {@code Double.POSITIVE_INFINITY},
    046         * {@code Double.NaN}, or  the limit inferior or limit superior of the
    047         * difference quotient.
    048         *
    049         * @param x the point at which the PDF is evaluated
    050         * @return the value of the probability density function at point {@code x}
    051         */
    052        double density(double x);
    053
    054        /**
    055         * For a random variable {@code X} whose values are distributed according
    056         * to this distribution, this method returns {@code P(X <= x)}. In other
    057         * words, this method represents the (cumulative) distribution function
    058         * (CDF) for this distribution.
    059         *
    060         * @param x the point at which the CDF is evaluated
    061         * @return the probability that a random variable with this
    062         * distribution takes a value less than or equal to {@code x}
    063         */
    064        double cumulativeProbability(double x);
    065
    066        /**
    067         * For a random variable {@code X} whose values are distributed according
    068         * to this distribution, this method returns {@code P(x0 < X <= x1)}.
    069         *
    070         * @param x0 the exclusive lower bound
    071         * @param x1 the inclusive upper bound
    072         * @return the probability that a random variable with this distribution
    073         * takes a value between {@code x0} and {@code x1},
    074         * excluding the lower and including the upper endpoint
    075         * @throws NumberIsTooLargeException if {@code x0 > x1}
    076         *
    077         * @deprecated As of 3.1. In 4.0, this method will be renamed
    078         * {@code probability(double x0, double x1)}.
    079         */
    080        @Deprecated
    081        double cumulativeProbability(double x0, double x1) throws NumberIsTooLargeException;
    082
    083        /**
    084         * Computes the quantile function of this distribution. For a random
    085         * variable {@code X} distributed according to this distribution, the
    086         * returned value is
    087         * <ul>
    088         * <li><code>inf{x in R | P(X<=x) >= p}</code> for {@code 0 < p <= 1},</li>
    089         * <li><code>inf{x in R | P(X<=x) > 0}</code> for {@code p = 0}.</li>
    090         * </ul>
    091         *
    092         * @param p the cumulative probability
    093         * @return the smallest {@code p}-quantile of this distribution
    094         * (largest 0-quantile for {@code p = 0})
    095         * @throws OutOfRangeException if {@code p < 0} or {@code p > 1}
    096         */
    097        double inverseCumulativeProbability(double p) throws OutOfRangeException;
    098
    099        /**
    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        boolean isSupportLowerBoundInclusive();
    150
    151        /**
    152         * Whether or not the upper bound of support is in the domain of the density
    153         * function.  Returns true iff {@code getSupportUpperBound()} is finite and
    154         * {@code density(getSupportUpperBound())} returns a non-NaN, non-infinite
    155         * value.
    156         *
    157         * @return true if the upper bound of support is finite and the density
    158         * function returns a non-NaN, non-infinite value there
    159         * @deprecated to be removed in 4.0
    160         */
    161        boolean isSupportUpperBoundInclusive();
    162
    163        /**
    164         * Use this method to get information about whether the support is connected,
    165         * i.e. whether all values between the lower and upper bound of the support
    166         * are included in the support.
    167         *
    168         * @return whether the support is connected or not
    169         */
    170        boolean isSupportConnected();
    171
    172        /**
    173         * Reseed the random generator used to generate samples.
    174         *
    175         * @param seed the new seed
    176         */
    177        void reseedRandomGenerator(long seed);
    178
    179        /**
    180         * Generate a random value sampled from this distribution.
    181         *
    182         * @return a random value.
    183         */
    184        double sample();
    185
    186        /**
    187         * Generate a random sample from the distribution.
    188         *
    189         * @param sampleSize the number of random values to generate
    190         * @return an array representing the random sample
    191         * @throws org.apache.commons.math3.exception.NotStrictlyPositiveException
    192         * if {@code sampleSize} is not positive
    193         */
    194        double[] sample(int sampleSize);
    195    }