-------------------------------------------------------------------------------
help for shufflevar
-------------------------------------------------------------------------------

Randomly shuffle variables 

        shufflevar varlist[, Joint DROPold cluster(varname)]


Description 

    shufflevar takes varlist and either jointly or for each variable shuffles
    varlist relative to the rest of the dataset. This means any association
    between varlist and the rest of the dataset will be random.  Much like 
    bootstrap or the Quadratic Assignment Procedure (QAP), one can build a
    distribution of results out of randomness to serve as a baseline against
    which to compare empirical results, especially for overall model-fit or
    clustering measures.

Remarks 

    The program is intended for situations where it is hard to model error
    formally, either because the parameter is exotic or because the
    application violates the parameter's assumptions. For instance, the
    algorithm has been used by Fernandez et. al. and Zuckerman to interpret
    network data, the author wrote this implementation for use in
    interpreting st frailty models with widely varying cluster sizes, and
    others have suggested using the metric for adjacency matrices in spatial
    analysis.

    Much like bsample, the shufflevar command is only really useful when
    worked into a forvalues loop or program that records the results of each
    iteration using postfile. See the example code below to see how to
    construct the loop.

    To avoid confusion with the actual data, the shuffled variables are
    renamed varname_shuffled.

    This command is an implementation of an algorithm used in two papers that
    used it to measure network issues:

    Fernandez, Roberto M., Emilio J. Castilla, and Paul Moore. 2000. "Social
    Capital at Work: Networks and Employment at a Phone Center." American
    Journal of Sociology 105:1288-1356.

    Zuckerman, Ezra W. 2005. "Typecasting and Generalism in Firm and Market:
    Career-Based Career Concentration in the Feature Film Industry,
    1935-1995." Research in the Sociology of Organizations 23:173-216.

Options 
 
    joint specifies that varlist will be keep their actual relations to one
        another even as they are shuffled relative to the rest of the
        variables.  If joint is omitted, each variable in the varlist will be
        shuffled separately.

    dropold specifies that the original sort order versions of varlist will
        be dropped.

    cluster(varname) specifies that shuffling will occur by varname.

Examples

    . sysuse auto, clear
    . regress price weight
    . local obs_r2=`e(r2)'
    . tempname memhold
    . tempfile results
    . postfile `memhold' r2 using "`results'"
    . forvalues i=1/100 {
    .  shufflevar weight, cluster(foreign)
    .  quietly regress price weight_shuffled
    .  post `memhold' (`e(r2)')
    . }
    . postclose `memhold'
    . use "`results'", clear
    . sum r2
    . disp "The observed R^2 of " `obs_r2' " is "
        (`obs_r2'-`r(mean)')/`r(sd)' " sigmas out on the" _newline
        "distribution of shuffled R^2s."


Author

    Gabriel Rossman, UCLA
    rossman@soc.ucla.edu

Also see

    On-line:  help for bsample, help for forvalues, help for postfile, help
             for program, help for permute