IRAP Readme File

; ---------------------------------------------------------------------------
; Contents window
; ---------------------------------------------------------------------------

Help Contents

This is a list of topics covered by the Help system.
To view a topic, select its heading below.


      [..Data files]

         [..File variables]
         [..Defined Variables]

         [..Convergence Criteria]

      The File Menu
         [..New library]
         [..Open library]

         [..Save library]

      The Variables Menu


      The Model Menu
         [..Define model]

         [..Sampling scheme]
         [..Convergence criteria]

      The Options Menu
         [..Variable columns]

         [..Automatic tiling]
         [..Save configuration]


; ---------------------------------------------------------------------------

IRAP is an interactive computer program which calculates both point estimates and
confidence intervals for attributable risk, based on regression models.  Modeling
consists of three conceptual phases: creating a library of variables, defining the
model, and running the model.

IRAP keeps a "library" of variables which the user has defined.  A variable can take its
value directly from the data file, or it can be defined in terms of other variables in the
library.  Typically, the user will create a separate library for each data file that he
or she uses.  A library can be saved to disk, then loaded whenever the corresponding data
file is used.

Once a library of variables has been created (or loaded from disk), the user may define a
model.  IRAP supports six data sampling methods:

       *     Simple Random Sampling
       *     Stratified Random Sampling
       *     Frequency Matching
       *     Individual Matching
       *     Cohort Analysis
       *     Cross-Sectional Analysis

After choosing the appropriate sampling method, the user defines a model by
specifying the appropriate variable names.  A model can contain both discrete and
continuous variables.  IRAP correctly parameterizes the discrete variables, so the
user need not explicitly create "dummy variables."

Once the model has been specified, the user tells IRAP to fit the model.  The program
asks for the names of the input and output files.  It then reads the data, and fits the

While these three phases are conceptually distinct, they can be interleaved.  For
example, after fitting a model, the user may decide to combine two levels of exposure into
one.  It is easy to define a new variable, then rerun the model, substituting the new
exposure variable for the old.
; ---------------------------------------------------------------------------
; DataFiles
; ---------------------------------------------------------------------------


Data Files
The data files used by IRAP are very simple: they are standard text files (i.e., "ASCII"
or "flat" files, not word processor files), with one line per record.  The lines are
"column-delimited."  That is, a variable is defined by the value occupying a given range
of columns in the file.  Each line is considered a separate record.  Leading and
trailing blanks are allowed.  Thus, a small data file such as


contains three records.  Assuming that each variable in this particular file occupies
exactly one column, it contains separate variables.  The variable in column 1 would be
missing for the first record.

Records do not need to be sorted, and they may contain missing data.  If a record
contains a missing value for a variable which is actually used in the model, then it will
not be used for fitting the model.  In the above example, a model which uses the
variable in column 1 would only use two records; models which do not use that
variable will use all three.  A "missing value" is anything that cannot be interpreted
as a number, for example, a blank field or a letter.  A field may contain leading and
trailing blanks, so long as it has a real value in it somewhere.  There is no upper
limit on the length of a record.  Most types of model require individual data.  The
exception is the cohort model, which takes data in the form of a person-year table.
; ---------------------------------------------------------------------------
; Variables
; ---------------------------------------------------------------------------

Although the data file is laid out in columns, IRAP's models are defined in terms
of named variables.  IRAP maintains a list of variables that may be used in the model,
called the "library."  Variables can be added to or deleted from the library, and the
entire library may be saved to disk for future reference.  Typically, an entire file
specification will be saved as a library. Then, that library will be loaded at the
beginning of a session, and used to define models.

There are two types of variable:  the "file variable" and the "defined variable."  A file
variable takes its values directly from the data file; a defined variable is a function
of any number of file variables.  Each variable has three attributes:  its name, its
number (that is, its position in the library), and optionally, a "missing code."
In addition, file variables must include a starting column and field length, and may
also specify an implicit decimal point's position.  Defined variables replace these
attributes with a definition.

