LIMMOMENT Function

Computes the limited moment of any distribution for which you have defined a cumulative distribution function (CDF).

Category:	Special Purpose Functions
Notes:	LIMMOMENT is a special purpose function that is automatically provided by the FCMP procedure for your convenience. If you specify order k and upper limit u, then the LIMMOMENT function computes the limited moment as E[min(X,u)^k], where E denotes an expectation taken over the distribution of a random variable X that is defined by the specified CDF function.

Syntax

Details

Example

Syntax

imom=LIMMOMENT('CDF-function-name', options-array, order, limit,

parameter-1, parameter-2, parameter-n);

Required Arguments

imom: specifies the limited moment that is returned from the LIMMOMENT function.

'CDF-function-name'

specifies the name of the CDF function. Enclose CDF-function-name in quotation marks.

Requirement:CDF-function-name must be a function defined using the FCMP procedure. It must have a signature as follows:

function <CDF-function-name> (x, parameter-1, parameter-2, …, parameter-n);

endsub;

Note:It is recommended that the CDF be a continuous function. For discrete CDF, the LIMMOMENT function might not be able to compute the limited moment.

options-array

specifies an array of options to use with the LIMMOMENT function. Options-array is used to control and monitor the process of numerical integration employed to compute the limited amount. Options-array can be a missing value (.), or it can have up to four of the following elements in the following order:

desired-accuracy: specifies the desired accuracy of the numerical integration. You can specify any value in the range (0,0.1). If you specify a smaller value, the result is a more accurate estimate of the moment, but it takes longer to compute the desired-accuracy. The default for desired-accuracy is 1.0e-8.

initial-step-size: specifies the step size that is used initially by the numerical integration process. An increase in the value results in a linear decrease in the number of times the integrand is evaluated. Typically, using the default value of 1 produces good results. The default for initial-step-size is 1.

maximum-iterations: specifies the maximum number of iterations that are used to refine the integration result in order to achieve the desired accuracy. An increase in this value results in an exponential increase in the number of times the integrand is evaluated. The default value for maximum-iterations is 8.

return-code

specifies the return status. If options-array is of dimension 4 or more, then the fourth element contains the return status. Return-code can have one of the following values:

<=0: indicates success. If negative, then the absolute value is the number of times the integrand function was evaluated in order to compute the limited moment. A larger absolute value indicates longer convergence time.

1: indicates that the limited moment could not be computed.

order: specifies the order of the desired limited moment. This value must be in the range [1,10].

limit: specifies the upper limit that is used to compute the desired limited moment. This value must be greater than 0.

parameters: specifies the parameters of the distribution at which the limited moment is desired. You must specify exactly the same number of parameters as required by the specified CDF function, and they should appear exactly in the same order as required by the specified CDF function..

Details

Let a random variable X have a probability distribution with probability density function f(x;θ) and cumulative distribution function F(x;θ), where θ denotes the parameters of the distribution. For a specified upper limit u, the k^th–order limited moment of this distribution is defined as follows:

The LIMMOMENT function uses the following alternate expression:

Because the expression needs only F(x), you need to specify only the CDF function for the distribution. Limited moments are often used in insurance applications to compute the maximum amount expected to be paid if the policy limit is set at a certain value.

You can control the numerical integration process with various options. The following is an example of an options array:

array opts[4] epsilon initial maxiter (1.0e-5 1 6);

where

epsilon(desired-accuracy)=1.0e-5

initial(initial-step)=1

maxiter(maximum-iterations)=6

You can examine the return status of the function by checking opts[4].

Example: Computing a Limited Moment for a Lognormal Distribution

This example demonstrates how you can compute the limited moment for any parametric distribution in a DATA step using the LIMMOMENT function. The example uses the lognormal distribution for illustration, but it can be extended to any distribution for which you can programmatically define a CDF function. The following statements define an FCMP function LOGN_LIMMOMENT that uses the LIMMOMENT function and the CDF function to compute limited moments from the lognormal distribution:

proc fcmp library=work.mycdf outlib=work.mylimmom.functions;
        function logn_limmoment(order, limit, mu, sigma, rc);
            outargs rc;
            array opts[4] / nosym (1.0e-8 . . .);
	
            m = limmoment("logn_cdf", opts, order, limit, mu, sigma);
            rc = opts[4]; /* return code */

            return (m);
        endsub;
    quit;

The preceding code assumes that you have stored the definition of the LOGN_CDF function in an FCMP library called Work.Mycdf using a PROC FCMP step as follows:

proc fcmp outlib=work.mycdf.functions;
        function logn_cdf(x, Mu, Sigma);
            if (x >= constant('MACEPS')) then do;
                z = (log(x) - Mu)/Sigma;
                return (CDF('NORMAL', z));
            end;
            return (0);
        endsub;
    quit;

You can now invoke the LOGN_LIMMOMENT function from a DATA step as shown below. Note that the location of the LOGN_CDF and the LOGN_LIMMOMENT functions must be specified with an appropriate value for the CMPLIB= option before you execute the DATA step:

options cmplib=(work.mycdf work.mylimmom);

    data _null_;
        do order=1 to 3;
            rcode = .;
            m = logn_limmoment(order, 100, 5, 0.5, rcode);
            if (rcode > 0) then
                put "ERROR: Limited moment could not be computed.";
            else
                put 'Moment of order ' order ' with limit 100 = ' m;
        end;
    run;