Vassilis Hajivassiliou                           March 1992
                        ssmlmnp program
(multiperiod/multinomial probit using Smooth Simulated Maximum Likelihood)


1.  Create a profile file using 'ssmlmnp.pro' as a template, specifying
    the configuration of your program -- see the end of this doc file.

2.  To use the program in conjunction with the profile file 'myfile.pro'
    you should issue

       ssmlmnp myfile

    The default output will be printed on the screen.  In order to save
    the default output in file 'myfile.scn' you should issue

       ssmlmnp myfile >& myfile.scn

    In usual unix fashion, if you would like to have the program run
    as a background process, you should append the ampersand '&'
    character at the end of the command line.

    For example, the command

      ssmlmnp myfile >& myfile.scn &

    will run the program in the background, saving all screen
    messages into  file myfile.scn.  An even better idea is to issue

      nice ssmlmnp myfile >& myfile.scn &

    which will run the job at a "nice" priority depending on the usage of
    the machine you are employing.

3.  Notes on the profile file:
    ** PAUSE [SEC]: number of seconds to wait between screens; if
    non-interactive, set to -1

    ** SPOOL FILE : name of output file

    ** DATA FILE  : name of data file.  See the file HLOGIT.DOC
    for a detailed explanation as to how the data should be
    organized.  In summary, the first line should state in parentheses
    a FORTRAN statement to read one complete observation on all
    variables.  The NX data for the variables that vary across
    alternatives (X variables -- see below) should appear first,
    followed by the value for the dependent variable, plus the NY
    values of the Y variables that do not vary across alternatives.
    Example 1:
    ---------
    NALT=3, NX=0, NY=4, first 9 observations
(5g13.6)
 3.00000     0.000000     0.000000      1.00000      47.0000
 1.00000      1.00000     0.000000      1.00000      48.0000
 3.00000     0.000000     0.000000      1.00000      49.0000
 1.00000      1.00000     0.000000      1.00000      50.0000
 3.00000     0.000000     0.000000      1.00000      47.0000
 1.00000      1.00000     0.000000      1.00000      48.0000
 3.00000     0.000000     0.000000      1.00000      49.0000
 1.00000      1.00000     0.000000      1.00000      50.0000
 3.00000     0.000000     0.000000      1.00000      49.0000
 1.00000      1.00000     0.000000      1.00000      50.0000
    Example 2:
    ---------
    NALT=3, NX=2, NY=3, first 9 observations
(8g8.4)
  0.2342  5.0000  3.0000  0.0000  0.0000  1.0000  47.0000
  1.0000  5.2222
  2.1111  5.4444
  3.2222  7.6666  1.0000  1.0000  0.0000  1.0000  48.0000
  2.3333  7.3333
  1.4444  7.0000
  4.5555  2.2222  3.0000  0.0000  0.0000  1.0000  49.0000
  5.1111  2.0000
  6.2222  2.3333

  ** OUTPARMS FILE : output file with results saved as possible
  inputs in future runs

  ** INITIAL ESTIMATION parameters:
     ** DERIVATIVE CHECK OF OMEGA MATRIX (0=NO, 1=YES) **
     ** METHOD:(0=NONE,1=LOGIT,2=CLARK)
        Checks of Derivatives: (0=NONE,1=LIK,2=YES)
        ITER : Maximum number of iterations
        ACCU : Convergence accuracy
        IALG : Algorithm to use: (2=DFP,4=BHHH)

  ** SML ESTIMATION parameters:
     ** NSIMUL : number of simulations
     ** ISEED  : starting seed for random number generator
     ** Derivative check: (0=NONE,1=LIK,2=YES)
     ** ITER   : maximum number of iterations
     ** ACCU   : convergence accuracy
     ** IALG   : Algorithm to use: (2=DFP,4=BHHH)

  ** COVARIANCE CORRECTION:
     ** RECOMPUTATION OF ROBUST COVARIANCE: 0=NO, 1=YES/OLD H, 2=YES/NEW H
     Let "OLD_H" = Hessian already calculated by optimization
                   algorithm.  This may be far from the Hessian
                   evaluated at the latest parameter values, because
                   algorithms like DFP recalculate the Hessian only
                   every several iterations, using rough
                   approximations in-between.
     Let "NEW_H" = Hessian reevaluated at the latest parameter values.
     Let "OFP_H" = BHHH approximation of Hessian based on Outer
                   Product of First Partial derivatives.
     Then the final variance-covariance matrix will be based on:
     0 = -inv(OLD_H)
     1 = inv{ OFP_H * inv(-OLD_H) * OFP_H }
     2 = inv{ OFP_H * inv(-NEW_H) * OFP_H }

  ** DIMENSIONS:
     ** NINDIV : number of individuals
     ** NALT   : number of discrete alternatives
     ** NPER   : number of time periods per individual
                 NB:  Note that this implies that your panel data set
                 --   must be a BALANCED one, i.e., it must have the
                      same number of time periods per individual.
     ** RAN/NO_RAN : 1=random effects present, 0=no random effects
     ** AR1/NO_AR1 : 1=AR1 present, 0=no AR1
     ** MNP/IIA    : 1=MNP, 0="IIA"

  ** INITIALVALUES:
      1) NX               X-VARIABLES
      2) NY*(NALT-1)      Y-VARIABLES
      3) NALT-1           CONSTANTS
      4) NALT             STANDARD DEVIATIONS OF UNOBSERVED UTIL'S
      5) NALT*(NALT-1)/2  CORRELATIONS OF UNOBSERVED UTIL'S
      6) NALT             STANDARD DEVIATIONS OF RANDOM EFFECTS
      7) NALT*(NALT-1)/2  CORRELATIONS OF RANDOM EFFECTS
      8) NALT             AUTOCORRELATIONS

      See Boersch-Supan, Hajivassiliou, Kotlikoff, and Morris 1992,
      "Health, Children, and Elderly Living Arrangements:  A
      Multiperiod Model with Unobserved Heterogeneity and
      Autocorrelated Errors " in D. Wise, ed., "Topics in the
      Economics of Aging," Chicago, University of Chicago Press,
      for a discussion of necessary identification assumptions.

      NB:  The program WILL NOT impose automatically any restrictions
           necessary to achieve identification.  It is your
           responsibility to impose such restrictions by enough
           "DO=0" values -- see below.

