Updated 16 May 2006 -- a work in progress!

                        The GRBL2 Package Of Econometric Models
Abstract:

   GRBL2 is a freeware package of econometric models and data manipulation programs.
   Writtein in GAUSS, these include program to estimate COUNT models,  estimat DISCRETE choice models,
   create and manipulate data, and much more.

Contents:

  I. Introduction
  Ia. Installing
  Ib. Using GRBL2 programs
  Ic. Using the GRBL2 control program
  II. GRBL2 Command files
  III. More documentation
  IV. Contact Information

      =================================================


I. Introduction

  GRBL2 is a collection of several GAUSS programs. These include:

    * COUNT.GCG    : Several Poisson and negative binomial count models
    * REG.GCG      : Several linear regression models (OLS, TOBIT, FE Panel,...)
    * CVM.GCG      : Several dichotoumos choice estimators, and robust computation of CVM
    * DISCRETE.GCG : a variety of MNL and single/double bounded models
    * EDITDATA.GCG : View the contents of a GAUSS dataset
    * MAKEDATA.GCG : Create  & modify GAUSS datasets
    * SNP.GCG      : Several semi-non-parametric estimators and CVM estimators
    * STATS.GCG    : Compute a variety of statitics

  GRBL2 also contains several sets of useful procedures that ambitious GAUSS programmers can use to
  implement their own models. These a complete maximum likelihood estimation procedure, a wide variety
  of I/O routines, and a number of data manipulation and math procedures.

  Since GRBL2 is an active work in progress, you should periodically check for the latest version.
  You can find the latest version at http://grbl.danielh.org/grbl2/

  To run these programs, you need to have either:
     * GAUSS 5.0 or above
     * or, a copy of the (free) Gauss 5.0 run time module.

  If you don't have GAUSS 5.0, you can obtain the GAUSs 5.0 run time module freely
  (http://grbl.danielh.org/grbl2/).



Ia. Installing

GRBL2_xxx.ZIP (where the xxx is a version number) contains the GRBL2 programs and source code.

Note that the GAUSS 5.0 runtime module is distributed seperately (in GSRUN5.ZIP).


To install:

* Create a x:\GRBL2 directory (where x: is one of your hard drives)

* Copy GRBL2_xxx.ZIP to this directory.

* UNZIP it. Make sure that subdirectories are created!

  If you need a copy of UNZIP; you can find one at the above web site.

* Run GAUSS version 5.0.

   If you don't have GAUSS 5.0, you can use the GAUSS 5.0 run time module. To install
   the runtime module:

     * Create a GSRUN50 subdirectory under x:\GRBL2
     * Copy GSRUN5.ZIP to this directory, and then unzip it.


* From GAUSS, run one of the several "compiled" GRBL2 programs (that are located in the
  x:\GRBL2 directory); all of them have a .GCG extension.

  For example, to create GAUSS dataset from a text file, from the >> GAUSS prompt you would:
     >>run x:\grbl2\MAKEDATA.GCG.

  As a convenience, you can use the GRBL2.GCG "control program" to launch any of the several
  programs that comprise the GRBL2 package -- see below for the details.

    This adds no functionality, but it can be helpful if you are running several
    different programs sequentially (saves you the trouble of telling gauss which .GCG
    file to run).

  Note: to use GRBL2.GCG, you MUST have installed the GAUSS run-time module somewhere
  on your computer, preferably in the GSRUN50 subdirectory of x:\GRBL2.



Ib. Using GRBL2 programs

  Note that for reasons historical and aesthetic, the GRBL2 programs run in GAUSS's DOS window.
  THis is a simple, 23x80 character window that will open up in the upper right corner of your
  monitor.

  It's a bit clunky, but it permits the use of colors and other simple formatting of
  output.

When you first start one of the GRBL2 programs, it will display an intro screen (in the DOS window)
that lists several options. Each program is a bit different, but in general the intro screen
will look something like this:

    a) FILE : Browse directory for a commands file
       PRIOR : Use file.in  (most recently specified command file)
    b) BATCH    : Enter commands from the keyboard
    c) VU            : View the current output file
       VU Prior      : Vu file.ext   (recent input file)
       VU file.ext   : View file.ext (recent output file)

    d) HELP          : view documentation file
    e) SEE           : view contents of a GAUSS data file
       SEE *         : view contents of file.dat GAUSS data file (recent GAUSS data file)
    f) EXIT          : exit

