{smcl}
{* 12jan2004}{...}
{hline}
help for {hi:stsatrisk} {right:(SJ4-4: st0058_2; SJ4-2: st0058_1; SJ4-1: st0058)}
{right: dialog {dialog stsatrisk}}

{hline}

{title:A wrapper to {cmd:sts graph} which adds notation to the graph with the number at risk}

{p 8 21 2}{cmd:stsatrisk} {space 2} [{cmd:if} {it:exp}] [{cmd:in} {it:range}] [{cmd:,}
{cmdab:catr:isk:(}{it:numlist} [{cmd:,} {it:{help textbox_options}} ]{cmd:)} 
{cmdab:nol:abel} {cmdab:showe:vents} {cmdab:tableg:end}
{cmdab:cl:abel(}{it:labels}{cmd:)} {cmdab:tablab:el(}{it:string}{cmd:)}
{cmdab:ll:ength(}{it:#}{cmd:)} {cmdab:ls:pace(}{it:#}{cmd:)}
{cmdab:vs:pace(}  {it:#}{cmd:)} {it:sts_graph_options}
{it:{help cline_options}} {it:{help twoway_options}} ]

{p 4 4 2}
{cmd:stsatrisk} is for use with survival-time data; see help {help st}.
You must have {cmd:stset} your data before using these commands; see
help {help stset}.


{title:Description}

{p 4 4 2}
{cmd:stsatrisk} is a wrapper to {cmd:sts graph}, and adds notation to the
Kaplan-Meier graph with the number at risk.  Only the survivor and failure
functions can be graphed.  With no options, {cmd: stsatrisk} will
calculate 5 good values for the major ticks on the x-axis and label the
at risk information at these points.

{p 4 4 2}
This command is limited in its facilities; it will not work with every
{cmd:sts graph} option and will not necessarily produce pretty graphs
with every scheme or possible graph option.  You can have up to 6 {cmd:by} 
or {cmd:strata} groups, no more.  Even with 6, you can still run into
a {it:too many options} error -- see notes below for more information.

{title:Options for {cmd:stsatrisk}}

{p 4 8 2}
{cmd:catrisk(}{it:numlist} [{cmd:,} {it:textbox_options} ]{cmd:)} customize
the time values at which the at risk information is to be noted.  This list
will also provide the (labeled) major ticks on the time axis.

{p 8 8 2}
{it:textbox_options} affect how the added text for the at risk information is
displayed.  They are described in help {help textbox_options}.

{p 4 8 2}
{cmd:showevents} show the number failed for the period after
the time point when at risk information was calculated in parentheses
after the at risk information.  

{p 4 8 2}
{cmd:clabel}({it:labels}) provide custom labels for the at risk table rows.  
These labels will also be used to label the legend if one is
generated.  

{p 4 8 2}
{cmd:nolabel} suppresses the use of value labels of the {cmd:by} or
{cmd:strata} variable to label the at risk table, and instead labels
by its values.  {cmd:nolabel} may only be specified with {cmd:by} 
or {cmd:strata}.

{p 4 8 2}
{cmd:tablabel} provide a customized label or title for the at risk table.

{p 4 8 2}
{cmd:tablegend} include a table summarizing the at risk and event data
with the legend.

{p 4 8 2}
{cmd:llength(}{it:#}{cmd:)} specifies the maximum length of labels used 
in the at risk table and legend if value labels are used.  If custom 
labels are specified with the {cmd:clabel} option, the length is 
unrestricted.  If there is one string {cmd:by} or {cmd:strata} variable,
its values will also be used without truncation.  The default value is 16.

{p 4 8 2}
{cmd:lspace(}{it:#}{cmd:)} allows the user to increase or decrease the
horizontal (label) space for the at risk table labels.  The default 
value is one, and {cmd:lspace} multiplies the horizontal space parameters.

{p 4 8 2}
{cmd:vspace(}{it:#}{cmd:)} allows the user to increase or decrease the vertical
space for the at risk table.  The default value is one, and
{cmd:vspace} multiplies the vertical space parameters.

{p 4 8 2}
{it:sts_graph_options} are (most of) the options documented in help
{help sts} for the {cmd:sts graph} command.  

{p 4 8 2}
{it:cline_options} are any of the options documented in help
{help cline_options}.

{p 4 8 2}
{it:twoway_options} are any of the options documented in help
{help twoway_options}.  These include options for titling the graph
(see help {help title_options}) and options for saving the graph to disk
(see help {help saving_option}).

{p 8 8 2}
Options {cmd:xmtick()} and {cmd:ymtick()} are not allowed with {cmd:stsatrisk}.
They are used to create space for the at risk table, and so are not available
to the user.

{title:Examples}
    
{p 4 8 2}{cmd:. sysuse cancer, clear}{p_end}
{p 4 8 2}{cmd:. stset studytime, failure(died)}{p_end}
{p 4 8 2}{cmd:. stsatrisk}{p_end}
{p 4 8 2}{cmd:. stsatrisk, catr(0(15)45) gwood}{p_end}
{p 4 8 2}{cmd:. stsatrisk, by(drug)}{p_end}
{p 4 8 2}{cmd:. label define drugtype 1 "placebo" 2 "drug A" 3 "drug B" }{p_end}
{p 4 8 2}{cmd:. label value drug drugtype}{p_end}
{p 4 8 2}{cmd:. stsatrisk, catr(0(15)45) by(drug)}{p_end}
{p 4 8 2}{cmd:. stsatrisk, by(drug) nolabel}{p_end}
{p 4 8 2}{cmd:. stsatrisk, catr(0(15)45, size(*.6)) by(drug)}{p_end}
{p 4 8 2}{cmd:. stsatrisk, by(drug) showev}{p_end}
{p 4 8 2}{cmd:. stsatrisk, by(drug) tableg}{p_end}

{title:Notes}

{p 4 4 2}
If users wish to add additional descriptive information to the
graph, e.g. the results of an associated log-rank chi-squared
test, this can be easily done via the graph options {cmd:caption()} or
{cmd:note()}.

{p 4 4 2}
{cmd:stsatrisk} uses ad-hoc calculation to create space for
the at risk table, and then makes extensive use of the {cmd:addtext()}
option to graphs to create the table.  It works pretty well most
of the time, but problems can occur.  

{p 4 4 2}
If labels are too long, they can overlap other parts of the graph.
This can generally be remedied first, by adjusting the {cmd:lspace()} and
{cmd:vspace()}  options.  These options have default values of 1,
and multiply the label space (horizontal) and vertical space respectively.  
Another fix is to use the {cmd:size()} option to the {cmd:catrisk()}
option, specifying {cmd:catr(0(15)45, size(*.6)} reduces the text size by 
a factor of 0.6.

{p 4 4 2}
An error of {it:too many options} can also be generated.  This
indicates the number of {cmd:addtext()} options generated automatically
by the code is too high.  This can be remedied by reducing the
number of {cmd:by} or {cmd:strata} groups, and/or reducing the number
of tick marks at which at risk information is to be given.
This can be modified through the {cmd:catrisk()} option.

{p 4 4 2}
The code also contains extensive comments to assist user-programmers
and non-programmers alike in making changes, if their particular problem
cannot be fixed by modifications to the call as specified above.

{title:Author}

{p 4 4 2}
The primary author is Jean Marie Linhart, StataCorp LP, jlinhart@stata.com.
Secondary authors are Jeffrey S. Pitblado and Jens Lauritsen.  James Hassell
wrote the dialog.  Please contact the primary author with bug reports.

{title:Also see}

{p 4 13 2}
Manual:  {hi:[ST] sts graph}{break}

{p 4 13 2}
Online:  help for {help st}, {help stci}, {help sts}