IRAP's variable names are much like those in many programming and statistical languages.
They may consist of letters, numbers, and underscores ('_'), but may not begin with a
number.  Variable names are "case insensitive."  That is, uppercase and
lowercase letters are interchangeable. Although IRAP variable names can use mixed
case for readability (for example, "Age" or "GroupedWeight"), case alone does not
distinguish two different variables (for example, "AGE" and "age" both refer to the
same variable).  In certain contexts, a variable can be specified either by name or
by number.  However, the number is merely the variable's current position in the
library:  if a variable is added or removed, then the numbers of all the variables after
it will be shifted.

Both file variables and defined variables can have a "missing code."  This is a value
which, when encountered, is converted to an internal "missing" value, as if the field in
the data file were blank.  Consider a variable called "AGE," with values 0, 1, 2,
and 3.  Many files may contain a "9" for subjects whose age is unknown.  Declaring 9
to be the "missing code" for AGE will cause those subjects to be excluded from any
analysis involving the AGE variable. The function of a missing code in defined
variables is a bit more subtle.  As would be expected, a defined variable is automatically
considered missing if it depends on any missing variables.  Using the "AGE" variable
as above, the defined variable

              AGEp1 = AGE + 1

will assume the values 1, 2, 3, and 4.  No missing code is needed for AGEp1, because
AGE's missing status (whether due to a blank or a "9" in the data file) is propagated
through the definition.

Although IRAP only allows one missing code per variable, a defined variable with a
missing code can be used to account for several different missing codes in the file.
Consider the file variable RACE:

             RACE          Meaning
             1             white
             2             black
             3             other
             4             refused to answer
             5             misc. unknown

For most analyses, both 4 and 5 should be considered "missing," but IRAP only allows
one missing code.  A workaround is to define RACE_1, with missing code 4, as follows:

             RACE_1 = RACE * (RACE <= 3)
                      + 4 * (RACE > 3)

When RACE is 1, 2, or 3, the expression will be evaluated as

             RACE_1 = RACE * (1) + 4 * (0)
                    = RACE

but when RACE is 4 or 5,

             RACE_1 = RACE * (0) + 4 * (1)
                    = 4

which is its missing code.  There is nothing magic about which number is used as the
missing code--it must only be outside of the variable's normal range.  In the above
example, 5, 6, -1 or 99 could just as easily have been used as a missing code (with the
corresponding change in the definition).
; ---------------------------------------------------------------------------
; FileVars
; ---------------------------------------------------------------------------


File Variables
IRAP's data files are column-delimited:  file variables are specified in terms of starting
column and field length.  Often, the decimal point is omitted from column-delimited data;
because it occurs in the same place in all records, its position can be inferred.  This
situation is handled by the "precision" attribute of file variables.  A variable with
two implied decimal places (e.g., 1.23 represented as "123") has a precision of 2.
An explicit decimal in the data will override the implied decimal, so "12." will always be
interpreted as 12, not as 0.12 or 1.2.

Please note that leading and trailing spaces can present some odd results if values are
not lined up consistently in their fields. Consider the file:

             8 209
             820 9

The variable "a" starts at column 2, has length 3, and precision 2.  Leading and
trailing blanks are ignored, so the records are interpreted as follows:

             data          a
             100           1.00
             101           1.01
              20           0.20
             20            0.20

This situation occurs rarely, if ever, because data represented with implicit
decimal places are usually right-justified in the field.
; ---------------------------------------------------------------------------
; DefinedVars
; ---------------------------------------------------------------------------

Defined Variables
Like its naming rules, IRAP's variable definition language borrows from more general
languages.  It combines arithmetic and boolean operators, assigning precedence
levels which naturally group expressions as would normally be expected.  Parentheses may
be used to override the default operator precedence, or simply for clarity.  The
operators are as follows, in order of descending precedence:

       ( )                              grouping
       - (unary minus)
       * /                              arithmetic
       + -
       < <= > >= == !=
       &&                               boolean
       @saturate(...)                   combination

