.-
help for ^simul2^                                            (STB-43: ip25)
.-

Monte Carlo simulations
-----------------------

        ^simul2^ progname^, r^eps^(^#^)^ [ ^a^rgs^(^whatever^) d^ots ^p^ar^(^plist^) report^ ]

where 
        plist = parameter-name numlist [, plist]
        

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

^simul^ eases the programming task of performing Monte Carlo type simulations.
progname is the name of a program that performs a single simulation.  Typing
"^simul^ progname^, reps(^#^)^" iterates progname # replications and collects the
results, replacing data in memory.

^simul^ calls progname two ways.  At the outset, ^simul^ issues "progname ^?^" and
expects progname to set the global macro $S_1 to contain a list of variable
names under which results are to be stored.  Thereafter, ^simul^ issues 
"progname postname" calls and expects it to perform a single simulation and
to store the results using "^post^ postname".  Details of ^post^ can be found in
help @postfile@ but enough information is provided below to use ^post^ 
successfully.

^simul2^ is a backward compatible version of ^simul^, adding the full-factorial 
simulation in one or more scalar parameters.  


Options
-------

^reps(^#^)^ is not optional -- it specifies the number of replications to be
    performed (within each condition formed by a unique combination of values 
    of parameters).

^args(^whatever^)^ specifies any arguments to be passed to progname on invocation.
    The query call is then of the form "progname ^?^ whatever" and subsequent
    calls of the form "progname whatever".

^dots^ requests a dot be placed on the screen at the beginning of every call
    to progname, thus providing entertainment during a long simulation.
    If parameters for the simulation are specified, their values are 
    displayed whenever changed for additional thrill.

^par(^plist^)^ specifies one or more parameter specifications separated by 
    commas. A parameter specification consists or a parameter name followed 
    by a numlist such as 1-5 or 0-1/0.10 (see help ^numlist^). 

^report^ specifies that a brief report is displayed with the interpretation 
    of the parameters.
    
    
Remarks
-------

progname must have the following outline: 

        ^program define^ progname 
                ^if "`1'"=="?" {^
                        ^global S_1 "^variable names^"^
                        ^exit^
                ^}^
                perform single simulation 
                ^post `1'^ results
        ^end^

There must be the same number of results following the ^post^ command as 
variable names following the ^global S_1^ command.

The replication counter, valued 1..^reps^, is available in the program progname 
in the scalar ^REPL^.

If parameters are specified (see option ^par^), their names ^must^ be included 
in ^S_1^, before other results to be saved, and in the same order as specified 
on the command line. ^simul2^ defines scalars, named as the parameters, to the 
appropriate values (silently overwriting any existing results) to be used 
within progname. 


Example
-------

1. Make a dataset containing means and variances of 100-observation samples 
from a log-normal distribution.  Perform the experiment 10,000 times:

        ^program define lnsim^
                ^if "`1'"=="?" {^
                        ^global S_1 "mean var"^
                        ^exit^
                ^}^
                ^drop _all^
                ^set obs 100^
                ^gen z = exp(invnorm(uniform()))^
                ^summarize z^
                ^post `1' _result(3) _result(4)^
        ^end^

^lnsim^ can then be executed 10,000 times by typing

        . ^simul2 lnsim, reps(10000)^
        
2. Using the parameter mechanism it is easy to study the effects of changing 
the sample size between 100 and 1000 in steps of 100.

        ^program define lnsim^
                ^if "`1'"=="?" {^
                        ^global S_1 "N mean var"^
                        ^exit^
                ^}^
                ^drop _all^
                * Stata does not allow "set obs scalar". Thus we first
                * have to copy the contents of N into a (local) macro.
                ^local Nobs = `N'^ 
                ^set obs `Nobs'^
                ^gen z = exp(invnorm(uniform()))^
                ^summarize z^
                ^post `1' N _result(3) _result(4)^
        ^end^

^lnsim^ can then be executed 10,000 times by typing

        . ^simul2 lnsim, reps(10000) par(N 100-1000/100)^
        
Note that the parameter name ^N^ is included in the definition of ^S_1^ in 
^lnsim^, in the ^post^ command, and in calling ^simul2^.        


Author
------

      Jeroen Weesie
      Utrecht University
      Netherlands
      weesie@@weesie.fsw.ruu.nl


Also see
--------

    STB:  STB-43 ip25
 Manual:  [R] simul
On-line:  help for @bstrap@, @postfile@, @numlist@