simul_confusion/Modules/ado/plus/p/praccum.hlp

.-
help for ^praccum^ - 1.6.4 - 2Nov2005
.-

Accumulate results from ^prvalue^
-------------------------------

  ^praccum^, [^xis(^value^)^ ^u^sing^(^matrixnm^)^ ^s^aving^(^matrixnm^)^ ^gen^erate^(^rootname^)^]

where either saving() or using() are required.

Description
-----------

^praccum^ accumulates predictions from a series of calls to ^prvalue^ and 
optionally saves these accumluated values to variables. These variables can 
then be plotted. This command allows you to plot predicted values in 
situations that cannot be handled by ^prgen^ (e.g., nonlinearities).

The command works with cloglog, cnreg, intreg, logit, mlogit, mprobit, nbreg, 
ologit, oprobit, poisson, probit, regress, slogit, tobit, zinb, zip, ztnb, 
and ztp.


Options
-------

^xis(^value^)^ specifies the value of the x-variable associated with the predicted
    values that are being accumulated.  If ^xis^ is not specified, new values
    are not accumulated.

^using(^matrixnm^)^ specifies the name of matrix to which accumulated results 
    should be added.  ^matrixnm^ will be created if it does not exist.

^saving(^matrixnm^)^: is only used to save the initial results and differs from
    differs from ^using()^ in that it will overwrite ^matrixnm^ if it exists.

^generate(^rootname^)^: root name of variables to be created from the matrix 
    specified by ^using^. This is only used when you are done accumulating 
    results and are ready to generate the variables.

Examples of included squared terms
----------------------------------

Consider the logit:

^. use binlfp,clear^
^. gen age2 = age*age^
^. logit lfp k5 k618 age age2 wc hc lwg inc^

If you want to plot the predictions against age, you cannot use ^prgen^ since 
when age changes, age2 must also change. The command:

^. prvalue , x(age=20 age2=400) rest(mean)^

computes predicted values for age=20 and age2=20*20=400. The command:

^. praccum , saving(mage) xis(20)^

creates a matrix named mage that contains three columns. The first column will
have a 20 for the value of age; the second the probability of a 0 given the 
values of the independent variables used in ^prvalue^, and the third column 
will have the probability of a 1. We now change the value of age and add this
to the matrix mage:

^. prvalue , x(age=25 age2=625) rest(mean)^
^. praccum , using(mage) xis(25)^

Here we are just adding a row to mage. This process repeats for other values:

^. prvalue , x(age=30 age2=900) rest(mean)^
^. praccum , using(mage) xis(30)^
^. prvalue , x(age=35 age2=1225) rest(mean)^
^. praccum , using(mage) xis(35)^
^. prvalue , x(age=40 age2=1600) rest(mean)^
^. praccum , using(mage) xis(40)^
^. prvalue , x(age=45 age2=2025) rest(mean)^
^. praccum , using(mage) xis(45)^
^. prvalue , x(age=50 age2=2500) rest(mean)^
^. praccum , using(mage) xis(50)^
^. prvalue , x(age=55 age2=3025) rest(mean)^
^. praccum , using(mage) xis(55)^
^. prvalue , x(age=60 age2=3600) rest(mean)^
^. praccum , using(mage) xis(60) gen(agsq)^

Produces the output:

^New variables created by praccum:^

^Variable |     Obs        Mean   Std. Dev.       Min        Max^
^---------+-----------------------------------------------------^
^   agsqx |       9          40   13.69306         20         60^
^  agsqp0 |       9    .4282142   .1752595   .2676314   .7479599^
^  agsqp1 |       9    .5717858   .1752595   .2520402   .7323686  ^

Which can be plotted:

^. graph agsqp1 agsqx,c(s)^

Example using ^forvalues^
-------------------------

The ^forvalues^ command makes using ^praccum^ much simpler.  The
following yields the same output as the example above:

^. capture matrix drop mage^
^. forvalues count = 20(5)60 {^
^.    local countsq = `count'*`count'^
^.    prvalue, x(age `count' age2 `countsq') rest(mean) brief^
^.    praccum, using(mage) xis(`count')^
^. }^
^. praccum, using(mage) gen(agsq)^

Example using global macros
---------------------------

^forvalues^ is not available for Stata 6.  Here, the task can still be 
simplified by using global macros. The advantage of this approach is
that you can let Stata do the multiplying:

^. global age = 20^
^.     global age2 = $age*$age^
^.     prvalue , x(age=$age age2=$age2) rest(mean)^
^.     praccum , saving(mage) xis($age)^
^. global age = 25^
^.     global age2 = $age*$age^
^.     prvalue , x(age=$age age2=$age2) rest(mean)^
^.     praccum , using(mage) xis($age)^
^. global age = 30^
^.     global age2 = $age*$age^
^.     prvalue , x(age=$age age2=$age2) rest(mean)^
^.     praccum , using(mage) xis($age)^
^. global age = 35^
^.     global age2 = $age*$age^
^.     prvalue , x(age=$age age2=$age2) rest(mean)^
^.     praccum , using(mage) xis($age)^
^. global age = 40^
^.     global age2 = $age*$age^
^.     prvalue , x(age=$age age2=$age2) rest(mean)^
^.     praccum , using(mage) xis($age)^
^. global age = 45^
^.     global age2 = $age*$age^
^.     prvalue , x(age=$age age2=$age2) rest(mean)^
^.     praccum , using(mage) xis($age)^
^. global age = 50^
^.     global age2 = $age*$age^
^.     prvalue , x(age=$age age2=$age2) rest(mean)^
^.     praccum , using(mage) xis($age)^
^. global age = 55^
^.     global age2 = $age*$age^
^.     prvalue , x(age=$age age2=$age2) rest(mean)^
^.     praccum , using(mage) xis($age)^
^. global age = 60^
^.     global age2 = $age*$age^
^.     prvalue , x(age=$age age2=$age2) rest(mean)^
^.     praccum , using(mage) xis($age) gen(agsq)^
^. graph agsqp1 agsqx,c(s)^

.-
Authors: J. Scott Long - jslong@@indiana.edu
         Jeremy Freese - jfreese@@ssc.wisc.edu
         www.indiana.edu/~jslsoc/