The first line of boolean operators contains the relational operators, "less than" (<),
"less or equal" (<=), "greater than" (>), "greater or equal" (>=), "equals" (==), and
"not equal" (!=).  Below them are the "and" (&&) and "or" (||) operators.

As IRAP only handles real numbers, the boolean operators bear some explanation  Any
boolean expression will evaluate to 1 if true, or 0 if false.  The operands of a
boolean operator may have any value; zero is interpreted as false, nonzero as true.  Thus,

    expression            result

    1 < 2                 1
    2 < 2                 0
    2 <= 2                1
    4.98 && -3            1
    0 && 3.14             0
    2 || 3.14 && 0        1 (&& is evaluated first)
    (2 || 3.14) && 0      0 (explicit grouping)

The operators may be mixed freely, with the exception of the "@saturate()" operator,
which may not be part of a larger expression. This operator creates a "saturation
variable," which is a variable with a unique value for each observed combination of its
operands' values.  The syntax is:

       @saturate(var1, var2, ...)

One or more variables may be listed, separated by commas.  Given variables var1
(1..2) and var2 (0..1), a saturation variable will have the following values:

       @saturate(var1, var2)     var1   var2
       0                         1      0
       1                         1      1
       2                         2      0
       3                         2      1

Note that the baseline level of the saturation variable represents the lowest
observed value of all the component variables.  The saturation operator is
offered primarily as a convenient way to create saturated models.  The above example
could be modeled with three effects: var1, var2, and an interaction term.  However, in
models with more variables, it becomes more convenient to define a saturation variable
than to explicitly model many interaction terms.  Another use for the saturation
operator involves the trivial case, "@saturate(var1)".  No matter what values
var1 assumes, the operator will map them to integers (0, 1, ...).  This matter will be
discussed more in the next section.

; ---------------------------------------------------------------------------
; Models
; ---------------------------------------------------------------------------
IRAP supports six data sampling methods, based on three types of regression model.
Simple and stratified random sampling, frequency matched, and cross-sectional data
fit a logistic model; individual-matched data fits a conditional logistic model; and cohort
data fits a Poisson model.  All models except for the conditional logistic model may be fit
either with or without an intercept parameter, and stratified models may include
or exclude parameters representing the stratification variables.
; ---------------------------------------------------------------------------
; Parameters
; ---------------------------------------------------------------------------

The model makes a syntactic distinction between discrete and continuous variables.  A
discrete variable with n levels is automatically modeled as n-1 0/1 parameters,
using the variable's minimum value as the baseline.  A continuous variable, marked by a
"#" in the model definition, is modeled as a single parameter, whose values reflect the
data literally.  Continuous variables are assumed to have a baseline value of 0.

Discrete variables are assumed to take on consecutive integer values; fractions are
rounded down.  While this rule causes no problems in most cases, variables that have
non-integer values, or whose values are not consecutive integers, cause problems.
Consider the variable "fat," which has the following values:


If fat really is a discrete variable, then it should be modeled with four parameters:
"fat=2," "fat=4.1," "fat=4.2," and "fat=4.3." However, IRAP rounds the highest three values
to 4, so it is interpreted as follows:

      fat           IRAP interpretation
      1             1
      2             2
      4.1           4
      4.2           4
      4.3           4

Now, seeing that "fat" has a minimum value of 1, and a maximum value of 4, IRAP creates
three model parameters: "fat=2," "fat=3," and "fat=4."  Thus, the model would look
something like this:

      fat           fat=2        fat=3         fat=4
      1             0            0             0
      2             1            0             0
      4.1           0            0             1
      4.2           0            0             1
      4.3           0            0             1

Three levels of the variable have been collapsed into the "fat=4" parameter, while
the "fat=3" parameter has no use at all.

The solution to this problem is to define a new variable as "satfat = @saturate(fat)."
The new variable will be defined as follows:

      satfat               fat
      0                    1
      1                    2
      2                    4.1
      3                    4.2
      4                    4.3

