README.TXT for SPAM version 3.7 - Statistics Program for Analyzing Mixtures
June 2003

CONTENTS
1. Included Files
2. Installation
3. Running SPAM
4. Version History
5. Distribution of Software
6. Who To Contact


1. INCLUDED FILES

  SPAM37.EXE - SPAM executable.
  SPAM_v37.pdf - SPAM v 3.7 Manual Addendum in Adobe PDF format.
  SPAM35Final.pdf - SPAM v 3.5 Manual Addendum in Adobe PDF format.
  SPAM_v32.pdf - SPAM v 3.2 User's Guide (The basic SPAM manual to which
                 SPAM_v37.pdf and SPAM35Final.pdf are addenda), in Adobe PDF format.
  Columbia.zip - example files for the SPAM v 3.2 User's Guide.
  README.TXT - This document.


2. INSTALLATION

SPAM version 3.7 consists of a single file, SPAM37.EXE.

Manual Installation
    A. Copy the file SPAM37.EXE to the directory of your choice.
       That's it.


3. RUNNING SPAM

Several options exist for running SPAM. In each case, SPAM is started
by executing SPAM37.EXE.

Options:
    A. Locate SPAM37.EXE with Windows Explorer and double click it to
       start.
    B. Add SPAM37.EXE to the start menu and select it to start. To add
       an item to the start menu,  go to START > Settings > Taskbar...
       Select the Start Menu Programs tab, choose Add... and follow the
       instructions on the screen. You can set the "Start In"
       directory for this shortcut by right clicking on the task bar and
       selecting Properties. Select the Start Menu Programs tab and click
       Advanced... Find the shortcut for SPAM, right click it, and
       select Properties. Set the Start In directory to the location of
       your control files.
    C. Create a shortcut to SPAM37.EXE, place it on your desktop, and
       double click it to start. To create a shortcut, locate the file
       in Explorer, right click on it, and select Create Shortcut. The
       shortcut can then be moved to the desktop. You can additionally
       open the property dialog box for the shortcut you just created
       (right click on it and select Properties) and specify the
       "Start In" directory. If you enter the directory that contains
       your control files, then the file selection dialog box will open
       to that directory by default.


4. VERSION HISTORY

Version  O.S.     Comments
1.0      Win 3.1  Sent to all initial users.

1.01     Win 3.1  Sent to all users between May 1995 and April 1997.

1.02     Win 3.1  Documentation updated to include random seed.
                  Program not changed.

2.0      Win 95   Major upgrade to Windows 95.
                  Date - 9 July 1997.
                  Shipped via email only July to December 1997.

                  Bugs fixed:
                  1. Baseline frequency output file now includes all
                     loci. The last locus was occasionally omitted in
                     the previous release.
                  2. Baseline frequency output file is now correct when
                     running an ESTIMATION and resampling the baseline.
                     Previously the final resample was printed instead
                     of the original baseline.
                  3. The final standard error is now printed in the
                     mixture estimate output file.
                  4. Score values in the mixture estimate output file now
                     have expected values of zero instead of the number
                     of observations in the mixture. This matches output
                     from other mixture software.
                  5. Bootstrap estimates are now correct for any mixture
                     file. Errors were occasionally noted, especially
                     when there were missing loci in the first line of
                     the mixture file.

                  Enhancements:
                  1. Random seed can now be generated from the system
                     clock or declared in the control file.
                  2. Multiple control files can be selected to run in
                     batch mode.

2.01     Win 95   Date - 24 December 1997.
                  1. A bug was corrected that would cause an error when
                     fewer than eight stocks were in the baseline.
                  2. SPAM95.EXE was changed to get the path of
                     _SPAM95.EXE from a SPAM.INI file instead of from
                     WIN.INI.
                  3. The dialog box to open the control file(s) was
                     changed to the Explorer type.
                  4. A setup application was created for installation.

2.02     Win 95   Date - 13 February 1998.
                  1. Bug #1 under version 2.01 was not completely
                     resolved. SPAM would still crash with too few stocks
                     and too many loci. Problem fixed for good this time.

