*! version 1.0.0 09aug2007
help stpowplot logrank

Title

stpowplot logrank -- Power, sample-size, and other curves for stpower logrank

Syntax

Estimated power vs sample size curve

stpowplot logrank [surv1 [surv2]] ,
yaxis(power) xaxis(n) n(extlist) [options
cmdopts]

Estimated sample size vs power curve

stpowplot logrank [surv1 [surv2]] ,
yaxis(n) xaxis(power) power(extlist)
[options cmdopts]

Other curves

stpowplot logrank [surv1 [surv2]] , yaxis(ycol) xaxis(xcol) [options cmdopts]

where

ycol and xcol are one of colnames of
stpower logrank.

surv1 and surv2 may each be specified as extlist enclosed in
parentheses.

extlist is defined as

numlist | range #min #max [npoints #np]

where

#np is 20 if npoints is omitted.

cmdopts are any options other than Reporting of
[ST] stpower logrank.

Main
* yaxis(ycol) y-axis column name

* xaxis(xcol) x-axis column name

by(colnames)
separate plots over values of colnames

over(colnames)
overlaid plots over values of colnames

outfile(filename[, replace]) save the
plot data to filename; use replace to overwrite existing
filename

Plot
plotopts(cline_options) affect rendition of plotted lines

plot#opts(cline_options) affect rendition of the plotted line for the #th over()
category.

Add plots
"addplot(addplot_option:plot)" add other plots to the generated graph

Y axis, X axis, Titles, Legend, Overall
twoway_options any options documented in
[G] twoway_options

byopts(by_option:byopts) how subgraphs are combined, labeled,
etc.

* yaxis() and xaxis() are required.

Description

stpowplot logrank produces power, sample-size, effect-size, and
other curves for the log-rank test.

You can use stpowplot logrank to

1. produce a power curve as a function of the effect size (expressed as a
hazard ratio) over the values of the sample size,

2. plot sample size as a function of power or hazard ratio separately for
various group-allocation ratios,

3. plot effect size (expressed as a hazard ratio or log hazard ratio) as a
function of power over the values of the sample size separately for different
significance levels, and

4. produce many other curves.

Options

Main

yaxis(ycol) specifies the column name ycol which values are to be
plotted on Y axis. One of colnames must be
specified.

xaxis(xcol) specifies the column name xcol which values are to be
plotted on X axis. One of colnames must be
specified.

by(colnames) produces
separate plots for each group identified by equal values of columns in
colnames. Multiple column names may be specified.

over(colnames)
produces overlaid plots over groups identified by equal values of columns in
colnames. Multiple column names may be specified.

outfile(filename[, replace]) creates a Stata data
file (.dta file) containing the values used to produce a graph.
replace indicates that filename be overwritten, if it exists.

Plot

plotopts(cline_options) affects the rendition of the plotted lines; see
[G] cline_options. This option may not be combined with
over(colnames).

plot#opts(cline_options) affects the rendition of the
plotted line for the #th over(colnames) category; see
[G] cline_options.

Add plots

addplot(plot) provides a way to add other plots to the generated
graph; see [G] addplot_option.

Y axis, X axis, Titles, Legend, Overall

twoway_options are any of the options documented in
[G] twoway_options. These include options for titling the graph (see
[G] title_options) and for saving the graph to disk (see
[G] saving_option).

byopts(byopts) affect the appearance of the combined graph, including
the overall graph title and the organization of subgraphs. See
[G] by_option.

Introduction to stpowplot logrank

stpowplot logrank follows a very similar syntax to stpower
logrank. The user specifies input parameters in the same way.

The user must specify column names of study parameters to be plotted on the y-
and x-axis in options yaxis() and xaxis(). Commonly, these study
parameters are power, n, and hr. yaxis() usually will
contain the column name ycol of the study parameter that is to be
computed given other study parameters. xaxis() would contain the column
name xcol of the study parameter for which the parameter of interest
ycol is to be computed. In addition to specifying yaxis() and
xaxis(), the user must also supply the values of xcol in the
respective option of stpower logrank for which ycol is to be
computed. These values may be supplied as extlist described above, i.e.
either as a number list or by specifying the number of points and the range of
values. Note that for columns s1 and s2 the values must be
specified as input arguments surv1 and surv2 enclosed in
parentheses.

For example, if we want to plot power as a function of the hazard ratio, we
specify column names power and hr in options yaxis() and
xaxis() as yaxis(power) and xaxis(hr). We also supply the
value of the hazard ratio for which the power is to be computed and plotted in
option hratio().

Although yaxis() and xaxis() allow specifying any column name of
stpower logrank, some of the column names would be appropriate as
y-axis columns, and others as x-axis columns. For example, since p1 is
never computed but accepts multiple values, it would be more appropriate to be
used in xaxis(). Other columns, say alpha, are more suitable to
be used in by() or over().

stpowplot logrank allows you to produce desired curves over the
values of other parameters by using options by() and/or over().
It plots the curves on separate graphs defined by the unique categories of
columns specified in by(), and overlays the curves obtained for the
unique categories of columns specified in over() on one graph. If
by() and over() are combined, a separate graph with overlaid
curves (obtained over the over() categories within each by()
category) is produced for each by() category.

Examples

Plot number of failures as a function of a hazard ratio for a 5% two-sided
log-rank test with 80% power

. stpowplot logrank, power(0.8) hratio(range 0.4 0.8) yaxis(e) xaxis(hr)

Plot power as a function of hazard ratio for a 5% two-sided
log-rank test over sample sizes of 100, 200, and 300. Assume 40% survival in the
control group by the end of the study.

. stpowplot logrank 0.4, hratio(r 0.4 0.8) n(100 200 300) yaxis(power)
xaxis(hr) over(n)

For the study design above, plot power as a function of sample size separately
for 0.05 and 0.1 significance levels.

. stpowplot logrank 0.4, n(r 100 300 np 30) alpha(0.05 0.1) yaxis(power)
xaxis(n) by(alpha) yline(0.9)

Plot power as a function of sample size over hazard ratios of 0.5, 0.6 and
separately for 0.05 and 0.1 significance levels.

. stpowplot logrank 0.4, hratio(0.5 0.6) n(r 100 300) alpha(0.05 0.1)
yaxis(power) xaxis(n) by(alpha) over(hr)

Plot power as a function of sample size over hazard ratios of 0.5, 0.6 and
control-group survival of 0.4, 0.5, and separately for 0.05 and 0.1
significance levels and 1:1 and 1:2 group allocation ratios (N2/N1).

. stpowplot logrank (0.4 0.5), nratio(1 3) hratio(0.5 0.6) n(r 100 300)
alpha(0.05 0.1) yaxis(power) xaxis(n) by(alpha nratio) over(hr s1)

Compare plots of number of failures and number of subjects as a function of
hazard ratio for the 5% two-sided log-rank test with 80% power assuming 40%
survival in the control group by the end of the study

. qui stpowplot logrank 0.4, hratio(r 0.4 0.8) yaxis(n) xaxis(hr)
outfile(mydata) nodraw
. use mydata
. stpowplot logrank 0.4, hratio(r 0.4 0.8) yaxis(e) xaxis(hr)
addplot(line n hr, sort) ytitle("")
title(Number of events and subjects vs hazard ratio)
legend(label(1 "Number of events, E")
label(2 "Number of subjects, N")
cols(1))

Also see

Online: [ST] stpower logrank