This variable will be modeled correctly, contributing four meaningful parameters to
the model:

   Variables                         Parameters
   fat    satfat   satfat=1  satfat=2 satfat=3  satfat=4
   1      0        0         0        0         0
   2      1        1         0        0         0
   4.1    2        0         1        0         0
   4.2    3        0         0        1         0
   4.3    4        0         0        0         1

IRAP automates the modeling of interactions in much the same way as with main effects.
An interaction is expressed as the product of two or more variables, such as:

             sex * age


             sex * age * race.

An interaction can contain any combination of discrete and continuous terms.  Continuous
variables are marked with a number sign:

             sex * #ContAge.

Discrete terms are parameterized automatically.  An interaction of discrete
variables results in one model parameter representing each combination of non-baseline
levels of the component variables.  Thus, an interaction of any number of binary variables
will result in a single model parameter, which is 1 when all of the interaction terms
are "exposed."  Consider the following examples:

       Variable     Values
       age          1, 2, 3
       sex          1, 2
       exposed      1, 2

       a)    sex * exposed

             Values               Model Parameters
             sex    exposed       (sex=2)*(exposed=2)
             1      1             0
             1      2             0
             2      1             0
             2      2             1

       b)    age * sex

             Values         Model Parameters
             age    sex     (age=2)*(sex=2) (age=3)*(sex=2)
             1      1       0                 0
             1      2       0                 0
             2      1       0                 0
             2      2       1                 0
             3      1       0                 0
             3      2       0                 1

Continuous terms are treated literally, as demonstrated below:

       Variable     Values
       ContAge      10, 25, 50
       ContWgt      120, 155
       age          1, 2, 3

       a)    #ContAge * #ContWgt

       Values                     Model Parameters
       ContAge ContWgt            ContAge*ContWgt
       10      120                1200
       10      155                1550
       25      120                3000
       25      155                3875
       50      120                6000
       50      155                7750

       b)    #ContWgt * age

       Values        Model Parameters
       ContWgt age   ContWgt*(age=2) ContWgt*(age=3)
       120     1     0                0
       120     2     120              0
       120     3     0                120
       155     1     0                0
       155     2     155              0
       155     3     0                155
; ---------------------------------------------------------------------------
; Effects
; ---------------------------------------------------------------------------
The variables that contribute to a model are grouped by function into lists of "effects."
Some lists are common to all models, while others, such as "case indicator," are
specific to certain types of model. Similarly, some lists may contain many
variables, while others are limited to one. The following types of model effect occur in
all models:

       *     Exposures - Each model must have one or more exposure variables.
             These are the variables used to determine exposure level in
             calculating attributable risk.

       *     Confounders - Optional.  These variables do not contribute to the
             attributable risk, but are modeled in the regression.

       *     By-variables - Optional.  Separate analyses are performed for each
             combination of values for these variables.

       *     Interactions - Optional.  This is a special type of effect that allows
             interactions to be modeled without resorting to huge lists of defined
             variables.  An interaction can contain any combination of discrete
             and continuous variables, and as with main effects, discrete
             variables are automatically parameterized.  To correctly
             calculate attributable risk, IRAP automatically treats any
             interactions involving an exposure variable as exposures as well.

In addition to these effects, each type of model also has other, required, effects, as
listed below.

Simple Random Sampling, Cross-sectional:

       *     Case indicator - A model must have exactly one case indicator.  This
             variable must be a file variable.
             0 represents a control; other (non-missing) values indicate a case.

Stratified Random Sampling, Frequency Matching:

       *     Case indicator - A model must have exactly one case indicator.  This
             variable must be a file variable.
             0 represents a control; other (non-missing) values indicate a case.

       *     Stratifiers - The model may be stratified by one or more discrete
             variables.  The "Stratifiers Modeled" checkbox indicates whether
             these will also be included as covariates in the regression, or
             merely used for stratifying the attributable risk.

