{smcl}
{* 06jul2007}{...}
{cmd:help gengammareg} 
{hline}

{title:Title}

{p2colset 5 20 22 2}{...}
{p2col :{hi:gengammareg} {hline 2}}Generate a time response appropriate for
{cmd:streg, distribution(gamma)}{p_end}
{p2colreset}{...}


{title:Syntax}

{p 8 13 2}
{cmd:gengammareg} {dtype} {newvar} {ifin} [{cmd:,} {it:options}]

{synoptset 21 tabbed}{...}
{synopthdr}
{synoptline}

{synopt: {opt xb:eta}{cmd:(}{it:{help varname:varname}}|{it:#}{cmd:)}}specify linear predictor, x'b; default is 0{p_end}
{synopt: {opt tr}{cmd:(}{it:{help varname:varname}}|{it:#}{cmd:)}}specify time ratio, equivalent to exp(x'b); default is 1{p_end}
{synopt: {opt k:appa}{cmd:(}{it:#}{cmd:)}}specify kappa; default is 0{p_end}
{synopt: {opt s:igma}{cmd:(}{it:#}{cmd:)}}specify sigma; default is 1{p_end}
{synoptline}


{title:Description}

{pstd}
{cmd:gengammareg} generates a time response that can be used with 
{cmd:streg, distribution(gamma)}, which fits a generalized gamma 
distribution to survival data.  The parameters that you specify to 
{cmd:gengammareg} mirror those that you would see in the output for 
{cmd:streg} when fitting a gamma model; you have a linear predictor 
or time ratio, and the ancillary parameters kappa and sigma.

{pstd}
Use {cmd:gengammareg} if you wish to simulate data for fitting gamma 
models via {cmd:streg}.  Since the exponential, Weibull, and lognormal
models are all special cases of gamma, you can use {cmd:gengammareg}
to generate data for these models as well.


{title:Options}

{phang}
{opt xb:eta}{cmd:(}{it:{help varname:varname}}|{it:#}{cmd:)} specifies
the linear predictor.  The linear predictor may be specified either as the
variable {it:{help varname:varname}} or, in the case of a constant-only gamma
model, as the constant {it:#} corresponding to _b[_cons] in {cmd:streg}
output.  By default, {cmd:xbeta()} is the constant 0, equivalent to 
_b[_cons] = 0.

{phang}
{opt tr}{cmd:(}{it:{help varname:varname}}|{it:#}{cmd:)} specifies 
the time ratio, equivalent to the exponentiated linear predictor.  The
time ratio may be specified either as the variable 
{it:{help varname:varname}} or, in the case of a constant-only gamma model, 
as the constant {it:#} corresponding to exp(_b[_cons]).  By default, 
{cmd:tr()} is the constant 1, equivalent to _b[_cons] = 0.

{phang}
{opt kappa} specifies the parameter kappa; see {bf:[ST] streg}.  The default
value of {opt kappa} is 0.

{phang}
{opt sigma} specifies the parameter sigma; see {bf:[ST] streg}.  The default
value of {opt sigma} is 1.

{pmore}
Given the default values of {cmd:kappa} and {cmd:sigma}, {cmd:gengammareg}
will by default generate lognormal data with {cmd:sigma} equal to 1.


{title:Remarks}

{pstd}
Those familiar with generalized gamma regression as implemented in {cmd:streg}
know that the model is parameterized so as to reduce to Weibull when
{cmd:kappa} = 1, exponential when {cmd:kappa} = 1 and {cmd:sigma} = 1, and
lognormal when {cmd:kappa} = 0.  These are nice properties, but a consequence
of this parameterization is that the resulting probability density bears
little resemblance to the three-parameter gamma density found in most
mathematical statistics texts.  This makes generating data from this model a
little more difficult.

{pstd}
A standard Gamma({res:a},{res:b},{res:g}) is a three-parameter generalization
of the standard two-parameter Gamma({res:a},{res:b}), which has mean
{res:a}*{res:b} and variance {res:a}*{res:b}^2.  If y is distributed as
Gamma({res:a},{res:b}), then z = {res:b}(y/{res:b})^(1/{res:g}) is distributed
as Gamma({res:a},{res:b},{res:g}).

{pstd}
The parameterization of gamma used by {cmd:streg}, however, is such that
the linear predictor, {cmd:xbeta} = log{{res:b}*{res:a}^(1/{res:g})}, 
{cmd:kappa} = sign({res:g})/sqrt({res:a}), and {cmd:sigma} = 
1/{sqrt({res:a})*|{res:g}|}.  Note that {res:g} can be negative.

{pstd}
Reversing the transform (and being mindful that {cmd:kappa} is also allowed 
to be negative) yields {res:a} = 1/({cmd:kappa}^2), 
{res:b} = exp({cmd:xbeta})*|{cmd:kappa}|^(2*{cmd:sigma}/{cmd:kappa}), 
and {res:g} = {cmd:kappa}/{cmd:sigma}.

{pstd}
The default case of {cmd:kappa} = 0 is degenerate and must be treated as a
limiting case.  Since {cmd:kappa} = 0 corresponds to lognormal data, the
random times are generated as exponentiated Gaussian random deviates, where
the Gaussian distribution has mean log({cmd:tr}) = {cmd:xbeta} and standard
deviation {cmd:sigma}.

{pstd}
But, these are just technical details stated more as a reminder to the
author.  {cmd:gengammareg} does all the work for you.

{pstd}
If you are using {cmd:gengammareg} to generate Weibull or exponential
data, note that the data are generated using the accelerated failure time
(AFT) parameterization of these models, and not the default hazard ratio (HR)
parameterization.  When using {cmd:streg} with these data, therefore, remember
to specify option {cmd:time} for AFT.   For Weibull data, row "p" in 
{cmd:streg} output corresponds to 1/{cmd:sigma}
as defined here.  Thus, an estimate of {cmd:sigma} can be found in row "1/p"
of the output produced by {cmd:streg, distribution(weibull)}.


{title:Examples}

    {hline}
{pstd}Setup{p_end}
{phang2}{cmd: . clear}{p_end}
{phang2}{cmd: . set obs 1000}{p_end}
{phang2}{cmd: . gen x1 = invnorm(uniform())}{p_end}
{phang2}{cmd: . gen xb = -1 + 0.5*x1}{p_end}

{pstd}Generate gamma-distributed survival times{p_end}
{phang2}{cmd: . gengammareg t, xbeta(xb) kappa(-0.4) sigma(0.5)}{p_end}

{pstd}{cmd:stset} the data and fit a gamma regression model{p_end}
{phang2}{cmd: . stset t}{p_end}
{phang2}{cmd: . streg x1, distribution(gamma)}{p_end}

    {hline}
{pstd}Setup{p_end}
{phang2}{cmd: . clear}{p_end}
{phang2}{cmd: . set obs 1000}{p_end}
{phang2}{cmd: . gen x1 = invnorm(uniform())}{p_end}
{phang2}{cmd: . gen xb = -1 + 0.5*x1}{p_end}

{pstd}Generate lognormal-distributed survival times{p_end}
{phang2}{cmd: . gengammareg t, xbeta(xb) sigma(0.5)}{p_end}

{pstd}{cmd:stset} the data and fit a gamma regression model{p_end}
{phang2}{cmd: . stset t}{p_end}
{phang2}{cmd: . streg x1, distribution(lognormal)}{p_end}

    {hline}
{pstd}Setup{p_end}
{phang2}{cmd: . clear}{p_end}
{phang2}{cmd: . set obs 1000}{p_end}
{phang2}{cmd: . gen x1 = invnorm(uniform())}{p_end}
{phang2}{cmd: . gen xb = -1 + 0.5*x1}{p_end}

{pstd}Generate Weibull-distributed survival times{p_end}
{phang2}{cmd: . gengammareg t, xbeta(xb) kappa(1) sigma(0.5)}{p_end}

{pstd}{cmd:stset} the data and fit a Weibull regression model{p_end}
{phang2}{cmd: . stset t}{p_end}
{phang2}{cmd: . streg x1, distribution(weibull) time}{p_end}

    {hline}
{pstd}Setup{p_end}
{phang2}{cmd: . clear}{p_end}
{phang2}{cmd: . set obs 1000}{p_end}
{phang2}{cmd: . gen x1 = invnorm(uniform())}{p_end}
{phang2}{cmd: . gen xb = -1 + 0.5*x1}{p_end}

{pstd}Generate exponentially-distributed survival times{p_end}
{phang2}{cmd: . gengammareg t, xbeta(xb) kappa(1)}{p_end}

{pstd}{cmd:stset} the data and fit an exponential regression model{p_end}
{phang2}{cmd: . stset t}{p_end}
{phang2}{cmd: . streg x1, distribution(exponential) time}{p_end}

    {hline}


{title:Also see}

{psee}
Online:  {help st}, {helpb stset}, {helpb streg}