{smcl}
{* *! version 1.0.0  09aug2007}{...}
{cmd:help stpowplot logrank} 
{hline}

{title:Title}

{p2colset 5 26 20 0}{...}
{p2col :{hi:stpowplot logrank} {hline 2}}Power, sample-size, and other curves for {opt stpower} {cmd:logrank}{p_end}
{p2colreset}{...}


{title:Syntax}

{phang}
Estimated power vs sample size curve

{p 8 43 2}
{opt stpowplot} {opt log:rank} [{it:surv1} [{it:surv2}]] {cmd:,} 
{opt y:axis}{cmd:(power)} {opt x:axis}{cmd:(n)} {opt n(extlist)} [{it:options}
{it:cmdopts}]

{phang}
Estimated sample size vs power curve

{p 8 43 2}
{opt stpowplot} {opt log:rank} [{it:surv1} [{it:surv2}]] {cmd:,} 
{opt y:axis}{cmd:(n)} {opt x:axis}{cmd:(power)} {opt p:ower(extlist)} 
[{it:options} {it:cmdopts}]

{phang}
Other curves

{p 8 43 2}
{opt stpowplot} {opt log:rank} [{it:surv1} [{it:surv2}]] {cmd:,} {opt y:axis(ycol)} {opt x:axis(xcol)} [{it:options} {it:cmdopts}]

{phang}
where