1:Ki Individual Matching:

       *     Case indicator - A model must have exactly one case indicator.  This
             variable must be a file variable.
             0 represents a control; other (non-missing) values indicate a case.

       *     Set number - This variable tells which matched set each individual
             belongs to.  The specific values are arbitrary, but must be the same
             for each member of a given matched set.

Cohort Analysis:

       *     Event count - The number of events that occured in the specific cell.

       *     Person-years - The number of person-years in the specific cell.

       All types of model except for "1:Ki individual matching" allow an "Include
Intercept" option.  By default, an intercept parameter will be included in the regression
model.  However, you may choose instead to use one of the model's discrete variables to
span the intercept.  In this case, the baseline level of one variable will also be
represented by a parameter in the model. This variable is chosen automatically.  The
first discrete confounder, if it exists, is used.  Otherwise, the first discrete exposure
variable is used.  However, the baseline parameter never contributes to the
attributable risk estimate.

A similar option exists for modeling stratifiers.  By default, stratifier
variables are modeled as discrete covariates. If you disable this option, they will not be
modeled, but will still define the strata in the attributable risk analysis.

; ---------------------------------------------------------------------------
; ConvCriteria
; ---------------------------------------------------------------------------

Convergence Criteria
The final set of modeling options offered by IRAP adjusts how the model is fit, not the
model's contents per se.  IRAP allows you to tune three parameters:  maximum iterations,
convergence tolerance, and singularity threshold.  The maximum iterations parameter
(default, 30) adjusts how long the regression is allowed to run before the model is deemed
divergent.  The convergence tolerance (default, 1x10**-8) is used to test for
convergence in the regression.  The singularity threshold (default, 1x10**-12)
tests for information matrix singularity. While these defaults are usually adequate,
you may change them to suit individual needs and tastes.  They are saved as part of the
program configuration, so your settings will be restored every time you start the program.
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------
New library
This command clears the entire library of variables.  Because the model cannot contain
variables which are not defined in the library, the "New library" command has the
side-effect of destroying the model definition.
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------

Open library
Oening a library replaces the current library with one that was previously saved.

The Files window shows the names of files in the current directory.  The Directories
window lists subdirectories, and all of your disk drives.  You will notice that only
filenames ending in ".var" are shown.

>      To change the criterion for displaying
       1. Move to the Filename field.
       2. Type the pattern for files you wish
       to see.
             "*" matches zero or more characters
             "?" matches exactly one character
             "*.*" shows all files.
             "a*.v" shows all files beginning
             with "a", with a ".v" extension.
       3. Click the "OK" button, or press

>      To change disk drive or directory
       1. Click on the Directories window, or press Alt+D.
       2. Double-click on the drive letter or directory name of your choice.  Or, use
       the arrow keys to select your choice, then press RETURN.  Choose ".." to move
       to the parent directory.
       1. Type the name of the directory in the Filename field, followed by a backslash
       2. Press RETURN.

>      To load a file
       1. Move to the Filename field.
       2. Type the name of the file.
       3. Press RETURN.
       1. Select the file in the Files window.
       2. Click the "OK" button.
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------
Save library
Having created a library of variables, you can save it to disk for future reference.  By
building a library that contains all of the variables used in a study, you ensure that
the same variables are used throughout the study, and that they are named consistently.

The "Directories" window contains a list of all the subdirectories of the current
directory, and all of your disk drives.

>      To change disk drive or directory
       1. Click on the Directories window, or press Alt+D.
       2. Double-click on the drive letter or directory name of your choice.  Or, use
       the arrow keys to select your choice, then press RETURN.  Choose ".." to move
       to the parent directory.
       1. Type the name of the directory in the Filename field, followed by a backslash
       2. Press RETURN.

Once the "Directory:" field shows the proper directory, you can save your library by
typing its name.

>      To save the library
       1. Move to the Filename field.
       2. Type the name under which you want to save the library.  If you did not change
       to the desired directory, you may explicitly specify the drive letter,
       directory, or both:
       3. Click the "OK" button, or press RETURN.
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------

