-------------------------------------------------------------------------------
help for mgen
-------------------------------------------------------------------------------

Apply generate to a matrix

        mgen exprlist , in(matname) out(matname) [ common(term) ]

    where exprlist is

        [[`]"]expr1["[']] [[`]"]expr2["[']] [[`]"]expr3["[']] ...

    and a single expr is

        [new|old]colname=exp

    (important notes: (1) expr must not contain spaces unless enclosed in
    quotes; (2) the exprs are processed one after another, i.e., expr2 can
    refer to the column created by expr1, but not the other way round; (3) be
    careful with replacing columns and then referring to the replaced column
    in a later expr)


Description

    mgen interprets the columns of a matrix as variables, generates new
    columns (or replaces old columns) according to a specified list of
    expressions, and then returns the generated (and the replaced) columns as
    a new matrix.

    Note: The column names of the input matrix and the specified new column
    names should conform to the naming conventions for variables.


Options

    in(matname) specifies the input matrix.

    out(matname) specifies the output matrix.

    common(term) specifies a common term which is added to the end of each of
        the expressions.


Examples

        . mat A=(1,2\3,4)
        . mat coln A=var1 var2
        . mat list A
        
        A[2,2]
            var1  var2
        r1     1     2
        r2     3     4
        

        . mgen var3=var1+var2 var4=var3^2, in(A) out(B)
        
        B[2,2]
            var3  var4
        r1     3     9
        r2     7    49
        

    Advanced application (note: tabstatmat is available from SSC):

        . tabstat e ft, by(year) s(mean) save not
        . tabstatmat A
        . mgen ne=(1-e) pt=e*(1-ft) ft=e*ft total=(ne+pt+ft)/100 , in(A)
            out(B) common(*100)

    Assume, "e" is labor force status (1 = in labor force, 0 = not in labor
    force) and "ft" is employment type (1 = fulltime, 0 = parttime, . =
    missing/not in labor force). The rows of matrix B will then contain the
    percentage distribution of nonemployed, partime employed and fulltime
    employed, e.g.:

        B[4,4]
                     ne         pt         ft      total
        1970  52.314139  5.8175698  41.868291        100
        1980  51.818218  6.9509233  41.230859        100
        1990  47.904043  9.7894623  42.306494        100
        2000  48.004791  13.477444  38.517765        100
        

Author

    Ben Jann, ETH Zurich, jann@soz.gess.ethz.ch


Also see

    Manual:  [U] 14.3 Naming conventions