Prefer Readme

Just below begins a description of PREFER. Appended to the end of this
file are instructions for installing PREFER for Windows (PREFWIN.EXE)
and for OS/2 (PREFOS2.EXE).

RD, 28 Mar 1995

INTRODUCTION (from v2.0 documentation)

The preference assessment program, PREFER, performs calculations
described in Johnson (1980), to determine the preference of J
individuals for I components using availability and usage data. PREFER
tests the hypothesis that all components are equally preferred and
compares components using the multiple comparison procedure of Waller
and Duncan (1969).

DESCRIPTION

PREFER v5.1 was developed using the CA-Realizer 2.0 Basic
development tool. It has been compiled for both Windows 3.1 and OS/2
2.1. The program performs a number of calculations, including a
subroutine supplied by Dr. David Duncan used to calculate the critical
value. The input data used by the program is:
I = number of components
J = number of individuals
Xij = usage of component i by individual j
Yij = availability of component i to individual j
NAMEi = component names
ALPHA = indicates significance level

I and J are integer values. I must be less tha J, and I * J must
not exceed 8,184 (the largest array of double-precision reals allowed
by CA-Realizer).
X and Y are two-dimensional arrays of size I * J. The array
values are stored as double-precision real numbers. There is a 64K
limit on the size of arrays, which leads to the 8,184 limit on the
number of 8-byte reals in each array.
NAME is an array of strings. Only the first nine characters of
each entry are shown when output is printed.
ALPHA is one of .01, .05, or .10, corresponding to significance
levels of 500, 100, and 50, respectively.

INPUT

PREFER has a main input screen for entering data. This screen
consists of two spreadsheets, for X and Y, and fields for entering the
number of components and individuals as well as the alpha value. The
spreadsheets are sized according to the current values of I and J,
which cannot be increased beyond the previously mentioned limit.
PREFER can also read and write data to and from files. By
default, data is stored in a binary format, with a .PDT extension. A
file saved by PREFER cannot be read by a text editor.
However, because previous versions of the program stored data as
text, PREFER does have the ability to work with textual data. Data can
be imported from a file of the correct format and can be exported to a
text file (.DAT extention by default). The format of the text file is
identical to previous versions of PREFER:

(from v2.0 documentation)
The first data line contains the integer values I and J
separated by a comma. The next card begins the X-matrix of
usage data. It is read in free format with commas separating
the elements. The j index (individuals) changes slowest. As
many elements as convenient may be placed on a line and as
many lines as necessary may be used. The Y-matrix of
availability data begins on the first line following the X-
matrix; it is read in the same format. Finally, component
names are entered separated by commas. As many lines as
necessary may be used for the names.

This may be confusing, as the matrices in the file are transposed
from the way they are shown on-screen. In the file, the components go
across the top, while in the spreadsheets, the components appear down
the side. In other words, the columns of the on-screen matrix are
stored as rows in the file.
The current import routine is fairly flexible when reading data.
Data can occupy as many lines as you want, as long as individual
values within each line are separated by commas. Hence, a file could
consist of just one value on each line, or it could have several rows
of values all on one line. As long as there are the proper number of
total values and they are in the correct order, PREFER will read the
file correctly.

OUTPUT

From the input screen, the input data can be printed to a printer
or file. This is not the same as exporting; rather, the data is
written in a nicer format and labelled.
Calculation results are shown on the screen in a new window. From
there, they may be printed to a printer or a file.

(from v2.0 documentation)
Output consists of three parts. The first section lists
t1ij the mean difference in ranks for each component.
Components are listed from most preferred to least
preferred. Next, the F-statistic for testing the hypothesis
of equal preference is given. The F-statistic is followed by
W, the critical value for the Waller-Duncan comparisons. The
final section lists for each pair of components i and k the
following statistics:
v1ik = the covariance
d1ik = the difference in mean rank
|d1ik|/sd1ik = the absolute standard difference in mean
rank, (s1ik is the standard error of the
difference).
u1ik = the (i,k) element of the inverse of the covariance
matrix.

For a more detailed description of the output, see the EXAMPLE
RUN section below.

INSTALLING PREFER

The following files are needed to install PREFER v5.1:

INSTALL.EXE
INSTALL.INF installation exectable and configuration file

PREF51.EXE main executable file
PREF51.PRF configuration file

RLZRUN20.RTS
CABLE.DLL
OBJ3D.DLL CA-Realizer files required by program (copied
to Windows or OS/2 directory)

CA_PRINT.DLL OS/2 only (copied to OS/2 directory)

SAMPLE.DAT sample text data file
SAMPLE.PDT sample binary data file (same data)
SAMPLE.OUT output produced using sample data

PREF51.HLP this file in PREFER help format
PREF51.DOC this file in DOS text format

