discreteTableSetup

Sets up table to generate pseudorandom numbers from a general discrete distribution.

Synopsis

discreteTableSetup (prf, t_del, nndx, imin, nmass)

Required Arguments

float prf(int ix) (Input)
User-supplied function to compute the probability associated with each mass point of the distribution The argument to the function is the point at which the probability function is to be evaluated. ix can range from imin to the value at which the cumulative probability is greater than or equal to 1.0 - t_del.
float t_del (Input)
Maximum absolute error allowed in computing the cumulative probability. Probabilities smaller than t_del are ignored; hence, t_del should be a small positive number. If t_del is too small, however, the return value, cumpr [nmass-1] must be exactly 1.0 since that value is compared to 1.0 - t_del.
int nndx (Input)
The number of elements of cumpr available to be used as indexes. nndx must be greater than or equal to 1. In general, the larger nndx is, to within sixty or seventy percent of nmass, the more efficient the generation of random numbers using randomGeneralDiscrete will be.
int imin (Input/Output)

A scalar containing the smallest value the random deviate can assume. (Input/Output)

imin is not used if optional argument indexOnly is used. By default, prf is evaluated at imin. If this value is less than t_del, imin is incremented by 1 and again prf is evaluated at imin. This process is continued until prf(imin) ≥ t_del. imin is output as this value and the return value cumpr [0] is output as prf(imin).

int nmass (Input/Output)

A scalar containing the number of mass points in the distribution. Input, if indexOnly is used; otherwise, output.

By default, nmass is the smallest integer such that prf(imin + nmass - 1) > 1.0 - t_del. nmass does include the points \(\text{imin}_{in}+j\) for which prf(\(\text{imin}_{in}+j\)) < t_del, for \(j=0,1, \ldots,\text{imin}_{out}-\text{imin}_{in}\), where \(\text{imin}_{in}\) denotes the input value of imin and \(\text{imin}_{out}\) denotes its output value.

Return Value

Array, cumpr, of length nmass + nndx containing in the first nmass positions, the cumulative probabilities and in some of the remaining positions, indexes to speed access to the probabilities.

Optional Arguments

indexOnly (Input)
Fill only the index portion of the result, cumpr, using the values in the first nmass positions. prf is not used and may be a dummy function; also, imin is not used. The optional argument returnUser is required if indexOnly is used.
returnUser, float cumpr[], int lcumpr (Input/Output)
cumpr is a user-allocated array of length nmass + nndx containing in the first nmass positions, the cumulative probabilities and in some of the remaining positions, indexes to speed access to the probabilities. lcumpr is the actual length of cumpr as specified in the calling function. Since, by default, the logical length of cumpr is determined in discreteTableSetup, lcumpr is used for error checking. If the option indexOnly is used, then only the index portion of cumpr is filled.

Description

Function discreteTableSetup sets up a table that function randomGeneralDiscrete uses to generate pseudorandom deviates from a discrete distribution. The distribution can be specified either by its probability function prf or by a vector of values of the cumulative probability function. Note that prf is not the cumulative probability distribution function. If the cumulative probabilities are already available in cumpr, the only reason to call discreteTableSetup is to form an index vector in the upper portion of cumpr so as to speed up the generation of random deviates by the function randomGeneralDiscrete.

Examples

Example 1

In this example, discreteTableSetup is used to set up a table to generate pseudorandom variates from the discrete distribution:

\[Pr(X = 1) = .05\]
\[Pr(X = 2) = .45\]
\[Pr(X = 3) = .31\]
\[Pr(X = 4) = .04\]
\[Pr(X = 5) = .15\]

In this simple example, we input the cumulative probabilities directly in cumpr and request 3 indexes to be computed (nndx = 4). Since the number of mass points is so small, the indexes would not have much effect on the speed of the generation of the random variates.

from numpy import *
from pyimsl.stat.discreteTableSetup import discreteTableSetup
from pyimsl.stat.writeMatrix import writeMatrix


def prf(ix):
    return 0.0


lcumpr = 9
nndx = 4
imin = [1]
nmass = [5]
nr = 5
cumpr = array([.05, .5, .81, .85, 1.0, 0, 0, 0, 0])
delta = 0.00001
i = 0
discreteTableSetup(prf, delta, nndx, imin, nmass,
                   indexOnly=True, returnUser={'cumpr': cumpr, 'lcumpr': lcumpr})

writeMatrix("Cumulative probabilities and indexes", cumpr, writeFormat="%5.2f")

Output

1 5
 
            Cumulative probabilities and indexes
    1      2      3      4      5      6      7      8      9
 0.05   0.50   0.81   0.85   1.00   3.00   1.00   2.00   5.00

Example 2

This example, randomGeneralDiscrete is used to set up a table to generate binomial variates with parameters 20 and 0.5.

from __future__ import print_function
from numpy import *
from pyimsl.stat.discreteTableSetup import discreteTableSetup
from pyimsl.stat.binomialPdf import binomialPdf
from pyimsl.stat.writeMatrix import writeMatrix


def prf(ix):
    n = 20
    p = 0.5
    return binomialPdf(ix, n, p)


lcumpr = 33
nndx = 12
imin = [0]
nmass = [21]
nr = 5
delta = 0.00001
i = 0

cumpr = discreteTableSetup(prf, delta, nndx, imin, nmass)

print("The smallest point with positive probability using")
print("the given del is %3i and all points after" % imin[0])
print("point number %3i (counting from the input value" % nmass[0])
print("of IMIN) have zero probability.")
writeMatrix("Cumulative probabilities and indexes", cumpr,
            column=True, writeFormat="%11.7f")

Output

1 19
The smallest point with positive probability using
the given del is   1 and all points after
point number  19 (counting from the input value
of IMIN) have zero probability.
 
Cumulative probabilities and indexes
            1    0.0000191
            2    0.0002003
            3    0.0012875
            4    0.0059080
            5    0.0206938
            6    0.0576583
            7    0.1315873
            8    0.2517219
            9    0.4119013
           10    0.5880987
           11    0.7482781
           12    0.8684127
           13    0.9423417
           14    0.9793062
           15    0.9940920
           16    0.9987125
           17    0.9997997
           18    0.9999809
           19    1.0000000
           20   11.0000000
           21    1.0000000
           22    7.0000000
           23    8.0000000
           24    9.0000000
           25    9.0000000
           26   10.0000000
           27   11.0000000
           28   11.0000000
           29   12.0000000
           30   13.0000000
           31   19.0000000

Fatal Errors

IMSLS_STOP_USER_FCN

Request from user supplied function to stop algorithm.

User flag = “#”.