.-
help for ^stlexis^                                           (STB-40: ssa10)
.-

Expansion of st data by time bands
----------------------------------

  ^stlexis^ [varlist], ^br^eaks^(^x1, x2,...,xk^)^ [^or^igin^(^varname | value^)^
          ^sc^ale^(^varname | value^)^ ^gen^erate^(^[type] varname^)^ ^l^abel ^i^nvert]


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

^stlexis^ expands a set of records concerning ^st^ data for subjects 
in a follow-up study into a larger number of person-time records.  
Each record in the new dataset concerns the follow-up of one subject 
through one band of a time scale. Expansion by several time scales may be 
achieved by repeated calls to ^stlexis^.

The ^breaks^ option is mandatory and specifies the cut-points on the time 
scale. Whenever follow-up extends over a cut-point, a new record is added.
A new variable is added to the data set indicating which time bands the new
records refer to. This variable can be defined in the ^generate^ option but, 
if it is not defined, the default variable ^t_band^ is used. Note that 
it is mandatory for the ^id^ variable to have been defined in the initial 
specification of the ^st^ data, since only by so doing can the new records be
related back to the subject to whom they refer.

The time scale used to expand the records need not be the same as that on 
which the original ^st^ data were defined, since its origin and units can be 
set using the ^origin^ and ^scale^ options. For example, if the entry and exit
times from the study are coded as dates (i.e.days from some arbitrary date)
then records can be divided up by years of age by specifying date of birth 
as the ^origin^ and 365.25 as the ^scale^. For advanced users, ^scale^ can 
be a variable, allowing different units for different individuals. This 
is useful for computations based on cumulative dose of environmental exposure.

If present, the ^varlist^ specifies which variables (in addition to the st
data) should be maintained in the expanded dataset. If absent, all variables 
are kept. The ^st^ data definition remains in force after the expansion and 
the component variables are correctly recoded.
 
The program may be called repetitively thus partitioning observation between
cells in a lexis diagram. This explains the name of the program.


Options
-------

^origin()^ specifies the variable which holds the origin of the analysis
time scale. For example, if times are coded in the ^st^ data as dates and 
we wish to analyse on age, this variable should contain date of birth.

^scale()^ specifies the units for the analysis time scale in terms of the 
original time units. For example, if times in the ^st^ data are defined in days
and we wish to analyse by years, this option should specify 365.25. For 
advanced use, the option can specify a variable.

^breaks()^ is not optional. It supplies the breaks for the 
bands, in ascending order. The list of break points, ..., may be simply
a list of numbers separated by commas, but may also include the syntax
a[b]c, meaning from a to c in steps of size b. Thus,
	40, 45, 50, 55, 60, 70, 80, 90
	40[5]60, 70[10]90
	40[5]60[10]90
are all valid and describe the same list.

^generate()^ supplies the name of a new variable to hold the time band 
indicators. This variable will be coded using the left-hand ends of the 
bands defined by ^breaks^.

^label^ controls the coding and labeling of the generated time
band variable. By default the variable is coded to the lower break
point for the time band and is unlabeled. If ^label^ is set,
bands are coded 0, 1, 2 ... , and appropriate labels are computed.

^invert^ reverses the roles of the basic and analysis scales in
defining the mapping by origin and scale. 


Example
-------
 
 . ^stset date_ex fail, t0(date_in) id(subject)^ 
 . ^gen enter = date_in ^            
 . ^stlexis , origin(dob) scale(365.25) br(40,50,60,70) gen(ageband)^
 . ^stlexis , origin(enter) scale(365.25) br(0,5,10,20) gen(fuband)^

The above example expands ^st^ data, coded as dates of entry to and exit from
a follow-up study, by age band and by time in follow-up. The origin for 
age is date of birth (dob) and the origin for time in follow-up is the 
date of entry to the study. Note however that it was necessary to take a 
copy of this variable, as it forms part of the ^st^ data; after the first 
expansion date_in and date_ex have been recoded to refer to the start and 
finish dates of each segment of follow-up rather than to the follow-up period 
as a whole. 


Authors
-------

      David Clayton
      MRC Biostatistical Research Unit
      Cambridge
      email: david.clayton@@mrc-bsu.cam.ac.uk

      Michael Hills
      London School of Hygiene and Tropical Medicine (retired)
      email: mhills@@regress.demon.co.uk


Also see
--------

    STB:  STB-40 ssa10
On-line:  help for @st@, @strate@, @stmh@, @stmc@, @staalen@