**[ST] stptime** -- Calculate person-time, incidence rates, and SMR

__Syntax__

**stptime** [*if*] [**,** *options*]

*options* Description
-------------------------------------------------------------------------
Main
**at(***numlist***)** compute person-time at specified
intervals; default is to compute overall
person-time and incidence rates
**trim** exclude observations <= minimum or >
maximum of **at()**
**by(***varname***)** compute incidence rates or SMRs by *varname*

Options
**per(***#***)** units to be used in reported rates
**dd(***#***)** number of decimal digits to be displayed
**smr(***groupvar ratevar***)** use *groupvar* and *ratevar* in **using()**
dataset to calculate SMRs
__u__**sing(***filename***)** specify filename to merge that contains
**smr()** variables
__l__**evel(***#***)** set confidence level; default is **level(95)**
__nosh__**ow** do not show st setting information

Advanced
__j__**ackknife** jackknife confidence intervals
__t__**itle(***string***)** label output table with *string*
__out__**put(***filename* [**,replace**]**)** save summary dataset as *filename*; use
**replace** to overwrite existing *filename*
-------------------------------------------------------------------------
You must **stset** your data before using **stptime**; see **[ST] stset**.
**by** is allowed; see **[D] by**.
**fweight**s, **iweight**s, and **pweight**s may be specified using **stset**; see **[ST]**
**stset**.

__Menu__

**Statistics > Survival analysis > Summary statistics, tests, and tables >**
**Person-time, incidence rates, and SMR**

__Description__

**stptime** calculates person-time and incidence rates. **stptime** computes
standardized mortality/morbidity ratios (SMRs) after merging the data
with a suitable file of standard rates specified with the **using()** option.

__Options__

+------+
----+ Main +-------------------------------------------------------------

**at(***numlist***)** specifies intervals at which person-time is to be computed.
The intervals are specified in analysis time t units. If **at()** is not
specified, overall person-time and incidence rates are computed.

If, for example, you specify **at(5(5)20)** and the **trim** option is not
specified, person-time is reported for the intervals t = (0 - 5], t =
(5 - 10], t = (10 -15], and t = (15 - 20].

**trim** specifies that observations less than or equal to the minimum or
greater than the maximum value listed in **at()** be excluded from the
computations.

**by(***varname***)** specifies a categorical variable by which incidence rates or
SMRs are to be computed.

+---------+
----+ Options +----------------------------------------------------------

**per(***#***)** specifies the units to be used in reported rates. For example, if
the analysis time is in years, specifying **per(1000)** results in rates
per 1,000 person-years.

**dd(***#***)** specifies the maximum number of decimal digits to be reported for
rates, ratios, and confidence intervals. This option affects only how
values are displayed, not how they are calculated.

**smr(***groupvar ratevar***)** specifies two variables in the **using()** dataset.
The *groupvar* identifies the age-group or calendar-period variable
used to match the data in memory and the **using()** dataset. The
*ratevar* variable contains the appropriate reference rates. **stptime**
then calculates SMRs rather than incidence rates.

**using(***filename***)** specifies the filename that contains a file of standard
rates that is to be merged with the data so that SMRs can be
calculated.

**level(***#***)** specifies the confidence level, as a percentage, for confidence
intervals. The default is **level(95)** or as set by **set level**.

**noshow** prevents **stptime** from showing the key st variables. This option
is seldom used because most people type **stset, show** or **stset, noshow**
to set whether they want to see these variables mentioned at the top
of the output of every st command; see **[ST] stset**.

+----------+
----+ Advanced +---------------------------------------------------------

**jackknife** specifies that jackknife confidence intervals be produced.
This is the default if **pweight**s or **iweight**s were specified when the
dataset was **stset**.

**title(***string***)** replaces the default "person-time" label on the output
table with *string*.

**output(***filename* [**, replace**]**)** saves a summary dataset in *filename*. The
file contains counts of failures and person-time, incidence rates (or
SMRs), confidence limits, and categorical variables identifying the
time intervals. This dataset could be used for further calculations
or simply as input to the **table** command.

**replace** specifies that *filename* be overwritten if it exists. This
option is not shown in the dialog box.

__Examples__

---------------------------------------------------------------------------
Setup
**. webuse stptime**

List part of the data
**. list in 1/5**

Declare data to be survival-time data
**. stset year, fail(fail) id(id) noshow**

Calculate person-time and incidence rate
**. stptime**

Calculate person-time and incidence rate per 1,000 person-years
**. stptime, per(1000)**

Same as above, but tabulate in ten-year intervals and display rates to
four decimal places
**. stptime, per(1000) at(0(10)40) dd(4)**

---------------------------------------------------------------------------
Setup
**. webuse diet**

Declare data to be survival-time data
**. stset dox, origin(time dob) enter(time doe) id(id)** **scale(365.25)**
**fail(fail==1 3 13) noshow**

Calculate person-time and incidence rates per 1,000 person-years,
tabulating in ten-year intervals, and excluding observations <=40 or >70
**. stptime, per(1000) at(40(10)70) trim**

Calculate standardized mortality ratios using **ageband** and **rate** in
**smrchd.dta**
**. stptime, smr(ageband rate)**
**using(http://www.stata-press.com/data/r15/smrchd) per(1000)**
**at(40(10)70) trim**

Calculate person-years and incidence rates per 1,000 person-years by
categories of **hienergy**
**. stptime, per(1000) by(hienergy)**

Same as above, but tabulating in ten-year intervals, and excluding
observations <=40 or >70
**. stptime, per(1000) by(hienergy) at(40(10)70) trim**

Same as above, but compute the SMR using **ageband** and **rate** in **smrchd.dta**
**. stptime, smr(ageband rate)**
**using(http://www.stata-press.com/data/r15/smrchd) per(1000)**
**by(hienergy) at(40(10)70) trim**
---------------------------------------------------------------------------

__Video example__

How to calculate incidence rates and incidence-rate ratios

__Stored results__

**stptime** stores the following in **r()**:

Scalars
**r(ptime)** person-time
**r(failures)** observed failures
**r(rate)** failure rate
**r(expected)** expected number of failures
**r(smr)** standardized mortality ratio
**r(lb)** lower bound for SMR
**r(ub)** upper bound for SMR