Example:
-------

DO=1 means "estimate parameter with PARVAL as starting value"
DO=0 means "hold parameter fixed during estimation at PARVAL value"

PARNAM..DO..PARVAL......
12345678..123456789012345
--------==---------------
PREMV1   1  23.4164
PREMV2   1  23.2921
LFS1     1   0.3107
LFS2     1   0.2940
ONE1     1  -0.5455
ONE2     1  -0.1827
sd-nu1   1   1.8197
sd-nu2   1   0.4088
sd-nu3   0   1.0000
co-nu1   1  -0.8801
co-nu2   1   0.2698
co-nu3   1   0.7702
sd-alfa1 1   0.7026
sd-alfa2 1   0.5484
sd-alfa3 0   0.0000
co-alfa1 1   0.0000
co-alfa2 1   0.0000
co-alfa3 1   0.0000
rho1     1   0.0000
rho2     1   0.0000
rho3     1   0.0000


************************************************************************
sample ssmlmnp.pro file
************************************************************************

**************** PROGRAM MODE: ************************************************
** PAUSE [SEC]: if non-interactive, set to -1 **
   -1
** SPOOL FILE **
   ssmlmnp.spo
** DATA FILE **
   ssmlmnp.dat
** OUTPARMS FILE **
   ssmlmnp.out
**************** INITIAL ESTIMATION: *******************************************
** DERIVATIVE CHECK OF OMEGA MATRIX (0=NO, 1=YES) **
   0
** METHOD                    D-CHECK                ITER   ACCU   IALG
   (0=NONE,1=LOGIT,2=CLARK)  (0=NONE,1=LIK,2=YES)                 (2=DFP,4=BHHH)
   0                         0                      100    .00001   2
**************** SML ESTIMATION: ***********************************************
** NSIMUL      ISEED         D-CHECK                ITER   ACCU   IALG
                             (0=NONE,1=LIK,2=YES)                 (2=DFP,4=BHHH)

   100          1234567       0                      100    .00001   2
**************** COVARIANCE CORRECTION: ****************************************
** RECOMPUTATION OF ROBUST COVARIANCE (0=NO, 1=YES/OLD HESS, 2=YES/NEW HESS) **
   2
**************** DIMENSIONS: **************************************************
** NINDIV **
   81
** NALT  NX  NY  CONST  WEIGHT **
   3     0   4   1      0
** NPER  RAN/NO_RAN  AR1/NO_AR1  MNP/IIA  (1/0) **
   10    1           1           1
**************** INITIALVALUES: ************************************************
1) NX               X-VARIABLES
2) NY*(NALT-1)      Y-VARIABLES
3) NALT-1           CONSTANTS
4) NALT             STANDARD DEVIATIONS OF UNOBSERVED UTIL'S
5) NALT*(NALT-1)/2  CORRELATIONS OF UNOBSERVED UTIL'S
6) NALT             STANDARD DEVIATIONS OF RANDOM EFFECTS
7) NALT*(NALT-1)/2  CORRELATIONS OF RANDOM EFFECTS
8) NALT             AUTOCORRELATIONS
--------------------------------------------------------------------------------
PARNAM..DO..PARVAL......
12345678..123456789012345
--------==---------------
PREMV1   1  23.4164
PREMV2   1  23.2921
PREOWN1  1   1.7004
PREOWN2  1   0.9207
LFS1     1   0.3107
LFS2     1   0.2940
HAGE1    1   0.0400
HAGE2    1  -0.0293
ONE1     1  -0.5455
ONE2     1  -0.1827
sd-nu1   1   1.8197
sd-nu2   0   1.0000
sd-nu3   0   1.0000
co-nu1   1  -0.8801
co-nu2   0   0.0000
co-nu3   0   0.0000
sd-alfa1 1   0.7026
sd-alfa2 1   0.5484
sd-alfa3 0   0.0000
co-alfa1 1   0.0000
co-alfa2 1   0.0000
co-alfa3 1   0.0000
rho1     1   0.0000
rho2     1   0.0000
rho3     1   0.0000