3.0      Win 95   Date - 12 May 1998.
                  SPAM version 3.0 has gone through major revisions in
                  both function and interface. Most notably, it now has a
                  more standard Windows appearance and performance. It is
                  a complete analysis tool from which you can edit
                  control files, perform mixed stock analyses and
                  simulations, and view the results.

                  I. Functional Revisions

                  *Options

                  1. When doing a bootstrap or simulation, stock
                     contribution estimates for each resample can be
                     output to a file. Use the new option

                        Print bootstrap estimates : t

                     with 'print' and 'bootstrap' being the keywords. The
                     file is given the output filename with the extension
                     *.RSM. The first two lines of the output file look
                     something like

                        Number of populations: 14
                        Number of resamples: 50

                     followed by a list of population names. The
                     estimates are then given with as many columns as
                     there are populations and as many rows as resamples.
                     If there are more than 100 populations, the line
                     will wrap so that there could be two or more rows
                     per resample.

                  2. An iterations output file can optionally be created.
                     This file contains iteration information from the
                     search algorithm and was previously only output to a
                     text window. The file has the output filename with
                     the extension *.ITR. Use the new option

                        Print iterations : t


                  *Parameters

                  1. In specifying the number of stocks in the analysis,
                     you can use either 'stocks' or 'populations' as
                     keywords:

                        number of populations : 14
                     or
                        number of stocks : 14

                  2. Bootstrap confidence intervals are now output for
                     each reporting region. Confidence intervals are
                     included in the *.SIM file when doing a simulation
                     or in the *.BOT file when doing an estimation and a
                     bootstrap is requested. You can specify what
                     confidence interval to output with the new parameter
                     statement

                        confidence intervals : 90

                     with 90% confidence intervals being the default. An
                     error message is generated if this is set less than
                     or equal to 0 or greater than or equal to 100. This
                     parameter is also used for the normal and the
                     likelihood confidence intervals so that confidence
                     intervals of other than 80% are now possible.


                  *Characters

                  1. The manual incorrectly states that there is a limit
                     of 9 types (alleles) per character (locus). The only
                     limitation was how many alphanumeric characters
                     could be read from one row of the baseline and
                     mixture files. This was previously set at 132 for
                     the baseline file and 256 for the mixture file.
                     Because many users would like to use SPAM for
                     microsatellite analyses, these limits have been
                     increased to 512 for the baseline and 1024 for the
                     mixture. You should make sure that no single row
                     exceeds these limits for either file.


                  Miscellaneous

                  1. A log file is created for any analysis performed
                     containing the notes and error messages previously
                     output to the main window. This file is located in
                     the same directory as the control file with the same
                     base filename and a *.LOG extension.

                  2. You can comment out lines with either a backward
                     slash (\) or a forward slash (/).

                  3. An error message is generated if the number of
                     resamples is set less than or equal to 1 when doing
                     a simulation or an estimation with a bootstrap.

                  4. An error message is generated if there are more loci
                     listed in the *characters section than are specified
                     in the number of characters option statement. We
                     could have just taken the first n loci listed, but
                     this way ensures that the loci that are used are the
                     ones the user intended.

                  5. An error message is generated if no output filename
                     is given in the *files section.

                  6. Blank lines are now acceptable at the end of a
                     mixture file. Previously there could not be a new
                     line character at the end of the last row of data

                  7. If an output filename is given in the *files section
                     containing directories that do not exist, they will
                     be created rather than giving an error message. This
                     saves you from having to set up the output directory
                     structure before running the analysis.

                  8. An error was fixed that caused a fatal error with a
                     small number of populations and a large number of
                     loci. This error only occurred when the number of
                     populations was less than around 7 and the number
                     of loci was greater than around 4 or 5. Previous
                     results should not be suspect if the analysis ran
                     to completion.

                  9. Baseline frequency files are now successfully
                     created when using large numbers of alleles per
                     loci, such as with microsatellite data.

                  II. Interface Revisions

                  File Structure

                  1. There is now only one file associated with SPAM
                     version 3.0, spam30.exe. This file can be installed
                     and executed from any directory. SPAM is written
                     completely in FORTRAN with full windows interface.

                  2. Two options listed below (selection of a text editor
                     and turning off error message boxes) make use of a
                     spam.ini file located in the c:\windows directory.
                     SPAM will create this file and make additions and
                     revisions as necessary so that you will not need to
                     edit this file yourself. The use of spam.ini is
                     fully compatible with previous versions of SPAM so
                     that multiple versions can be used simultaneously.

                  3. When spam30.exe is copied to your hard drive, you
                     will most likely wish to create a shortcut for it
                     on your desktop. To do this, right click the file
                     in Explorer and select 'Create Shortcut' and place
                     it on your desktop. You can change the working
                     directory of the shortcut so that file selection
                     always begins in a predetermined directory. Right
                     click the shortcut, select the 'Shortcut' tab, and
                     enter a path in the 'Start in:' box. From this same
                     location, you can select 'Change Icon...' to select
                     the old style SPAM icon if you prefer.


                  Windows Interface

                  1. SPAM is run by executing spam30.exe either directly
                     or from a shortcut. A standard window appears from
                     which you will perform analyses and view/edit files.
                     It remains open for the duration of your SPAM
                     session.

                  2. To run an analysis with an existing control file.
                     Select 'Run SPAM' from the Commands menu, or press
                     F10. An open file dialog box appears from which you
                     select one or more control files. The filter is set
                     for *.CTL so be sure your control files have this
                     extension. If your file has a different extension,
                     type in a filter (e.g., *.TXT or *.*) and press
                     Enter. When the appropriate file or files are
                     selected, click Open.

                     A child window will appear with the name of the
                     control file in the caption bar along with the word
                     'Running'. Blue text will appear in the child window
                     as the analysis moves through different stages. You
                     are informed of any output files that are created.
                     When the analysis is complete, the text changes to
                     black and informs you the analysis is complete, the
                     system asterisk sound is heard, and the word
                     'Finished' appears in the caption bar.

                     If a fatal error occurs during the analysis, a popup
                     window appears that describes the error. Click OK
                     and the text in the child window changes to red amd
                     informs you the analysis was aborted, the system
                     exclamation sound is heard, and the word 'Finished'
                     appears in the caption bar.

                  3. To view the results, select the output file you wish
                     to view from the 'Results' menu that appears with a
                     child window. All possible files associated with an
                     analysis are included in the list, but only those
                     that pertain to the selected child window are
                     visible and can be selected. Select a file and it
                     will open in an external text editor. By default,
                     Notepad is used as the text editor, but any text
                     editor can be chosen as described in item 6 below.
                     You can also use function keys to view the more
                     common files: control = F5, log = F6, estimation =
                     F7, and simulation = F8. Once activated, the text
                     editor is a stand-alone application and can be used
                     to edit and save any file.

                  4. You can open any file for editing or viewing from
                     SPAM. Select 'Open File' from the Commands menu, or
                     press F11. An open file dialog box appears from
                     which you can select a single file. The filter is
                     initially set for control files (*.CTL), but can be
                     changed to show all SPAM files (*.CTL, *.LOG, *.EST,
                     *.SIM, *.BOT, *.ITR, *.RSM, *.BSL, *.CMX, *.GEN, and
                     *.POP) or any file (*.*). Select the file, click
                     Open, and the file is opened in the external text
                     editor. With this feature, you can easily make
                     changes to your control file from your SPAM session.

                  5. Once an analysis is complete and you have closed the
                     child window or exited SPAM altogether, you can open
                     any SPAM file directly with your text editor.
                     Alternatively, you can use the original control file
                     to load just the list of files associated with an
                     analysis and view them from within SPAM. Select
                     'Load Results List' from the Commands menu, or press
                     F12. An open file dialog box appears from which you
                     can select one or more control files. Select the
                     file and click Open. A child window will appear with
                     text stating that the control file is being read.
                     Upon completion, the text changes to green and
                     informs you that the results list has been loaded.
                     You can then use the Results menu to select the file
                     or files you would like to view. This procedure is
                     only meaningful if the analysis was previously run.
                     Otherwise, some or all of the files listed may not
                     exist. If a non-existent file is selected, the text
                     editor will appear, but no file is loaded.

                  6. To change the external text editor, select 'Select
                     Text Editor' from the Options menu. An open file
                     dialog box appears with the filter set for
                     executable files (*.EXE). Find the executable for
                     the text editor you wish to use and click Open. The
                     path to this file will be saved in the spam.ini file
                     for future sessions. Notepad has a single document
                     interface so that only a single file can be opened
                     at a time. Repeatedly selecting files for viewing
                     results in multiple Notepad applications running.
                     Selecting a text editor with a multiple document
                     interface, such as WinEdit, allows you to open
                     several files within the one editor.

                  7. If you are running several control files
                     successively (multiple control files selected from
                     the 'Run Spam' open file dialog box), a fatal error
                     in any one file will stop the process until you
                     click OK in the popup error dialog. This is not a
                     good thing if you are running several analyses
                     overnight. To turn off the popup error messages,
                     select 'Show Error Messages' from the Options menu.
                     Error messages are shown if this menu item has a
                     check mark and not shown if the check mark is
                     absent. Repeatedly selecting 'Show Error Messages'
                     will toggle the state of the check mark. When
                     unchecked, a fatal error will quit the current
                     analysis and SPAM continues on to the next control
                     file. Error messages are always printed out to the
                     log file so that you can still determine the cause
                     of the error. After multiple analyses are run, an
                     aborted analysis is easy to spot because the text
                     will be red. Select the child window where the error
                     occurred and choose the log file from the Results
                     menu to view the error message. The state of the
                     'Show Error Messages' check mark is saved in the
                     spam.ini file so that any change you make will be
                     saved between sessions.

