README for IOPUT

IOPUT version 1.0, Copyright (C) 2007 Dan Uznanski and Alison Watkins
IOPUT comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it under certain conditions; see LICENCE.txt for more information.

----------------------

What the program does:

IOPUT (Index Of Patchiness with Unavailable Traps) was designed to calculate the index of patchiness described by Brown et al. (2004) when some trap stations are unavailable.

The original method developed by Brown et al. (2004) requires the status of every trap to be recorded as occupied or not on every possible trapping occasion. Browns method does not allow for unavailable traps (for example where a trap was sprung but no animal caught, or only a non-target animal was caught).

When the IOPUT program encounters an unavailable trap, it treats the data as if the trap was not there in the field; the distance between the neighbouring stations is doubled but the unavailable station cannot be randomised nor does it receive part of the redistributed catch when calculating the average distance as an empty trap would.  For example for traps:

1 2 3 4 5

if there was 50 m between each trap and trap 2 was unavailable (say, caught a mouse instead of a rat) and traps 4 and 5 caught rats (or whatever animal is of interest) then IOPUT would recieve the data:

0,-,0,1,1

And during calculation would treat traps 1 and 3 as being 100 m apart (as they were in the field) as if trap 2 had never been present.

For three captures over ten stations the captures are broken into segments (tenths) and split among bins (traps) as follows (each upper case letter represents one capture and each lower case letter represents 1/10th of each capture):

ie for captures:

A,B,C,0,0,0,0,0,0,0

each tenth will be distributed:

aaa aaa aaa abb bbb bbb bbc ccc ccc ccc

This will always be the most efficient way of distributing the captures even if the captures are clustered at one end.

----------------------

How to install IOPUT:

Choose (or create) the folder in which you want the program to be, and copy all the files from the IOPUT folder on this CD into your folder.  Make sure you have Python installed as IOPUT will not run without it.  The latest version of the Python interpreter, which was used to create IOPUT, is available from www.python.org.

----------------------

Input format (for data files):

Data must be formatted as a CSV file.

There should be nothing in the first two columns of the top row (when viewed with spreadsheet software).  The rest of the top row should represent trap number.  The first two columns should contain the sample date (or other sample identifier) and should be identical.  All other cells should contain the relevant data.  sample.csv provides an example.

All unavailable traps should be marked with a '-'.  See sample2.csv for an example.

----------------------

Output format:

The top line of trap number is not returned in the output.  However the rest of the input file is (2 columns of sample dates/identifiers plus the data).  On the right hand end of the data are the results, output in the following order (explanation below): Dob, Random?, Dav, Dmax, Dmin, I, above, below.  These ARE NOT labled.

Dob	The observed D value for your data
Random?	Whether or not the data were ranomised (True or False).  If false, every possible permutation of the observed data was tested against Dob
Dav	The averaged D value of the set of possible permutations or the set of randomised permutations
Dmax	The highest D value calculated by any permutation (randomised or not)
Dmin	The lowest D value calculated by any permutation (randomised or not)
I	The patchiness index (Dob/Dav)
above	The number of permutations with a D value greater than Dob
below	The number of permutations with a D value less than Dob

You will need to calculate the P value from above and below (P = above/(above+below)).  You will probably also want to label each column to avoid confusion.

----------------------

Instructions to run IOPUT:

distributions.py, permutations.py and all data files should be in the same folder.

Open the command prompt (start > run, type cmd and hit OK) and navigate to the directory in which Python is installed in (probably C:\Python24>).

Type the following (where '...' represents the directory in which the program and data files are in 'sample.csv' represents your data file and 'sampleoutput.csv' represents your desired output (this file does not have to exist))

python "C:\...\distributions.py" "C:\...\sample.csv" > "C:\...\sampleoutput.csv"

----------------------

Troubleshooting:

Remember: the program may take some time to run, especially if you have a large data set.  A single, short line of data should take only a few seconds, but multiple long lines of data may take an hour or more.  Of the two sample data sets included here, shortsample.csv takes approximately 20 seconds, sample.csv takes approximately 6 minutes and sample2.csv takes approximately 5 minutes.

If you need to interupt the program, the shortcut ctrl-shift-C in the command prompt will acheive this, but your data set will not be fully analysed.

Firstly:
Have you installed Python?  This program will not run without the Python interpreter installed.

Error messages:

********
'python' is not recognized as an internal or external command, operable program or batch file.
-----
Cause: Either you do not have Python installed, or you have not navigated to the folder where it is installed (eg C:\Python24> (see below))
********

********
The process cannot access the file because it is being used by another process.
-----
Cause: the output file is open.
********

********
Traceback (most recent call last):
  File "C:\python24\distributions.py", line 220, in ?
    runDataFile(sys.argv[1])
  File "C:\python24\distributions.py", line 134, in runDataFile
    for line in skipFirstIterations(csv.reader(file(filename))):
IOError: [Errno 2] No such file or directory: 'C:\\python24\\sample3.csv'
-----
Cause: Incorrect file name or incorrect directory path.  Check spelling.
********

If you have any other problems, please contact the authors at: afwatkins@gmail.com

----------------------

Authorship:

Dan Uznanski and Alison Watkins

----------------------

Licence:

Released under the GPL.  See the file LICENCE.txt for more information.