The first option, FILE, is the most important -- it is used to tell the program what "command file" to use.

These "command files" are how you communicate with GRBL2 programs.
They are used to specify input files, models, variables, etc.  They are described in the next setion.

The PRIOR option is a shortcut: it is used to select the most recently used
"commands file". This is a very convenient shortcut -- you can run a model,
tweak the command file, and run it again without having to re-enter the name of
the command file.


Ic. Using the GRBL2 control program


  As a convenience, you can use the GRBL2.GCG "control program" to launch any of the several
  programs that comprise the GRBL2 package. GRBL2.GCG adds no functionality, but it can be helpful
  if you are running several  different programs sequentially.

     To use GRBL2.GCG, you MUST have installed the GAUSS run-time module somewhere
     on your computer, preferably in the GSRUN50 subdirectory of x:\GRBL2. That is,
     even if you own a copy of GAUSS, to use GRBL2.GCG you MUST have the run-time
     module installed!

  One of the primary advantages of using the GRBL2.GCG "control program" is the ability
  to use GRBL2 "scripts" to run programs sequestially. For example, you might want
  to run MAKEDATA first (to create a  GAUSS dataset), then REG (to do a linear regression),
  and then DISCRETE (for logit model).  With a script file, you can do this at one shot,
  you don't have to hang around waiting for each program to finish.

  To do this, simply select the SCRIPT option in GRBL2, and provide the name of
  GRBL2 "script file" that you have created.

  GRBL2 script files are simple "mime-like" text files that tell GRBL2.GCG what programs to
  run, and what program-specific command file the program should use.

  Each line of a script file should have the following syntax:

      progname:  filename , arg1 , arg2 ,...

  where
      progname: One of the GRBL2 programs (sucha s DISCRETE, or MAKEDATA)
      filename: the name of a GRBL2 command file, containing commands for the program you
                 specified
      argn : up to 10 arguments (seprated by commas). These will be inserted into the
             filename file (as specified below)

   Note that, as with GRBL2 command files, @s are used for comments.

   Also, progname can have two additional values (other then the GRBL2 programs):
       WORK_DIR  : Set the working directory
       COMMENT: Write a comment to the GRBL2 window.

   Example:
      @ a sample grbl2 script file @
      work_dir: e:\projects\mywork
      makedata: test1.in
      comment: Now do regressions....
      Reg: test1b.in , Regressions using mywork directory

   Hint:
      It is possible to use the same command file for each of your programs!
      This is done by judicious use of the $PROGRAM "GRBL2 variable" in IF statements.
      Basically, you can tell each GRBL2 program to only execute a subset of the
      commands in a command file.

     Example:
        If $PROGRAM ne MAKEDATA goto step2 ;
        step1: ;
           MODEL CREATE ;
                 ..
           RUN ;
        step2: ;
        if $PROGRAM ne COUNT goto step3 ;
            Model count ;
               ...
            run ;
        step3: ;
        etc.

     Note that the $PROGRAM variable is  compared (using NE, or EQ) to the actual name of the program --
     such as MAKEDATA, COUNT, REG, DISCRETE, and STATS.

     Hint:
        GRBL2 will write errors to the GRBL2.ERR file (in you GAUSS 5.0 runtime directory).
        You can use the ERROR option, in GRBL2.GCG, to view these errors.



      =================================================

II. GRBL2 Command files

Although a few of the GRBL2 programs have an extensive keyboard interface (CVM), in general to
tell a GRBL2 program what to do, you (the user) must write a "command file".

Commands, that are included in a "GRLB2 comamnd file", take the form:
   keyword modifer1 [modifer2 ...modifiern] ;
