help mata mm_expand()
-------------------------------------------------------------------------------

Title

    mm_expand() -- Duplicate rows and columns


Syntax

        t. matrix mm_expand(X, real vector nr [, real vector nc, sort])

        void      _mm_expand(X, real vector nr, real vector nc, sort)


        t. matrix mm_repeat(X, real scalar nr [, real scalar nc])

        void      _mm_repeat(X, real scalar nr, real scalar nc)


    where X is a transmorphic matrix and sort is a real scalar.


Description

    mm_expand() duplicates rows and columns in X and returns the result as a
    new matrix. Vector nr specifies for each row the desired number of
    duplicates (with 1 indicating that no copies are added). nr may also be
    scalar, in which case nr duplicates are returned of each row. nc
    analogously specifies the column duplicates.

    The default for mm_expand() is to append additional copies of rows at the
    bottom of X and append additional copies of columns at the right.
    Alternatively, sort!=0 causes duplicates to be tied together and arranged
    in the original sort order of X.

    mm_repeat() returns a matrix composed of repetitions of X. nr specifies
    the desired number of repetitions of X in the direction of rows. nc
    specifies the desired number of repetitions of X in the direction of
    columns.

    _mm_expand() and _mm_repeat() expand X in place.

    With all of the above functions, values less than 1 or missing values are
    interpreted as if they were 1 in nr and nc. See help for select() if you
    want to delete rows or columns from a matrix.

    With the 25feb2008 update of Stata 10 a matrix version of the J()
    function has been introduced, which supersedes the mm_repeat() function.


Remarks

    Some examples:

        : X = (1,2)'
        
        : X
               1
            +-----+
          1 |  1  |
          2 |  2  |
            +-----+

        : mm_expand(X,(3,2))
               1
            +-----+
          1 |  1  |
          2 |  2  |
          3 |  1  |
          4 |  1  |
          5 |  2  |
            +-----+

        : mm_expand(X,(3,2),1,1)
               1
            +-----+
          1 |  1  |
          2 |  1  |
          3 |  1  |
          4 |  2  |
          5 |  2  |
            +-----+

        : mm_expand(X',2,(3,2))
               1   2   3   4   5
            +---------------------+
          1 |  1   2   1   1   2  |
          2 |  1   2   1   1   2  |
            +---------------------+

        : mm_expand(X',2,(3,2),1)
               1   2   3   4   5
            +---------------------+
          1 |  1   1   1   2   2  |
          2 |  1   1   1   2   2  |
            +---------------------+

        : S = ("a","b")\("c","d")
        
        : S
               1   2
            +---------+
          1 |  a   b  |
          2 |  c   d  |
            +---------+

        : mm_repeat(S,3,2)
               1   2   3   4
            +-----------------+
          1 |  a   b   a   b  |
          2 |  c   d   c   d  |
          3 |  a   b   a   b  |
          4 |  c   d   c   d  |
          5 |  a   b   a   b  |
          6 |  c   d   c   d  |
            +-----------------+

        : _mm_repeat(S,3,2)
        
        : S
               1   2   3   4
            +-----------------+
          1 |  a   b   a   b  |
          2 |  c   d   c   d  |
          3 |  a   b   a   b  |
          4 |  c   d   c   d  |
          5 |  a   b   a   b  |
          6 |  c   d   c   d  |
            +-----------------+


Diagnostics

    Non-integer values in nr and nc are truncated.


Source code

    mm_expand.mata


Author

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


Also see

    Online:  help for [M-5] select(), moremata