{smcl}
{* 15jan2005}{...}
{hline}
help for {hi:onespell}
{hline}

{title:Generate single longest spell for each unit in panel data, listwise}

{p 8 17}{cmd:onespell}
{it:varlist}
[{cmd:if} {it:exp}]
[{cmd:in} {it:range}] 
, {cmd:saving(}{it:name}{cmd:)}
[
{cmd:replace}
]

{p 4 4}{cmd:onespell} is for use with panel data. You must {cmd:tsset} your data before using {cmd:onespell}; see help {cmd:tsset}.

{title:Description}

{p 4 4}{cmd:onespell} produces a subset of a panel data set in which all observations 
on {cmd:varlist} are non-missing and contiguous in the time dimension. If a panel unit 
contains more than one such subset, the longest "spell" is retained. 

{p 4 4}For instance, if a panel contains up to 20 years of data per firm, and firm {it:i} contains 
non-missing values for all variables of interest for years 1-10 and 12-20, the first subset 
will be retained as that firm's single "spell" and years 12-20 will be discarded. 

{p 4 4}If there are two or more spells of equal length, the latest spell will be retained. If 
firm {it:i} has non-missing values for all variables of interest for years 1-6, 8-13, 15-20, 
the spell for years 15-20 will be retained.

{p 4 4}Although performing this operation for a single variable of interest is fairly straightforward, 
this routine deals with a more challenging task: generating the single longest spell in a listwise 
fashion, across a set of variables. This applies the same logic as does, e.g., {cmd:regress}: an 
observation with a missing value in any variable will be deleted from the regression sample. 
Some matrix software (e.g., DPD for Ox) requires that panel data be organized in this fashion, 
with each unit appearing as a single contiguous block of non-missing observations. {cmd:onespell} 
will produce such a dataset, which after conversion to Stata version 6 format 
(by, e.g., Stat/Transfer) may be read directly by Ox. The routine has been tested with the latest 
version of Ox (3.40) and the DPD package (1.21).

{title:Options}


{p 4 8}{cmd:saving(}{it:name}{cmd:)} (a required option) causes the pruned dataset to be 
saved as {it:name}.dta. If that dataset already exists, the {cmd:replace} option must be used.

{title:Examples}

{p 4 8}{stata webuse grunfeld, clear :. webuse grunfeld, clear}{p_end}

{p 4 8}{stata replace invest = . in 28 :. replace invest = . in 28}{p_end}
{p 4 8}{stata replace mvalue = . in 55 :. replace mvalue = . in 55}{p_end}
{p 4 8}{stata replace kstock = . in 87 :. replace kstock = . in 87}{p_end}
{p 4 8}{stata replace kstock = . in 94 :. replace kstock = . in 94}{p_end}

{p 4 8}{stata onespell invest mvalue kstock, saving(grun1) :. onespell invest mvalue kstock, saving(grun1) }{p_end}


{title:Author}

{p 4 4}Christopher F. Baum, Boston College, USA{break} 
       baum@bc.edu

{title:Acknowledgements}

{p 4 4} Most of the computations in this routine are generated by N.J. Cox's {cmd:tsspell} routine. Thanks to David Roodman for assistance with the issues of moving data between his {cmd:xtabond2} routine and DPD for Ox. 

{title:Also see}

{p 4 13}On-line: {help tsspell}