When fitting several models at once, it is often convenient to check a report, or copy a
data file without exiting IRAP.  For this reason, IRAP offers a DOS "shell" facility.
By choosing this command, you will start a command prompt while IRAP is still running.
From this prompt, you can do routine chores without having to leave IRAP.  Because IRAP
is still running behind the shell, less memory than normal will be available, but
most programs will not be hindered by this condition.

To return to IRAP, type "exit" at the DOS prompt.  Do not restart IRAP with the "irap"
command; doing so will start another copy of the program, not return you to your previous
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------
This command terminates the program.  The current model definition and library will be
lost.  Of course, you can save the library (see "Save library," above) for use in future
sessions.  At present, there is no way to save a model definition.
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------

Choose this command to add a new variable to the library.  There are two types of
variable:  the "file variable" and the "defined variable."  In short, a file
variable takes its value directly from the data.  Because it is often desirable to
recode data without creating a special data file, IRAP also provides "defined variables,"
which are specified as functions of any number of file variables.

Initially, IRAP presents you with a dialog for adding file variables.

>      To add a file variable
       1. Fill in the Name, Column, and Length fields with the information for this
       variable.  Use TAB or the mouse to move between fields.
       2. If the field in your data contains an implicit decimal point (e.g., 1.5
       represented as "15"), enter the number of decimal places in the "Precision"
       field (in the above example, you would enter "1").
       3. If the data file contains a numeric value which should be interpreted as
       "missing," then enter that value in the "Missing Code" field.  Some files have
       several codes that mean "missing."  To handle this problem, see the "Concepts"
       4. By default, the variable will be added after the last variable in the
       library.  If you want to insert it elsewhere, enter the position in the
       "Number" field.
       5. Click the "Add" button, or press RETURN.

At this point, the dialog box will clear itself, so that you may add another variable.

>      To quit adding variables
       * Click the "End" button, or press ESCAPE.

>      To add a defined variable
       1. From the dialog box described above, click the "Defined Variable" button, or
       press Alt+D.
       2. Fill in the "Name" and "Definition fields.  The variable definition
       language is described in the "Concepts" section.
       3. If you wish to define a missing code for the variable, type it in the
       "Missing Code" field.
       4. By default, the variable will be added after the last variable in the
       library.  If you want to insert it elsewhere, enter the position in the
       "Number" field.
       5. Click the "Add" button, or press RETURN.

Again, the dialog box will ready itself for another variable.  To stop adding variables,
click the "End" button, or press ESCAPE.  IRAP will remember that you were adding
defined variables, and return you to that dialog box the next time you add variables.

>      To return to adding file variables
       * Click the "File Variable" button, or press Alt+F.
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------
Modifying a variable is essentially like adding one.  You will be presented with a
dialog box that is completed with the variable's current specifications.  Simply
make any necessary changes.

>      To modify a variable
       1. You will be asked which variable you want to modify.  Enter the variable's
       name, or its number.  Click the "OK" button, or press RETURN.
       2. A dialog box similar to the "Add Variables" dialog will appear.  Make all
       necessary changes to the information that is displayed.
       3. Click the "Add" button, or press RETURN.
       4. To cancel the operation, clidk the "End" button, or press ESCAPE.
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------

Deleting a variable removes it from both the library and the model.  To delete a variable,
you need only give its name or number.  If it was a part of the model, a message will
appear indicating that the model was changed.
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------
The "New" command clears the entire model definition.  The sampling scheme does not
change, but the "Stratifiers Modeled" and "Intercept Modeled" options (if applicable to
the sampling scheme) are returned to their default values.
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------

Define Model
This command allows you to specify the contents of the model.  It presents a dialog
box with a field for entering each part of the model.  The exact form of the dialog
depends on the current sampling scheme (see the "Sampling scheme" command, below), but
all versions are similar.  When the program starts, the sampling scheme is "Simple

