help mata mm_panels()
-------------------------------------------------------------------------------

Title

    mm_panels() -- Identify panel sizes and sub-panels


Syntax

        void           mm_panels(X, Xinfo [, Y, Yinfo])

        real colvector _mm_panels(X)

        real scalar    mm_npanels(X)


    where

            X:  transmorphic vector containing (upper level) panel ID
                variable (e.g. strata)

        Xinfo:  will be replaced by a real colvector containing panel sizes
                or, if Y is present, a k x 2 real matrix containing upper
                level panel sizes and numbers of lower level panels within
                upper level panels

            Y:  transmorphic vector containing lower level panel ID variable
                (e.g. clusters within strata)

        Yinfo:  will be replaced by a real colvector containing lower level
                panel sizes



Description

    mm_panels(X, Xinfo) stores in colvector Xinfo the sizes of the panels in
    X. A panel is defined as a consecutive series of identical values.  Note
    that mm_panels() does not sort the data. A new panel simply begins each
    time X changes from one row to the next. Identical values that are
    separated by rows containing other values do not belong to the same
    panel. The "size" of a panel is the number of rows it contains.

    mm_panels(X, Xinfo, Y, Yinfo) stores in the first column of matrix Xinfo
    the sizes of the X-panels (e.g. strata). In the second column of matrix
    Xinfo, the number of Y-panels (e.g. clusters) within each X-panel is
    stored. Furthermore, the Y-panel sizes within X-panels are stored in
    colvector Yinfo.

    _mm_panels(X) is a subroutine used by mm_panels(). It returns the panel
    sizes in X. Essentially,

        : Xinfo = _mm_panels(X)

    is equivalent to

        : mm_panels(X, Xinfo=.)


Remarks

    For example, consider the following data

        : X,Y
                1   2
             +---------+
           1 |  1   1  |
           2 |  1   2  |
           3 |  1   2  |
           4 |  2   1  |
           5 |  2   2  |
           6 |  2   2  |
           7 |  2   2  |
           8 |  3   1  |
           9 |  4   1  |
          10 |  4   1  |
             +---------+

    Typing

        : mm_panels(X, Xinfo=.)
        
        : Xinfo
               1
            +-----+
          1 |  3  |
          2 |  4  |
          3 |  1  |
          4 |  2  |
            +-----+

    informs us that there are four panels in X. The first panel contains
    three observations, the second panel contains four observations, etc.

    Furthermore,

        : mm_panels(X, Xinfo=., Y, Yinfo=.)
        
        : Xinfo
               1   2
            +---------+
          1 |  3   2  |
          2 |  4   2  |
          3 |  1   1  |
          4 |  2   1  |
            +---------+

    indicates that in the first and second panel there are two sub-panels
    each and in the third and fourth panel there is one sub-panel each.

    Finally,

        : Yinfo
               1
            +-----+
          1 |  1  |
          2 |  2  |
          3 |  1  |
          4 |  3  |
          5 |  1  |
          6 |  2  |
            +-----+

    displays the sizes of the sub-panels.

    See help for mm_sample() for an application of mm_panels() in the context
    of stratified and clustered sampling.


Conformability

    mm_panels(X, Xinfo)
      input:
                  X:  n x 1 or 1 x n
      output:
              Xinfo:  k x 1, where k is the number of panels in X, k<=n

    mm_panels(X, Xinfo, Y, Yinfo)
      input:
                  X:  n x 1 or 1 x n
                  Y:  n x 1 or 1 x n
      output:
              Xinfo:  k x 2, where k is the number of panels in X, k<=n
              Yinfo:  l x 1, where l is the number of sub-panels in Y, l<=n

    _mm_panels(X)
                  X:  n x 1 or 1 x n
             result:  k x 1, where k is the number of panels in X

    mm_panels(X)
                  X:  n x 1 or 1 x n
             result:  1 x 1


Diagnostics

    If Y is missing (i.e. Y==.) or void (i.e. length(Y)==0), mm_panels() does
    not replace Yinfo. If both X and Y are missing or void, mm_panels() does
    not replace Xinfo.

    If X is missing or void and Y is not missing and not void, all
    observations are interpreted as belonging to the same stratum.

    If X is not missing and not void and Y is missing or void, each
    observation is interpreted as belonging to it's individual cluster.


Source code

    mm_panels.mata


Author

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


Also see

    Online:  help for mm_sample(), [M-5] panelsetup(), [M-4] utility, 
             moremata