To install the Windows version, choose <Run> from the <File> menu
in the program manager, and enter the complete path and file name for
INSTALL.EXE. (ex. A:\INSTALL.EXE or C:\PREF51\INSTALL.EXE) The install
program will then copy the files and set up a Windows program group
and item.
To install the OS/2 version, go to the command line, change to
the directory containing the INSTALL.EXE (ex. A: or C:, then CD PREF51
if necessary), and type INSTALL.

USING PREFER

At startup, the main input screen is shown. It contains two
spreadsheets for displaying the usage and availability data. Also,
there are fields for entry of the number of components and individuals
as well as the alpha value.
To enter data, simply click on the desired cell in a spreadsheet
and type in the data. (There is a separate button to click on for
changing the component names.) Manuevering inside the spreadsheet can
be done with the arrow keys or mouse.
Input data can be retrieved from a file or stored to one. These
options are the standard Open, Save, and Save As commands in the File
menu. Data is stored in a binary format, and cannot be examined with a
text editor.
However, to preserve compatibility with previous versions of
PREFER, there are options to work with textual data. The Import and
Export options under the file menu read and write data in the same
textual format used by earlier versions of PREFER. See the INPUT
section, above, for details about this file format.
Also under the File menu are options to print the input data to
the printer or to a file. Data is printed in a tabular form, with (by
default) eight individuals printed on each line. This number can be
adjusted by the user by choosing the Preferences option under the
Options menu.
The Options menu also contains a choice entitled Change Maximums.
By default, the maximum numbers of components and individuals allowed
are 20 and 409, respectively. These maxima may be adjusted; however,
the product of the two must not exceed 8,184. For instance, the user
could increase the maximum number of components to 30, but the maximum
number of individuals would be reduced to 272.
When the data is entered correctly, the Calculate button will
start the calculations. In a few moments, the output screen will
appear. See the OUTPUT section above and the EXAMPLE RUN section below
for an explanation of the output.
The output can be printed to a printer or file by clicking on the
Print button in the output screen. This brings up a self-explanatory
option selection screen.
Clicking on the Close button in the output screen will return the
user to the input screen. Note: only one output screen may be open at
a time. If an output screen is open and the user clicks on the
Calculate button, the old output screen will be destroyed.
To exit PREFER, click on the Quit button in the input screen or
select Exit from the File Menu.

EXAMPLE RUN

This example describes the input and output produced by the
sample data files included with PREFER v5.1. The data described can be
found in SAMPLE.DAT, which must be imported to be used in PREFER v5.1.
The data is also stored in binary format as SAMPLE.PDT, which can be
opened as a regular PREFER data file.

(from v2.0 documentation)
For this example, there are four components named
FOOD1, FOOD2, FOOD3, and FOOD4, and seven individuals. This
information along with the usage and availability data are
shown in Figure 1 as formatted for input to the program. The
first input line shows I and J (4 and 7). The next seven
lines illustrate input of usage data. The first line of the
usage data gives the usage value of FOOD1, FOOD2, FOOD3, and
FOOD4, respectively, by animal 1. The next six lines give
the usage data for the other six individuals. Starting on
line nine the availability data are shown in the same format
as the usage data. The final line shows component names
separated by commas.
Figure 2 shows the first part of the output. Components are
ranked showing FOOD2 most preferred and FOOD4 least preferred.
Figure 3 shows the rest of the output. The F-statistic with 3 and
4 degrees of freedom is just significant at p = .09. Next the
critical value for the Waller-Duncan procedure is given as W =
2.84 using a K ratio of 100.
The final section of output in Figure 3 lists the statistics
v1ik, d1ik, |d1ik|/sd1ik, and u1ik for each pair of components.
If d1ik < 0, a preference is shown for component i over component
k. If on the other hand d1ik > 0, a preference is shown for
component k over component i. If |d1ik|/sd1ik > W the preference
is statistically significant and "SIG" is printed after the
component names. In the example, FOOD2 is found to be
significantly preferred over FOOD4.

FIGURE 1. Data from SAMPLE.DAT used in example run.
(spaces between numbers unnecessary, added for clarity)

4, 7
2, 20, 11.5, 5
1, 4, 3, 2
19, 21, 22.5, 15
15, 14, 13.5, 13.5
5, 7, 8, 4
10, 25, 20, 15
7.5, 4, 5, 2
10, 20, 40, 30
18, 2, 21.5, 15
25, 15, 20, 30
15, 10, 5, 9
10, 30, 30, 20
50, 30, 15, 47
20, 10, 10, 20
FOOD1,FOOD2,FOOD3,FOOD4


FIGURE 2. Sample output from example run.
(stored as SAMPLE.OUT)

Average difference in ranks for components

COMPONENT TBAR RANK

FOOD2 -1.285714 1
FOOD3 -.642857 2
FOOD1 .642857 3
FOOD4 1.285714 4


Test of ho: all components are equally preferred

F( 3, 4) = 4.25385


