-------------------------------------------------------------------------------
help for brrcorr
-------------------------------------------------------------------------------


Correlations of variables with BRR-based significance calculations


        brrcorr  [varlist] [weight] [if exp] [in range] [, pw obs sig print(#)
                 star(#) bonferroni sidak

                 brrweight(varlist) fay(#) dof(#) ]

by ... : may be used with the above commands; see by.

pweights are allowed; see weights.


Description

brrcorr displays the correlation matrix for varlist or, if varlist is not
specified, for all variables in the data.  Observations are excluded from the
calculation due to missing values on a casewise basis, unless the pw option is
specified.

Significance levels of the correlations are based on standard errors that are
calculated using a series of user-supplied replication weights, by the balanced
repeated replication (BRR) method.  This is an alternate method to the Taylor
series linearization methods used by Stata's svy-based commands.


Options

brrweight() specifies the list of variables that contain the replicate weights
    for the dataset.  The standard errors for the model are based on the
    variation in the estimates generated across the various weights.

    A set of brrweights is required for the analysis.  Once the brrweights are
    specified they are stored as a characteristic of the dataset and need not
    be respecified in subsequent command.

fay() specifies the k value that should be used for weighting the estimates,
    based on Fay's method.  The default is zero, meaning that simple averaging
    will be used.  As with the replicate weights, the value for fay() is stored
    as a characteristic of the dataset once it is specified, and need not be
    re-specified in subsequent commands.

dof() specifies the degrees of freedom for model fit and t-statistics.  The
    default is to use the number of replications.

pw specifies that observations are to be excluded from the calculations on a
    pairwise basis.  The default is casewise.

obs adds a line to each row of the matrix reporting the number of observations
    used in calculating the correlation coefficient.

sig adds a line to each row of the matrix reporting the significance level of
    each correlation coefficient.

print(#) specifies the significance level of correlation coefficients to be
    printed.  Coefficients with larger significance levels are left blank.
    print(10) or print(.1) would list only coefficients significant at the 10%
    level or better.

star(#) specifies the significance level of coefficients to be starred.
    star(5) or star(.05) would star all coefficients significant at the 5%
    level or better.

bonferroni makes the Bonferroni adjustment to calculated significance levels.
    This affects printed significance levels and the print() and star()
    options.  "pwcorr, print(.05) bonferroni" prints coefficients with
    Bonferroni-adjusted significance levels of .05 or less.

sidak makes the Sidak adjustment to calculated significance levels.  This
    affects printed significance levels and the print() and star() options.
    "pwcorr, print(.05) sidak" prints coefficients with Sidak-adjusted
    significance levels of .05 or less.


Examples

        . brrcorr dvcrate medage [pw=wgt], brrw(bw*)

        . brrcorr mrgrate dvcrate medage, pw obs sig



Methods and formulae

Point estimates are calculated using aweights.  Significance levels of the
estimated correlations are based on the variance matrix of each estimate,
calculated as follows:

                   G    
          V = c * SUM [ (r - r(i))^2 ]
                  i=1

where r is the estimated coefficient based on the full sample weights, r(i) is
the estimated coefficient using the i'th set of replicate weights, G is the
number of replicates, and c is a constant defined as:

         1 / G            for standard BRR (i.e. fay==0), or

         1 / (G*(1-k)^2)  for Fay's method.
         
For calculation of variances and significances, the correlations are first
transformed using Fisher's Z transformation, in order to normalize the
distribution.


Saved Results

brrcorr saves in r() the following for the last-calculated correlation:

        rho  the estimated correlation coefficient
        N    the number of observations
        p    the p-level


Acknowledgements

These commands consists largely of the ado file code from official Stata's
pwcorr command.  I would like to thank Bobby Gutierrez at StataCorp for advice
on implementation of BRR.


Author

        Nick Winter
        Cornell University
        nw53@cornell.edu