3.2      Win 95   Date - 3 February 1999.
                  1. When using more than one level and estimate values
                     are given in both the populations and regions
                     sections, the values for level 1 are used for setting
                     up simulations or starting values. Worked OK before
                     with one level, but not for two or three.
                  2. When using characters with many alleles (microSats),
                     It's possible to generate a simulated sample with
                     all 'impossible' genotypes, causing SPAM to crash.
                     Now a message box appears and a line is added to the
                     log file that states why SPAM is aborting and suggests
                     reducing the genotype tolerance. This parameter can be
                     set to 0 to avoid having any 'impossible' genotypes.
                  3. Added a second file filter to run control files that
                     do not have a *.ctl extension. The default is still
                     *.ctl, but the user can select the usual All Files
                     (*.*) filter.
                  4. Previous revision allowed large number of loci or
                     alleles per loci, but there were still problems when
                     printing a baseline summary or condensed mixture file.
                     This has been corrected so that, if the baseline and
                     mixture files can be read, then these files should be
                     created OK. General guidelines to live by:
                     a. All loci should have a maximum of 100 possible
                        alleles. If you have more, you should pool some
                        together.
                     b. The total number of alleles over all loci should
                        not exceed 1000. If loci have 100 alleles each,
                        you can have a max of 10 loci (100*10=1000). If
                        they have 20 alleles each, you can have a max of
                        50 loci (20*50=1000). Etc.