{phang2}
{it:ycol} and {it:xcol} are one of {helpb stpower_logrank##colnames:colnames} of 
{cmd:stpower} {cmd:logrank}.
{p_end}

{phang2}
{it:surv1} and {it:surv2} may each be specified as {it:extlist} enclosed in
parentheses.{p_end}

{phang2}
{it:extlist} is defined as{p_end}
{phang3}
{it:{help numlist}} | {opt r:ange} {cmd:#min} {cmd:#max} [{opt np:oints} {cmd:#np}]
{p_end}
{phang2}
where{p_end}
{phang3}
{cmd:#np} is 20 if {cmd:npoints} is omitted.{p_end}

{phang2}
{it:cmdopts} are any options other than Reporting of 
{manhelp stpower_logrank ST: stpower logrank}.{p_end}

{synoptset 40 tabbed}{...}
{marker plotopts}{...}
{synopthdr}
{synoptline}
{syntab:Main}
{p2coldent:* {opt y:axis(ycol)}}y-axis column name{p_end}
{p2coldent:* {opt x:axis(xcol)}}x-axis column name{p_end}
{synopt:{cmd:by(}{it:{helpb stpower_logrank##colnames:colnames}}{cmd:)}}
separate plots over values of {it:colnames}{p_end}
{synopt:{cmd:over(}{it:{helpb stpower_logrank##colnames:colnames}}{cmd:)}}
overlaid plots over values of {it:colnames}{p_end}
{synopt:{cmdab:out:file(}{it:filename}[{cmd:,} {cmd:replace}]{cmd:)}}save the 
plot data to {it:filename}; use {cmd:replace} to overwrite existing 
{it:filename}{p_end}

{syntab:Plot}
{synopt:{opth ploto:pts(cline_options)}}affect rendition of plotted lines{p_end}
{synopt:{cmdab:plot:}{ul:{it:#}}{cmd:opts(}{it:{help cline_options}}{cmd:)}}affect rendition of the plotted line for the {it:#}th {cmd:over()}
category.{p_end}

{syntab:Add plots}
{synopt :{opth "addplot(addplot_option:plot)"}}add other plots to the generated graph{p_end}

{syntab:Y axis, X axis, Titles, Legend, Overall}
{synopt:{it:{help twoway_options}}}any options documented in 
{bind:{bf:[G] {it:twoway_options}}}{p_end}
{synopt:{opth byop:ts(by_option:byopts)}}how subgraphs are combined, labeled,
etc.{p_end}
{synoptline}
{p2colreset}{...}
{p 4 6 2}
* {cmd:yaxis()} and {cmd:xaxis()} are required.{p_end}


{title:Description}

{pstd}
{cmd:stpowplot} {cmd:logrank} produces power, sample-size, effect-size, and
other curves for the log-rank test.

{pstd}
You can use {cmd:stpowplot} {cmd:logrank} to

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

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

{phang2}
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

{phang2}
4.  produce many other curves.


{title:Options}

{dlgtab:Main}

{phang}
{opt yaxis(ycol)} specifies the column name {it:ycol} which values are to be
plotted on Y axis.  One of {helpb stpower_logrank##colnames:colnames} must be
specified.

{phang}
{opt xaxis(xcol)} specifies the column name {it:xcol} which values are to be
plotted on X axis.  One of {helpb stpower_logrank##colnames:colnames} must be
specified.

{phang}
{cmd:by(}{it:{helpb stpower_logrank##colnames:colnames}}{cmd:)} produces 
separate plots for each group identified by equal values of columns in
{it:colnames}.  Multiple column names may be specified.

{phang}
{cmd:over(}{it:{helpb stpower_logrank##colnames:colnames}}{cmd:)}
produces overlaid plots over groups identified by equal values of columns in
{it:colnames}.  Multiple column names may be specified.

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

{dlgtab:Plot}

{phang}
{opt plotopts(cline_options)} affects the rendition of the plotted lines; see
{manhelpi cline_options G}.  This option may not be combined with 
{opt over(colnames)}.

{phang}
{cmd:plot}{it:#}{cmd:opts(}{it:cline_options}{cmd:)} affects the rendition of the
plotted line for the {it:#}th {opt over(colnames)} category; see 
{manhelpi cline_options G}.

{dlgtab:Add plots}

{phang}
{opt addplot(plot)} provides a way to add other plots to the generated
graph; see {manhelpi addplot_option G}.

{dlgtab:Y axis, X axis, Titles, Legend, Overall}

{phang}
{it:twoway_options} are any of the options documented in 
{manhelpi twoway_options G}.  These include options for titling the graph (see 
{manhelpi title_options G}) and for saving the graph to disk (see
{manhelpi saving_option G}).

{phang}
{opt byopts(byopts)} affect the appearance of the combined graph, including
the overall graph title and the organization of subgraphs. See 
{manhelpi by_option G}.


{title:Introduction to stpowplot logrank}

{pstd}
{cmd:stpowplot} {cmd:logrank} follows a very similar syntax to {cmd:stpower}
{cmd:logrank}.  The user specifies input parameters in the same way.

{pstd}
The user must specify column names of study parameters to be plotted on the y-
and x-axis in options {cmd:yaxis()} and {cmd:xaxis()}.  Commonly, these study
parameters are {cmd:power}, {cmd:n}, and {cmd:hr}.  {cmd:yaxis()} usually will
contain the column name {it:ycol} of the study parameter that is to be
computed given other study parameters.  {cmd:xaxis()} would contain the column
name {it:xcol} of the study parameter for which the parameter of interest
{it:ycol} is to be computed.  In addition to specifying {cmd:yaxis()} and
{cmd:xaxis()}, the user must also supply the values of {it:xcol} in the
respective option of {cmd:stpower} {cmd:logrank} for which {it:ycol} is to be
computed.  These values may be supplied as {it: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 {cmd:s1} and {cmd:s2} the values must be
specified as input arguments {it:surv1} and {it:surv2} enclosed in
parentheses.

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

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

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


{title:Examples}

{pstd}
Plot number of failures as a function of a hazard ratio for a 5% two-sided
log-rank test with 80% power{p_end}
{phang2}
{cmd:. stpowplot logrank, power(0.8) hratio(range 0.4 0.8) yaxis(e) xaxis(hr)}
{p_end}

{pstd}
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.{p_end}
{phang2}
{cmd:. stpowplot logrank 0.4, hratio(r 0.4 0.8) n(100 200 300) yaxis(power)} 
         {cmd: xaxis(hr) over(n)}

{pstd}
For the study design above, plot power as a function of sample size separately
for 0.05 and 0.1 significance levels.{p_end}
{phang2}
{cmd:. stpowplot logrank 0.4, n(r 100 300 np 30) alpha(0.05 0.1) yaxis(power)}
         {cmd: xaxis(n) by(alpha) yline(0.9)}

{pstd}
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.{p_end}
{phang2}
{cmd:. stpowplot logrank 0.4, hratio(0.5 0.6) n(r 100 300) alpha(0.05 0.1)} 
         {cmd: yaxis(power) xaxis(n) by(alpha) over(hr)}

{pstd}
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).{p_end}
{phang2}
{cmd:. stpowplot logrank (0.4 0.5), nratio(1 3) hratio(0.5 0.6) n(r 100 300)}
         {cmd: alpha(0.05 0.1) yaxis(power) xaxis(n) by(alpha nratio) over(hr s1)}

{pstd}
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{p_end}
        {cmd:. qui stpowplot logrank 0.4, hratio(r 0.4 0.8) yaxis(n) xaxis(hr)}
           {cmd: outfile(mydata) nodraw}
        {cmd:. use mydata}
        {cmd:. stpowplot logrank 0.4, hratio(r 0.4 0.8) yaxis(e) xaxis(hr)}
           {cmd: addplot(line n hr, sort) ytitle("")}
           {cmd: title(Number of events and subjects vs hazard ratio)}
           {cmd: legend(label(1 "Number of events, E")}
                  {cmd: label(2 "Number of subjects, N")}
                  {cmd: cols(1))}


{title:Also see}

{psee}
Online:  {manhelp stpower_logrank ST: stpower logrank}
{p_end}