where
   keyword : the type of action.
   modifier1 through modifiern : a set of modifiers for the keyword,
             (the number of modifiers depends on the keyword)
   ;        : each command should end with a semi-colon.

Notes

   * Spaces, commas, and new lines are treated as word seperators,
     and semi-colons as command seperators.
     Thus:
        you can  have several commands per line, or a command
        instruction can span multiple lines.
   * keywords and modifiers are case insensitive
   * you can include comments in the file by enclosing them (in the
     usual GAUSS fashion) between @s.

Each program understands its own set of keywords. These include keywords
specific to the program, and  keywords that are understood by all the GRBL2 programs.

These "generic" keywords include:

 Keyword    Example
--------------------------------------------------
  X         X PRICE INCOME AGE ;
  Y         Y TRIPS ;
  BSTART           BStart  NO ; BStart YES -1 100 32 ;
  COMMENT          COMMENT This comment line will be printed ;
  DEFINE           DEFINE BaseT The ultimate analysis ;
  FILE             FILE  recnat4s ;
  GOSUB            GOSUB  BLOCK1 AB ,CD EF ;
  GOTO             GOTO FOO1  ; ..... ; FOO1:  ... ;
  IF and #IF       IF  $A = B then xxx ; IF A = B goto step1 ;
                   #IF A > 3 goto biga ;
  OUTPUT           OUTPUT recnat4s.out -overwrite ;
  QUIT             QUIT ;
  PAUSE            PAUSE 10 Hit X to exit ;
  RUN              RUN ;
  STARTBLOCK       STARTBLOCK BLOCK1 ; .... ; ENDBLOCK
  SELECT           SELECT  or q2 eq 2 , or q2 eq 1 ;
  STOP             STOP
  TITLE            TITLE The Main Model ;  TITLE $BaseT; using respondents only ;

Several of these keywords allow you to implement a fairly complex logical flow, with
keyphrase processing subject to IF conditions, and to user input.  Others are used
to select input files, independent variables, etc.

The GRBL2_BATCH.TXT describes the generic keywords (such as IF) in great details.
To reiterate, the documentation for each program describes what keywords are used
(for that program).

      =================================================



III. More documentation

The following documentation you may find useful:

   * CVM.TXT        -- Brief, and outdated, description of the CVM program.

   * DISCRETE.TXT   -- The manual for the DISCRETE program.
   * REG.TXT        -- The manual for the REG program.
   * DOUBLE.PDF     --  A complete description of DISCRETE's single and double bounded dichotomous
                        choice estimators. As MIXED.PDF, DOUBLE.PDF is easier to read, but less
                   extensive, than DISCTETE.TXT.


   * GRBL2_BATCH.TXT -- Describes the bells and whistles of "GRBL2" input files.
         Most of these progams use GRBL2 input files to specify models,
                        variables, etc.  You can do a lot in these input files (such as IF and
                        GOTO statements).

   * MIXED.PDF      -- A complete description of DISCRETE's mixed logit model; describing the
                       many variants supported, and how to run them.  MIXED.PDF is not as complete
             DISCRETE.TXT (some of the minor options are not explained), but it should be
             a lot easier to read.

   * MAKEDATA.TXT   -- Description of the MAKEDATA program.

   * SNP.TXT        -- Descrription of the SNP program (not very detailed)
              For a detailed description of the SNP models, see:
              Joseph Cooper.  "Nonparametric and Semi-Nonparametric Discrete
              Choice Methods," Chapter in "The Handbook of Contingent Valuation",
              J. Kahn, D. Bjornstad, and A. Alberini (Eds.), forthcoming, 2000.
              Edgar Elgar, London.

   * STATS.TXT      -- Description of the STATS program

  BTW: MIXED.DOC and DOUBLE.DOC, in the SOURCE\DISCRETE directory,
       are MS word versions of the above PDF files.



     ===================================================================

IV. Contact Information

Having troubles getting DISCRETE to run?  Have a few suggestions? You
can contact the author (Daniel Hellerstein) at 202 694-5613, or
via E-mail at danielh@ers.usda.gov or danielh@crosslink.net
