help panels
-------------------------------------------------------------------------------

Title

    panels -- Count panels (groups) / apply command to panel units


Syntax


    Syntax 1: count panels

        panels varlist [if] [in] [weight] [, options ]


    Syntax 2: apply command to panel units

        panels varlist [if] [in] [weight] [, options prefix_options ] :
               command


    options             description
    --------------------------------------------------------
    generate(newvar)    store panel sizes in newvar
    fillin              fill in newvar for all observations
    id(newvar)          create a new panel ID variable
    replace             overwrite existing variables
    isconstant(varlist) verify that the specified variables
                          are constant within panels
    noisily             display panel info with syntax 2
    nowarn              suppress syntax 2 warning message
    --------------------------------------------------------

    fweights, aweights, iweights, and pweights are allowed; see help weight.


Description

    panels counts the panels defined by varlist and displays some basic
    information on panel sizes (syntax 1). A panel is a group of observations
    with identical values for the variables in varlist.

    If used as a prefix command (syntax 2), panels applies the specified
    command to the panel units defined by varlist. This is useful, for
    example, if you want to compute frequency distributions or summary
    statistics for panel characteristics. To be precise, panels picks one
    observation per panel and then applies the command to these observations.
    Variables referred to in command are assumed to be constant within
    panels. Use the isconstant() option to verify this assumption.

    command is required to follow standard Stata syntax and allow the if
    qualifier.


Options

    generate(newvar) stores in newvar the sizes of the panels (i.e. the
        number of observations per panel). The default is to use only one
        observation per panel to store this information (the remaining
        observation are set to missing). Specify the fillin option to store
        the panel sizes in all observations.

    fillin causes newvar stored by generate() to be filled in for all
        observations within the panels.

    id(newvar) stores in newvar unique identification numbers for the panels
        (using values 1, 2, ...).

    replace allows panels to overwrite existing variables.

    isconstant(varlist) verifies that the specified variables are constant
        within panels. check() is a synonym for isconstant(). Error is
        returned if any of the variables is not constant within panels.

    noisily can be used with syntax 2 to request that the information on the
        number of panels and the panel sizes be displayed. The default is to
        suppress this information in syntax 2.


Examples

    . webuse nlswork, clear
    (National Longitudinal Survey.  Young Women 14-26 years of age in 1968)
    
    . panels idcode
    
    Number of obs      =     28534
    Number of groups   =      4711
    
    Obs per group: min =         1
                   avg =  6.056888
                   max =        15
    
    . panels idcode if race==2
    
    Number of obs      =      8051
    Number of groups   =      1325
    
    Obs per group: min =         1
                   avg =  6.076226
                   max =        15
    
    . panels idcode: tabulate race
    
       1=white, |
       2=black, |
        3=other |      Freq.     Percent        Cum.
    ------------+-----------------------------------
              1 |      3,329       70.66       70.66
              2 |      1,325       28.13       98.79
              3 |         57        1.21      100.00
    ------------+-----------------------------------
          Total |      4,711      100.00
    
    (variables assumed constant within panels; use isconstant() to verify)
    
    . panels idcode: summarize birth_yr grade collgrad
    
        Variable |       Obs        Mean    Std. Dev.       Min        Max
    -------------+--------------------------------------------------------
        birth_yr |      4711    48.25387    3.051795         41         54
           grade |      4709    12.74347    2.566536          0         18
        collgrad |      4711    .2061134    .4045558          0          1
    
    (variables assumed constant within panels; use isconstant() to verify)
    
    . panels idcode, isconstant(age): summarize age
    23657 contradictions in 23823 observations
    assertion is false
    age not constant within panels
    r(9);
    

Returned results

    panels saves the following scalars:

        r(N)      Number of observations
        r(N_g)    Number of panels (groups)
        r(g_min)  Minimum panel size
        r(g_avg)  Average panel size
        r(g_max)  Maximum panel size

    If panels is used as a prefix command (syntax 2), the results may become
    overwritten by command.


Author

    Ben Jann, ETH Zurich, jannb@ethz.ch

    Thanks for citing this software as follows:

        Jann, B. (2009). panels: Stata module to count panels and apply a
        command to panel units. Available from 
        http://ideas.repec.org/c/boc/bocode/s457086.html.


Also see

    Cox, N. J. (2007). Speaking Stata: Counting groups, especially panels.
        The Stata Journal 7(4):571-581.