{smcl}
{* 21apr2004/18oct2005}{...}
{hline}
help for {hi:mvcorr}
{hline}

{title:Generate moving-window correlations in time series or panel}

{p 8 17 2}{cmd:mvcorr}
{it:tsvar1 tsvar2}
[{cmd:if} {it:exp}]
[{cmd:in} {it:range}]
{cmd:,} {cmdab:g:enerate(}{it:newvar}{cmd:)}
{cmdab:w:indow(}{it:#}{cmd:)}
[
{cmd:end}
{cmd:force}
]

{p 4 4 2}
{cmd:mvcorr} is for use with time-series data.  You must {cmd:tsset} your
data before using {cmd:mvcorr}; see help {help tsset}.

{p 4 4 2}
{it:varname} may contain time-series operators; see help {help varlist}.


{title:Description}

{p 4 4 2}{cmd:mvcorr} computes a moving-window correlation coefficient for
{it:tsvar1} and {it:tsvar2} which must be time series variables under the aegis 
of
{cmd:tsset}.  If a panel calendar is in effect, the coefficient is calculated
for each time series within the panel.  The correlation coefficient is placed
in a new variable, specified with the {cmd:generate()} option.  Although
{cmd:mvcorr} works with unbalanced panels (where the start and/or end points
differ across units), {cmd:mvcorr} does not allow gaps within the observations
of a time series; that is, the value of an observation for a given period may
be missing, but the observation itself must be defined. Gaps in time series may
be dealt with via the {cmd:tsfill} command.

{p 4 4 2} 
By using time-series operators, {cmd:mvcorr} may also be used to generate moving
autocorrelations.


{title:Options}
    
{p 4 8 2}{cmd:generate(}{it:newvar}{cmd:)} specifies the name of a new variable
in which the results are to be placed.
This is a required option. 
 
{p 4 8 2}{cmd:window(}{it:#}{cmd:)} specifies the width of the window for
computation of the statistics, which must be an integer and at least 3. By
default, results for odd-length windows are placed in the middle of the window
and results for even-length windows are placed at the end of the window. The
first default can be over-ridden by the {cmd:end} option. This is a required option.

{p 4 8 2}{cmd:end} forces results to be placed at the end of the window in 
the case where the window width is an odd number.

{p 4 8 2}{cmd:force} forces results to be computed when some of a particular 
window's values are missing.


{title:Remarks} 

{p 4 4 2}Occasionally people want to use {cmd:if} 
and/or {cmd:in} when calculating moving correlations, but 
that raises a complication not usually encountered. 
What would you expect from a moving correlation calculated with 
either kind of restriction? Let us identify two possibilities: 

{p 8 8 2}Weak interpretation: I don't want to see any results for 
the excluded observations. 

{p 8 8 2}Strong interpretation: I don't even want you to use the 
values for the excluded observations. 

{p 4 4 2}Here is a concrete example. Suppose as a consequence of 
some restriction, observations 1-42 are included, but not 
observations 43 on. But the moving correlation for 42 will depend, 
among other things, on the value for observation 43 if the summary
extends backwards and forwards and is of length at least 3, 
and it will similarly depend on some of the observations 44 
onwards in some circumstances. 

{p 4 4 2}Our guess is that most people would go for the weak 
interpretation, which is employed in {cmd:mvcorr}. If not, 
you should ignore what you don't want or even set unwanted values 
to missing afterwards by using {cmd:replace}. 


{title:Examples}

{p 4 8 2}{stata "webuse grunfeld" :. webuse grunfeld}{p_end}
 
{p 4 8 2}{stata "mvcorr invest mvalue, win(5) gen(rho)" :. mvcorr invest mvalue, win(5) gen(rho)}{p_end}

{p 4 8 2}{stata "mvcorr invest L.invest, win(5) gen(acf) end" :. mvcorr invest L.invest, win(5) gen(acf) end}{p_end}


{title:Authors}

{p 4 4 2}Christopher F Baum, Boston College, USA{break}
baum@bc.edu
    
{p 4 4 2}Nicholas J. Cox, Durham University, U.K.{break}
n.j.cox@durham.ac.uk


{title:Acknowledgements}     

{p 4 4 2}This routine is based on Cox's {cmd:movsumm} and the authors'
{cmd:mvsumm} and {cmd:statsmat}. Its development was encouraged by a query from
Nathalie Carcenac.
 

{title:Also see}

{p 4 13 2}On-line: {help correlate}, {help tsset}, {help tsfill}