.-
help for ^stpiece^
.-

Estimation of piecewise-constant hazard rate models
---------------------------------------------------

^stpiece^ [varlist] [^if^ exp] [^in^ range], [^tp(^numlist^)^
^tv(^varlist^)^ 
      ^pre^split^(^#^)^ ^nopre^serve ^streg_options^]


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

^stpiece^ is a wrapper that uses a number of existing Stata routines to
estimate piecewise-constant hazard rate models.  A piecewise-constant
model is an exponential hazard rate model where the constant rate is
allowed to vary within pre-defined time-segments.  See the discussion
in, for example, Blossfeld and Rohwer (1995).  Estimation of this model
in Stata is usually a multi-step process, since one must manually define
the time pieces and if necessary split the spells.  ^stpiece^ automates
this process. 

^stpiece^ allows you to define the time intervals (time pieces) with the
^tp^ option and then splits the data for you using @stsplit@. In
addition, ^stpiece^ will allow you to specify, with the ^tv^ option,
variables whose effects you think may be non-proportional, i.e. they may
vary between time pieces. 

By default, ^stpiece^ will @preserve@ your data before creating the time
pieces.  This is typically convenient as it leaves your data "as is,"
thereby avoiding any problems that can arise when you split the spells
and then decide to change your outcome variable.  However, it does slow
the program down, since the data must be re-split before each model
estimation.  The ^nopreserve^ option will cause ^stpiece^ to change the
data.  You can then use the ^presplit^ option to avoid having to split
the data again. 

The data must be ^st^. In order to create time pieces, an id variable
must be declared with ^stset^. See @st@ and @stset@. 


Options
-------

^tp()^ allows you to define the time periods using a numlist.  The logic
is the same as for ^stsplit^.  See @stsplit@ for details. The time
pieces are listed in the output as tp#, where # indexes the time pieces
sequentially, starting at 1. 

^tv()^ allows you to specify variables whose effects vary between time
pieces.  These variables appear in the output as %stub%tp#, where %stub%
is the first four letters of the variable name, and # indexes times
pieces sequentially, starting at 1.  For example, specifying
^tv(^educat^)^ for a model with four time pieces would result in
variables labelled eductp1 - eductp4.  The user must be sensitive to the
possibility of variable name comflicts. 

^presplit(#)^ is useful if the data has already been split and the time
pieces have already been defined. # specifies how many time pieces
exist.  In this case, the variables identifying the time pieces must
follow the convention defined by the option ^tp^.  In other words, the
time period dummy variables must be of the form tp#, starting at tp1 and
increasing sequentially.   Note that it is possible to combine ^tv^ with
^presplit^.

^nopreserve^ tells ^stpiece^ that you are willing to let it change your
data.  There are two advantages: 1) speed (particularly in large data
sets); and 2) you retain the variables created by stpiece after it
finishes. 


Examples
--------

    .^stpiece sex race, tp(0,1,3,10) tv(educ)^
    .^stpiece sex race, tp(0(5)25) tv(educ)^
    .^stpiece sex race, tv(educ) pre(4)^


References
----------

Blossfeld, Hans-Peter, and Gotz Rohwer.  1995.  Techniques of Event
History Modeling.  Mahwah, NJ: Lawrence Erlbaum. 


Note
----

The parameter estimates generated by stpiece will not match exactly with
the results produced by Transition Data Analysis (TDA).  This is due to
a minor difference between TDA and ^stsplit^ in how they define time
pieces.  Specifically, TDA defines time pieces in the manner [t0,t1)
while ^stsplit^ defines time pieces in the manner (t0,t1].  The
estimates can be made to agree by subtracting a very small constant from
the finishing times when using ^stpiece^, but all that is achieved by
this is making the software packages agree. 


Author
------

    Jesper B. Sorensen
    University of Chicago
    Graduate School of Business
    email: jesper.sorensen@@gsb.uchicago.edu