>      To enter a model definition
       1. When the dialog box apears, the cursor will be in the "Case indicator"
       field.  Type the name of the case indicator variable.
       2. Using the mouse, or by pressing Alt+E or TAB, move to the "Exposures" field.
       Type the names of one or more exposure variables, separated by spaces.
       3. If the model includes any covariates which do not contribute to attributable
       risk, move to the "Confounders" field. Type the names of the confounder
       variables, separated by spaces.
       4. If the model should be fit separately for each value of one or more variables,
       move to the "By-variables" field.  Type the variable names, separated by spaces.
       5. IRAP can automatically create interactions involving any number of
       variables.  To specify an interaction, move to the "Interactions" field.  An
       interaction has the form
       Type as many interactions as you wish, separating the terms of each with an
       asterisk ("*"), and separating different interaction with spaces.
       6. IRAP can include a separate parameter to model the intercept, or use a
       covariate in the model to span the intercept.  To span the intercept, clear
       the "Intercept Modeled" checkbox by clicking it with the mouse, or by
       pressing Alt+N.
       7. When done, click the "OK" button, or press RETURN to accept the model.  Click
       the "Cancel" button, or press ESCAPE to cancel the model definition.

Although the other sampling schemes require slightly different information, the form is
the same.

The stratified models (Stratified Random Sampling and Frequency Matching) offer a
checkbox labeled "Stratifiers Modeled."  When this option is checked, the stratification
variables will appear in the regression model as discrete covariates.  Clearing the
checkbox will remove the stratification variables from the regression model, while
retaining the stratification of the attributable risk estimate.
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------
Sampling Scheme
The "Sampling scheme" command offers a submenu listing the six modeling options:

       Simple Random Sampling
       Stratified Random Sampling
       Frequency Matching
       1:k Individual Matching
       Cohort Analysis
       Cross-sectional Analysis

>      To select a sampling scheme
       * Click your choice with the mouse, or use the arrow keys to highlight your
       choice, then press RETURN.
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------

Convergence Criteria
This command is used to tune several parameters used in fitting the model.  These
parameters are saved by the "Save configuration" command in the "Options" menu,
and restored automatically when the program starts.

The first line adjusts the number of iterations allowed before the regression
model is deemed divergent.  The second line adjusts the convergence threshold for the
regression models.  A larger convergence tolerance will cause the model to converge
in fewer iterations.  The third line adjusts the constant used to detect singular information

>      To change a convergence criterion
       1. Move to the field you want to change.
       2. Enter the new value.
       3. Cleck the "OK" button, or press RETURN.

>      To restore the original values
       1. Click the "Defaults" button, or press Alt+D.
       2. Click the "OK" button, or press Alt+O.
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------
Use this command to fit the completed model. When you "run" a model, IRAP first reads the
data into memory.  Little is gained by creating a file that only contains the
variables for a certain model; only the values which are used by the current model
are actually read from the file.  With the data in core, the program builds its
parameter tables, then fits the model.

>      To run the model
       1. In the "Data file" field, type the name of the input file.
       2. In the "Report file" field, type the name under which the model's output
       should be stored.
       3. The report file can have up to two title lines at the top of each page.  To
       specify a title, type its text in the "Title 1" and "Title 2" fields.
       4. IRAP always computes an estimate of attributable risk for all levels of
       exposure combined.  To produce an estimate for each individual exposure
       pattern as well, check the "Partial attributable risk estimates" box by
       clicking it with the mouse, or by pressing Alt+P.
       5. By default, IRAP prints the entire file description at the beginning of its
       report.  To suppress this list, clear the "List variable definitions" checkbox
       by clicking it with the mouse, or by pressing Alt+L.
       6. When all settings are correct, click the "OK" button, or press RETURN.

If you specify a report file which already exists, IRAP offers three options:

       Overwrite (Alt+O)          - Replace the old file with the new one.
       Append (Alt+A)             - Add the report to the end of the old file.
       New name (Alt+N)           - Go back, and enter a new name for the report.
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------

