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.math.distribution;
018
019 /**
020 * Interface for discrete distributions of integer-valued random variables.
021 *
022 * @version $Id: IntegerDistribution.java 1178295 2011-10-03 04:36:27Z psteitz $
023 */
024 public interface IntegerDistribution extends DiscreteDistribution {
025 /**
026 * For a random variable {@code X} whose values are distributed according
027 * to this distribution, this method returns {@code P(X = x)}. In other
028 * words, this method represents the probability mass function for the
029 * distribution.
030 *
031 * @param x Value at which the probability density function is evaluated.
032 * @return the value of the probability density function at {@code x}.
033 */
034 double probability(int x);
035
036 /**
037 * For a random variable {@code X} whose values are distributed according
038 * to this distribution, this method returns {@code P(X <= x)}. In other
039 * words, this method represents the probability distribution function, or
040 * PDF for the distribution.
041 *
042 * @param x Value at which the PDF is evaluated.
043 * @return PDF for this distribution.
044 */
045 double cumulativeProbability(int x);
046
047 /**
048 * For this distribution, {@code X}, this method returns
049 * {@code P(x0 <= X <= x1)}.
050 *
051 * @param x0 the inclusive, lower bound
052 * @param x1 the inclusive, upper bound
053 * @return the cumulative probability.
054 * @throws IllegalArgumentException if {@code x0 > x1}.
055 */
056 double cumulativeProbability(int x0, int x1);
057
058 /**
059 * For this distribution, {@code X}, this method returns the largest
060 * {@code x} such that {@code P(X <= x) <= p}.
061 * <br/>
062 * Note that this definition implies:
063 * <ul>
064 * <li> If there is a minimum value, {@code m}, with positive
065 * probability under (the density of) {@code X}, then {@code m - 1} is
066 * returned by {@code inverseCumulativeProbability(0).} If there is
067 * no such value {@code m}, {@code Integer.MIN_VALUE} is returned.
068 * </li>
069 * <li> If there is a maximum value, {@code M}, such that
070 * {@code P(X <= M) = 1}, then {@code M} is returned by
071 * {@code inverseCumulativeProbability(1)}.
072 * If there is no such value, {@code M}, {@code Integer.MAX_VALUE} is
073 * returned.
074 * </li>
075 * </ul>
076 *
077 * @param p Cumulative probability.
078 * @return the largest {@code x} such that {@code P(X < x) <= p}.
079 * @throws IllegalArgumentException if {@code p} is not between 0 and 1
080 * (inclusive).
081 */
082 int inverseCumulativeProbability(double p);
083
084 /**
085 * Reseed the random generator used to generate samples.
086 *
087 * @param seed New seed.
088 * @since 3.0
089 */
090 void reseedRandomGenerator(long seed);
091
092 /**
093 * Generate a random value sampled from this distribution.
094 *
095 * @return a random value.
096 * @since 3.0
097 */
098 int sample();
099
100 /**
101 * Generate a random sample from the distribution.
102 *
103 * @param sampleSize number of random values to generate.
104 * @return an array representing the random sample.
105 * @throws org.apache.commons.math.exception.NotStrictlyPositiveException
106 * if {@code sampleSize} is not positive.
107 * @since 3.0
108 */
109 int[] sample(int sampleSize);
110 }