Critical value for Waller-Duncan procedure with K=100:
W = 2.84

Abs
Var/ Diff in Std Sigma
I K Covar mn rnk Diff Inv

FOOD1 FOOD1 2.05952 0.00000 0.00000 1.67180
FOOD2 FOOD1 -1.41071 -1.92857 1.99590 1.58221
FOOD2 FOOD2 1.65476 0.00000 0.00000 2.13583
FOOD3 FOOD1 -0.30952 -1.28571 1.63636 0.68187
FOOD3 FOOD2 -0.38095 0.64286 0.84416 0.79336
FOOD3 FOOD3 1.64286 0.00000 0.00000 0.92113
FOOD4 FOOD1 -0.33929 0.64286 0.86204 0.00000
FOOD4 FOOD2 SIG 0.13690 2.57143 4.27241 0.00000
FOOD4 FOOD3 -0.95238 1.92857 2.35302 0.00000
FOOD4 FOOD4 1.15476 0.00000 0.00000 0.00000

VERSION HISTORY

1.0 Anthony M. Frank, Feb 1980, FORTRAN version (updated Oct
1981)
2.0 Oct 1985, version for IBM PC
3.0 Cathy Kopas, Oct 1985, allow interactive user input
4.0 Mike Schwartz, Feb 1990, BASIC version, added DOS user
interface
5.0 Chad Pankratz, Aug 1994, CA-Realizer version for Windows and
OS/2
5.1 Oct 1994, fixed calculation bugs

REFERENCES

Duncan, D.B. 1979. Personal communication. Oct. 29, 1979. IBM.
1970. System/360 scientific subroutine package. Version III.
Programmer's Manual. Program Number 360A-CM-03X. Fifth
edition (August 1970) pp. 119-120, 152-159.
Johnson, D.H. 1980. The comparison of usage and availability
measurements for evaluating resource preference. Ecology
61(1).
Waller, R.A. and D.B. Duncan. 1969. A Bayes rule for the
symmetric multiple comparisons problem. J. Am. Statist.
Assoc. 64:1484-1503.

INSTALLATION INSTRUCTIONS FOR PREFER v5.1 (for Windows)

Note:
Version 5.0 of PREFER contained differences in the calculation
routines which resulted in erroneous results. Version 5.0 should
NOT be used any more.

Installation instructions:

After copying PREFWIN.EXE to a directory, extract the files from the
executable archive by typing at the prompt, PREFWIN

The install program must be run to set up PREFER on a machine.

To install:
Under the File menu in the Windows Program Manager, select Run.
Then, type in the path and file name of the install program; for
example, A:\INSTALL. The program will be copied to its own
subdirectory (which may be changed by the user). In addition, a
RLZRUN20 directory will be created under the Windows directory.
This directory contains files needed for PREFER to run.

NOTE to users who have previously installed PREFER v5.0:
By default, this version installs to a different directory than
v5.0 did, and it creates a new program group in Windows. After
installation, v5.0 of PREFER can be deleted from your hard drive,
and the Windows program group for PREFER v5.0 can be deleted.
Alternately, if you do choose to install to the same directory,
the files that can be deleted are just those which begin with
PREF50.

INSTALLATION INSTRUCTIONS FOR PREFER v5.1 FOR OS/2

This distribution of PREFER v5.1 is stored as a single archive of files.
This means that the files must first be extracted from the archive and
then installed onto the system. The filename is PREFOS2.EXE; it is a
self-extracting archive.

To install the program:

1) Create a temporary directory on your hard drive. This directory will
contain the files needed to install PREFER. Make sure you use a
directory name that does not already exist (ex. XXX or something
like that). This directory will not be used to store the actual
program. For example, issue the command:
MKDIR C:\XXX

2) Copy the self-extracting archive file to the newly-created temporary
directory. For example,
COPY A:PREFOS2.EXE C:\XXX

** THE NEXT STEP MUST BE RUN FROM DOS, OR IN A DOS WINDOW. **

3) Change to the temporary directory and execute the file.
C:
CD \XXX
PREFOS2
This will extract the installation files for PREFER v5.1.

** THE FOLLOWING STEP MUST BE RUN UNDER OS/2. **

4) Now, from the OS/2 Full Screen command prompt, type:
INSTALL
The installation routine will execute. Make the directory you choose
for the install is not the temporary directory.

5) The files in the temporary directory can now be deleted, and the
directory may be removed. For example:
C:
CD \XXX
DEL *.*
CD ..
RMDIR \XXX

NOTE: IF YOU HAVE PREVIOUSLY INSTALLED PREFER v5.0

By default, this version installs to a different directory than
v5.0 did, and it creates a new program group on the desktop. After
installation, v5.0 of PREFER can be deleted from your hard drive,
and the desktop program group for PREFER v5.0 can be deleted.
Alternately, if you do choose to install to the same directory,
the files that can be deleted are just those which begin with
PREF50.