help mata rpnfcn()
-------------------------------------------------------------------------------

Title

    rpnfcn() -- A generic function evaluator based on Reverse Polish Notation
    (RPN)


Syntax

        numeric matrix rpnfcn(pointer matrix A)


Description

    mf_rpnfcn(A) returns the result of sequentially evaluating the commands
    given in the rows of matrix A.

    The fundamental commands allowed in A falls in the following categories

        Stack manipulation         Commands that enters matrices into the
                                   stack, copies and interchange stack
                                   elements.

        Binary operators           The four basic arithmetic operations of
                                   addition, subtraction, multiplication, and
                                   division.

        Single element functions   Distribution functions which are executed
                                   on the current top element of the stack
                                   and replace it with the result.

        Numerical integration      Functions used for numerical integration
                                   based on Monte Carlo with stratified,
                                   antithetic sampling.



Remarks

    Each row of A should consist of two elements, first a pointer to a
    function, and second either a pointer to an appropriate argument matrix
    or a null pointer. Upon completion of evaluation of all rows in A, only
    one matrix should be present in the internal stack set up by rpnfcn(),
    which is then returned as the result of the evaluation.

    Note, that it is the users responsibility that matrices are conformable,
    as most procedures internally use the Mata colon operators, see Mata
    colon operators. The lack of check on matrix dimensions is considered a
    feature, as it for example allows specifying a (1 x 2) matrix as
    parameter vector for a function which then uses this pair of parameter
    values for evaluating all elements of a (n x m) matrix in the stack.
    Equally well, a (n x 2) parameter matrix can be supplied to the same
    function, now with the implication that the pair of values in each row of
    the parameter matrix is applied to all elements of the corresponding row
    in the (n x m) matrix in the stack.


Example

    Consider the density for the minimum of two Weibull distributed random
    variables at x with the two parameter vectors theta1 and theta2. The
    following code defines and evaluates the algorithm matrix corresponding
    to this.


. mata
------------------------------------------------- mata (type end to exit) -----
: x = (NULL)

: theta1 = (NULL)

: theta2 = (NULL)

: fweimin = (&tostack(),  &x \
>            &enter(),    NULL \
>            &enter(),    NULL \
>            &fwei(),     &theta1 \
>            &swapst(),   NULL \
>            &Swei(),     &theta2 \
>            &product(),  NULL \
>            &rotst(),    NULL \
>            &enter(),    NULL \
>            &Swei(),     &theta1 \
>            &swapst(),   NULL \
>            &fwei(),     &theta2 \
>            &product(),  NULL \
>            &add(),      NULL
>            )

: x = (0, 2, 8 \
>      .7, 1, 6)

: theta1 = (-2, 2)

: theta2 = (0, .3)

: rpnfcn(fweimin)
                 1             2             3
    +-------------------------------------------+
  1 |            0   .1344860648   4.74373e-08  |
  2 |  .6423218484   .4965861523   .0000298698  |
    +-------------------------------------------+

: end
-------------------------------------------------------------------------------


Source code

    rpnfcn.mata

Author

    Henrik Støvring, Research Unit of General Practice, University of
    Southern Denmark.  Please email hstovring@health.sdu.dk if you have
    comments, questions or observe any problems.


Also see

    Manual:  [M] Mata Reference Manual

    Online:  help for [M-0] mata, RPN stack manipulation functions, RPN
             binary operators, RPN distribution functions, RPN functions for
             integration