Variable Columns
When the library becomes large, not all of the variables will fit into the "Variables"
window at once.  While you can always scroll through its contents to find a particular
variable, life is easier if you do not need to do so.  For this reason, the library can
be displayed in one, two, three, or five columns, trading the number of variables
displayed against the amount of information shown for each.

>      To select the number of variable columns
       1. The "Variable columns" command will offer a submenu listing the display
       2. Click the option of your choice with the mouse, or type the number of columns
       you wish to see (1, 2, 3, or 5).

In one column, all information is displayed about each variable, but only about 13 or 14
can be seen at once.  A horizontal scroll bar will appear for viewing definitions that do
not fit in one line.  This mode is good for checking long variable names or definitions,
but can be annoying for general use.

The default setting is two columns.  This mode also shows all of the attributes for
file variables, but it truncates variable names longer than nine characters.  For
defined variables, only the beginning of the definition appears, and the missing code is
not shown at all.

In three column mode, the missing codes disappear for file variables, as well.  In
five columns, only the variable names themselves are displayed, but about 65 of
them will fit into the window at once.
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------
Automatic Tiling
Regardless of the variable format chosen, you may want to manually move or resize the
windows, for example to hide part of the model definition in order to see more
variables at once.  Unfortunately, IRAP has its own idea of how the screen should look.
In an effort to be helpful, the program automatically positions the variable window
above the model window, so that the model window is just large enough to show the whole
model, and the variable window gets the rest of the screen.  This feature is called
"automatic tiling," because it places the windows next to each other like tiles on a

>      To turn Automatic tiling on or off
       * choose the "Automatic tiling" command from the Options menu.
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------

The display command is used to change the color scheme and the display mode used by
your computer.  Because it depends on the video hardware in your computer, its action
changes depending on your computer. Most computers that support IRAP have some
form of VGA display.

The default choices of "color" and "25 lines" are appropriate for most cases.  Two
alternative color schemes, "mono" and "reverse mono," are offered; these may look
better on monochrome screens.  The "Lines" option offers a choice of video modes.  More
lines means more information, but it also means smaller type.

>      To change the color scheme
       1. click the button of your choice, or press:
             Alt+L for color
             Alt+M for monochrome
             Alt+R for reverse monochrome.
       2. Click the "OK" button, or press RETURN.

>      To change the number of screen lines
       1. click the button of your choice, or press:
             Alt+2 for 25 lines
             Alt+4 for 43 lines
             Alt+5 for 50 lines.
       2. Click the "OK" button, or press RETURN.

On a system with a CGA or Herculese display, you will find a checkbox marked "Snowy."  On
some systems, mostly those with CGA monitors, the screen will become snowy when the
computer is updating its contents.  While this is not dangerous to you or your
computer, it can be extremely annoyint.  If this is a problem on your screen, marking the
"Snowy" box should help to alleviate it. Because the EGA and VGA displays handle the
problem themselves, the option is not offered for them.
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------
Save Configuration
IRAP can save its configuration settings for future use.  To save the current
configuration, simply choose the "Save configuration" command in the "Options" menu.
No dialog boxes or submenus will appear, but a file called "irap.cfg" will be created in
the directory that contains irap.exe.  The next time IRAP is started, it will read this
file, setting the configuration options automatically.

>      To have IRAP look for (and save) the configuration file in a different place
       * start the program with the command:
             irap @filepath

The "filepath" can be any valid DOS file specifier.  For example,

       irap c:\home\williams\williams.cfg

       irap mine.cfg

       irap \i.c

The following settings are saved in the configuration file:
       *     "Color scheme" display setting
       *     "Lines" display setting
       *     "Snowy" display setting
       *     Variable columns
       *     Automatic tiling
       *     Maximum iterations for regression
       *     Tolerance for convergence of regression
       *     Singularity threshold for generalized inverse
; ---------------------------------------------------------------------------
; ---------------------------------------------------------------------------
This command displays a brief message about the IRAP program, including the version