3.5     Win 98   Release Date - 7 Sept 2001
                1. Expanded choice of bootstrap confidence intervals.
                2. User can request that the maximum likelihood value attained for
                   each simulation or bootstrap resample is recorded. This, coupled
                   with the new ability to synchronize mixture simulations across runs,
                   allows the user to conduct Monte Carlo likelihood ratio tests.
                   See the SPAM v 3.5 Addendum for example applications now available.
                3. Minor changes to default values (see SPAM v 3.5 Addendum).

3.7	Win 98	Release Data - 25 June 2003
		1. Allows for Bayesian modeling of baseline allele frequency distributions. 
		   Namely, SPAM 3.7 offers two Bayesian models of baseline allele frequency 
		   distributions: 1) Rannala-Mountain and 2) Pella-Mausda.
		   See the SPAM v 3.7 Addendum for details and examples.


5. DISTRIBUTION OF SOFTWARE

SPAM is freely distributed to anyone wishing to use the software. We do,
however, ask that you not distribute it without our permission so that we
can maintain an accurate list of users. We are dedicated to fixing bugs
and making enhancements to SPAM and would like to be able to send notices
and revisions to all users.


6. WHO TO CONTACT

Gene Conservation Laboratory
Alaska Department of Fish and Game
333 Raspberry Road
Anchorage, AK 99518

Anton Antonovich
Anton_Antonovich@fishgame.state.ak.us
907-267-2836

Lisa Seeb
Lisa_Seeb@fishgame.state.ak.us
907-267-2249

Bill Templin
Bill_Templin@fishgame.state.ak.us
907-267-2234
