discrete_table_setup
Sets up table to generate pseudorandom numbers from a general discrete distribution.
Synopsis
#include <imsls.h>
float *imsls_f_discrete_table_setup (float prf(), float del, int nndx, int *imin, int *nmass, ..., 0)
The type double function is imsls_d_discrete_table_setup.
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 - del.
float del (Input)
Maximum absolute error allowed in computing the cumulative probability. Probabilities smaller than del are ignored; hence, del should be a small positive number. If del is too small, however, the return value, cumpr [nmass-1] must be exactly 1.0 since that value is compared to 1.0 - 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
imsls_f_random_general_discrete will be.
int *imin (Input/Output)
Pointer to a scalar containing the smallest value the random deviate can assume. (Input/Output)
imin is not used if optional argument IMSLS_INDEX_ONLY is used. By default, prf is evaluated at imin. If this value is less than del, imin is incremented by 1 and again prf is evaluated at imin. This process is continued until prf(imin) ≥ del. imin is output as this value and the return value cumpr [0] is output as prf(imin).
int *nmass (Input/Output)
Pointer to a scalar containing the number of mass points in the distribution. Input, if IMSLS_INDEX_ONLY is used; otherwise, output.
By default, nmass is the smallest integer such that prf(imin + nmass - 1) > 1.0 - del. nmass does include the points iminin + j for which prf(iminin + j) < del, for j = 0, 1, ..., iminout - iminin, where iminin denotes the input value of imin and iminout 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. To release this space, use imsls_free.
Synopsis with Optional Arguments
#include <imsls.h>
float *imsls_f_discrete_table_setup(float prf(), float del, int nndx, int *imin, int *nmass,
IMSLS_INDEX_ONLY,
IMSLS_RETURN_USER, float cumpr[], int lcumpr,
IMSLS_FCN_W_DATA, float prf(), void *data,
0)
Optional Arguments
IMSLS_INDEX_ONLY, (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 IMSLS_RETURN_USER is required if IMSLS_INDEX_ONLY is used.
IMSLS_RETURN_USER, 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 imsls_f_discrete_table_setup, lcumpr is used for error checking. If the option IMSLS_INDEX_ONLY is used, then only the index portion of cumpr is filled.
IMSLS_FCN_W_DATA,
float prf(int ix),
void *data (Input)
User-supplied function to compute the probability associated with each mass point of the distribution, which also accepts a pointer to data that is supplied by the user.
data is a pointer to the data to be passed to the user-supplied function. See the
Passing Data to User-Supplied Functions section at the beginning of this manual for more details.
Description
Function
imsls_f_discrete_table_setup sets up a table that function
imsls_f_random_general_discrete 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
imsls_f_discrete_table_setup 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
imsls_f_random_general_discrete.
Examples
Example 1
In this example, imsls_f_discrete_table_setup 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.
#include <imsls.h>
#include <stdlib.h>
float prf(int ix);
int main()
{
int i, lcumpr = 9, ir[5];
int nndx = 4, imin = 1, nmass = 5, nr = 5;
float cumpr[9], del = 0.00001, *p_cumpr = NULL;
i = 0;
cumpr[i++] = .05;
cumpr[i++] = .5;
cumpr[i++] = .81;
cumpr[i++] = .85;
cumpr[i++] = 1.0;
imsls_f_discrete_table_setup (prf, del, nndx, &imin, &nmass,
IMSLS_INDEX_ONLY,
IMSLS_RETURN_USER, cumpr, lcumpr,
0);
imsls_f_write_matrix("Cumulative probabilities and indexes",
1, lcumpr, cumpr,
0);
}
float prf(int ix)
{
return 0.;
}
Output
Cumulative probabilities and indexes
1 2 3 4 5 6
0.05 0.50 0.81 0.85 1.00 3.00
7 8 9
1.00 2.00 5.00
Example 2
This example,
imsls_f_random_general_discrete is used to set up a table to generate binomial variates with parameters 20 and 0.5. The function
imsls_f_binomial_pdf (Chapter 11,
Probability Distribution Functions and Inverses) is used to compute the probabilities.
#include <stdio.h>
#include <imsls.h>
float prf(int ix);
int main()
{
int lcumpr = 33;
int nndx = 12, imin = 0, nmass = 21, nr = 5;
float del = 0.00001, *cumpr;
int *ir = NULL;
cumpr = imsls_f_discrete_table_setup (prf, del, nndx, &imin, &nmass, 0);
printf("The smallest point with positive probability using \n");
printf("the given del is %d and all points after \n", imin);
printf("point number %d (counting from the input value\n", nmass);
printf("of IMIN) have zero probability.\n");
imsls_f_write_matrix("Cumulative probabilities and indexes",
nmass+nndx, 1, cumpr,
IMSLS_WRITE_FORMAT, "%11.7f", 0);
}
float prf(int ix)
{
int n = 20;
float p = .5;
return imsls_f_binomial_pdf(ix, n, p);
}
Output
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 = "#". |