.-
help for ^tscollap^               (Statalist distribution  25 June 2000)
.-

Compact timeseries into dataset of means, sums, end-of-period values etc.
-------------------------------------------------------------------------

	^tscollap^ clist  ^,^ ^to(^freq^)^ [^gen^erate(^freqvar^)]

where freq denotes the lower frequency over which data are to be compacted,
and clist is either

	[^(^stat^)^] varlist [ [^(^stat^)^] ... ]
	[^(^stat^)^] target_var^=^varname [target_var^=^varname ...] [ [^(^stat^)^ ...]

or any combination of the varlist or target_var forms. stat is one of

	^mean^            mean over interval
	^sum^             sum over interval
	^gmean^           geometric mean over interval (for variable > 0)

	^first^           first observation of the interval
	^last^            last observation of the interval

If stat is not specified, ^mean^ is assumed.

^tscollap^ is for use with time-series data of monthly, quarterly, or half-yearly
frequency.  You must ^tsset^ your data before using ^tscollap^; see help @tsset@.
If the data are a panel of timeseries (i.e. if a ^panelvar^ has been specified
in ^tsset^) the specification of the panel identification variable will 
automatically be retained in the resulting dataset (it need not, and should not,
be specified in the ^varlist^).  Time-series operators may not be used. 

Description
-----------

^tscollap^ converts the timeseries data in memory into a dataset of means, sums,
or selected values taken from the specified interval. It is a variant of 
^collapse^, which automatically forms the groups over which statistics are to 
be calculated from an understanding of the calendar data. For instance, 
monthly data may be converted to quarterly, half-yearly, or annual (yearly) 
data by specifying to(q), to(h), or to(y), respectively. Data may be averaged 
over the interval (using either an arithmetic or geometric mean), or summed 
(as would be appropriate for income statement data). Either the first or the 
last observation of each interval may be selected (so that, e.g., end-of-
period values may be readily assembled). Since its syntax (and internal logic) 
is taken from ^collapse^, more than one statistic may be generated from a 
single variable (e.g. both average and end-of-period values may be specified 
by using different target_var names). ^tscollap^ embodies the June2000 
correction to ^collapse^.

All variables not specified in the target list are dropped (including the 
current tsset variable), and a new tsset variable is generated as freq_freq 
(as long as that variable does not already exist). The ^gen^erate option may 
be used to customize the new tsset variable. If a ^panelid^ variable is in
use by ^tsset^, it should not be listed; it will be automatically retained.

Options
-------

^to(^freq^)^ specifies the target frequency, which must be specified. It may
take on any value lower than the current value as understood by tsset. ^freq^
must be given as ^q^, ^h^, ^y^, in either lower- or upper-case. 

^gen^erate(^freqvar^) may be used to specify the name of the new ^tsset^ 
variable, which will be formatted at the target frequency.

Examples
--------

 . ^tscollap rs r20, to(q)^

 . ^tscollap rs (first) rsf=rs (last) rsl=rs, to(q)^

 . ^tscollap dgnp (gmean) gnpdot=dgnp, to(y) gen(year)^

Note
----

^tscollap^ makes use of ^_gfilter^, part of Nicholas J. Cox' package ^egenmore^.
My thanks (without implicating) Nick Cox for guidance in improving ^tscollap^.

Author
------

        Christopher F Baum, Boston College, USA
        baum@@bc.edu
        
        
Also see
--------

  Manual:  ^[R] collapse^
 On-line:  help for @collapse@, @egenmore@