533568720
User’s Manual
For the Computer Code NAIS1P2
Version 1.3
April 30, 2005
For the
National Animal Identification System (NAIS)
http://www/colostate.edu/~pburns/nais.html
(Note, because this is a research and development project, there will be frequent updates to both the
code and this manual – see the above web page for the latest versions.)
By
Patrick J. Burns
ACNS
Professor of Mechanical Engineering
Colorado State University
Fort Collins, CO 80523-2028
Voice: 970.491.5778
FAX: 970.491.1958
Patrick.Burns@ColoState.EDU
Page 1 of 13
533568720
Change Management
Changes from Version 1.0 to version 1.1
1. Added species in animal input.
2. Produced output in USAIP format, insofar as possible, with each record being a transaction.
Changes from version 1.1 to version 1.2
1.
Added input of events definitions. See section 3.E.
2.
Added input for transactions in terms of multiple events. See section 3.F.
3.
Split transactions output into separate events, with each record of the output file
corresponding to one event, either into or out of a premises.
Changes from version 1.2 to version 1.3
1. Added base offsets to animal ID and premises ID, this will allow the creation of multiple
output files that can be combined into a single input file for trace back and trace forward
processing. These offsets are input on Line 2, the Run Control Information.
Page 2 of 13
533568720
1. Introduction
This user’s manual is for the code nais1p2 (version 1.2) that produces an animal events output file
that is determined from the input to the code. The code is written in Fortran 90, and is executed on
the PC in a Windows environment. It will be ported to the Sun when the time arrives to produce
massive output files.
The remainder of this user’s manual is organized as follows. Section 2 presents the basic theoretical
foundation for the simulation. Section 3 contains the specifications for the input file. Section 4
presents and discusses an example input file. Section 5 describes the files associated with the code,
including descriptions of the output files. Finally, Section 6 contains details on how the code and this
user’s manual may be obtained.
2. Theoretical Approach
This section presents the theoretical foundation for the code and describes the algorithm for
generating a transactions output file. It begins with a discussion of general Probability Distribution
Functions (PDF’s), continues with a discussion of a probability transaction matrix, and concludes
with the details of the steps used to produce an output file.
A. Probability Distribution Functions (PDF’s)
The code is a Monte Carlo discrete event simulation. The output is based upon Probability
Distribution Functions (PDF’s) that describe the probability of occurrence of discrete events and
probability matrices that describe the transactions of animals between states (e.g. birth, death,
transfer into and out of premises). A general PDF is depicted graphically in Figure 1 below.
f2
f4
f1
fB-1
fB
f3
0
N1
N2
N3
N4
NB-1
NB
Figure 1 Probability Distribution Function (PDF)
Note that the PDF is organized into an arbitrary number of discrete “bins,” each of arbitrary size
(width and height). The values of the functions are constant within each bin. Each bin describes the
fraction of occurrences between the numbers bounding the bin on the x axis. For example, if this is a
Page 3 of 13
533568720
PDF of animal premises sizes, then bin 3 specifies the fraction of premises f3 that exist of sizes
between numbers of animals N2 and N3. In general, bin i is specified by fraction fi that occurs
between numbers Ni-1 and Ni. The first bin always begins at N0 = 0. Some properties and constraints
that must be observed for the PDF are
 Each PDF has a user-selectable number of bins, B and is specified by PDF(fi, Ni, B) for i = 1
to i = B.
 The spacing of the Ni is arbitrary, and need not be uniform.
 All fi must be positive definite, that is each fi must be greater than or equal to zero, but can be
zero.
 The sum of all fi must be 1, or 100%.
B. Animal Transaction Events
The discrete events that are modeled probabilistically involve an animal changing its state. For
example, a transaction might be an animal being sold – this is a transaction because it also must be
purchased. Each such animal transaction may result in two animal events (transitions in state) – the
animal existing on one premise is sold (the first event of the transaction) and then it is purchased by
possibly another premise (the second event of the transaction). Each such animal event is written to
the output file as a row of data. Thus, the output file could be termed an animal events file.
There two exceptions to a transaction resulting in a two animal events: when an animal is either born
or dies. Birth is handled automatically as the starting event for an animal. Nevertheless, an animal
death on a premises is modeled as a transaction, to achieve consistency in the model. The present
version of the code requires the user to define events, and also transactions, with transactions being a
sequence of two events.
Each transaction is modeled probabilistically, and the probabilities for each transaction must add to
1, or 100%. Furthermore, different animals can undergo different numbers of transactions – an
animal may be sold multiple times before being slaughtered or dying on a premises. To add fidelity,
the transaction probabilities are modeled as varying with the number of animal transactions. For
example, an animal undergoing many transactions may be more likely to die on a premises than an
animal undergoing only a few transactions.
These events are modeled by the transaction events probability matrix. The rows of the matrix are the
numbers of animal transactions, 1 through the maximum number of animal transactions (input in the
Animal Transactions PDF), and the columns of the matrix are the probabilities of the types of the
transactions. As an example, assume that the number of total possible types of transactions is 3:
sold/purchased, culled/sent to slaughter, and death on premises. Assume further that the maximum
possible number of animal transactions, excluding birth, is 2. Table 1 gives the probabilities for all of
the transactions event types for 1 and 2 possible transactions.
No. of Transaction
Events
1
2
Table 1 Transactions Event Probabilities
“Sold/Purchased”
“Culled/Sent to
Probability
slaughter” Probability
0.0
0.9
0.2
0.6
The transactions events probability matrix for this scenario would then be:
0.0 0.9 0.1
Page 4 of 13
“Died on Premises”
Probability
0.1
0.2
533568720
0.2 0.6 0.2
C. Code Execution
The code follows 5 simple steps to produce a NAIS output file. All times in the file are relative to
“right now,” i.e. whenever the code is run. The following steps are conducted for each and every
animal to be modeled.
1. An animal is selected from the animal age PDF (here, animal natural lifetimes are modeled in
days).
2. The animal is “born,” in the past, at a time equal to a random fraction of its lifetime, i.e. this
determines the animal’s age as of “right now.” This event is why “birth” is not modeled as a
transaction.
3. A “birth” premises is selected from the premises PDF.
4. The number of transactions is selected from the animal transactions PDF.
5. For each transaction, a transaction type is selected probabilistically from the transactions
events probability matrix and occurs at a random date between the “birth date” and “today.”
a. If the transaction results in a change in premises, then a destination premises is
randomly selected, and processing for this animal may continue.
b. However, if a transaction type of “died on premises” is selected randomly, then the
“death transaction” is written to the output file, and processing for this animal ceases.
6. Each event from step 5 is written to the animal details output file.
3. Input File
This section describes the structure of the input file that must be named nais1.in. With the exception
of where names are entered, all input is format free and can be entered in free form with spaces in
between values. Lines that begin with the character & in column 1 are treated as comment lines, and
are ignored by the code. These types of lines can be used to help the user organize and describe the
input file. Finally, lines and input must be organized in sequence exactly as described below. The
code is very “dumb,” and the following rules must be followed absolutely.
The detailed specifications for the input are presented below in nine sections A-I, each pertaining to a
particular aspect of the code.
A. Line 1 – Run Title
Title – A title for the run, up to 32 characters, is entered. This title appears in the header information
printed in the output file.
B. Line 2 – Run Control Information
idata – value that controls program execution:
- idata = 0: data check only
- idata <> 0: normal execution
idebug – value that controls printing of debug information:
- idebug < 0: much debug printing
- idebug = 0: no debug printing
- idebug > 0: some debug printing
iseed0 – value controlling how the random number generator is seeded:
- iseed0 < 0: use default, internal initial seed (generates repeatable output)
- iseed0 = 0: generate seed “randomly” from the time
- iseed0 > 0: use iseed0 as the seed
istat – value controlling printing of statistical information:
- istat = 0: do not compute output statistics
Page 5 of 13
533568720
- else, compute output statistics
iprint – value controlling printing to the output file:
- iprint = 0: do not print animals to output file
- else, print some animal details to the output file
offset_a – animal number base offset – this base offset is added to the animal ID to allow the output
file to start at an animal number other than 1 (for example, an offset of 100 would result in the
number of first animal simulated as 101, and animal numbers would be incremented by one
thereafter),
offset_p – premises base offset – this base offset is added to the premises ID to allow the output file
to start at a premises number other than 1 (for example, an offset of 50 would result in the
number of first premises as 51, and premises numbers would be incremented by one thereafter),
C. Line 3 Number of animals and animal species
na – number of animals to be simulated (the number of animals existing in the database at time = 0
(today) will be equal to na minus the number of animals that die on premises and the animals
that are slaughtered), and
aspecies – animal species, a 3-character variable. Note that all characters produced by the current
version of the code are lower case. This input must be one of:
Table 2 Animal Species Types
bov
cam
equ
por
ovi
cap
cer
cam
equ
dee
elk
pou
chi
tur
gee
duc
phe
gui
qua
pgn
aqu
tro
sal
ctf
til
sba
shr
cra
oys
clm
slp
msl
For example, for 10,000 bovine animals, line 3 would appear
10000 bov
Next, PDF information is entered. Each PDF is entered by first specifying the number of bins, B, for
the PDF. Then, for each bin, i, one line is required that contains the upper bound number, Ni, for the
bin and the bin’s fraction, fi, until all bins have been input. Note that bins must be input in order of
increasing Ni. That is, Ni, must be greater than Ni-1 for all i.
D. Animal Age PDF
Line 1:
nagebins –number of animal age bins
Next nagebins lines (values separated by one or more spaces):
N1 f1 (Number of animals at end of age bin 1, and fraction of animals in age bin 1)
N2 f2 (Number of animals at end of age bin 2, and fraction of animals in age bin 2)
N3 f3 (Number of animals at end of age bin 3, and fraction of animals in age bin 3)
.
.
.
Nnagebins fnagebins (Number of animals at end of age bin nagebins, and fraction of animals in age bin
nagebins)
Page 6 of 13
533568720
Notes:
1. When entering the lines describing the bins, the first entry is an integer and the second entry is
a fraction, i.e. for 100 animals and a fraction of 20%, the input would appear
100 0.20
2. The nagebins lines defining the PDF must be input in order of increasing Ni.
3. The sum of all fi must be 1, or 100%.
E. Events
Here, animal events are input. Three types of input are required: 1) the number of events, 2) the event
codes (presumably in USAIP format), and 3) the event names. Note that the first event input must be
“birth.” Finally, the events defining the transactions to be input below must be consistent (part of the
set of) the events input in this section.
Line 1:
nevents – number of events to be read subsequently
Next nevents lines:
Event code 1
Event code 2
.
.
Event code nevents
Next nevents lines:
(Note the following event names must be input in columns 1 through 20, i.e. left-justified.)
Event name 1
Event name 2
.
.
Event name nevents
Notes:
1. USAIP event codes should be used.
2. The event codes are associated sequentially with the event names. That is, the first event code
is associated with first event name, etc.
3. The first event input must be the “birth” event.
F. Animal Transactions PDF
Line 1:
ntbins –number of animal transactions bins, equal to the maximum possible number of animal
transactions
Next ntbins lines (values separated by one or more spaces):
1 f1 (Number of animals at end of transactions bin 1, and fraction of animals in transactions bin 1)
2 f2 (Number of animals at end of transactions bin 2, and fraction of animals in transactions bin 2)
3 f3 (Number of animals at end of transactions bin 3, and fraction of animals in transactions bin 3)
.
Page 7 of 13
533568720
.
ntbins
fntbins (Number of animals at end of transactions bin ntbins, and fraction of animals in
transactions bin ntbins)
Notes:
1. When entering the lines describing the bins, the first entry is an integer and the second entry is
a fraction, i.e. for 20 animals and a fraction of 10%, the input would appear
20 0.10
2. The ntbins lines for the PDF must be input sequentially in order of increasing Ni, from 1 to
ntbins.
3. The sum of all fi must be 1, or 100%.
G. Animal Transactions Definitions
Line 1:
ntprob –number of transactions (also the number of transactions probabilities).
Next ntprob lines:
(Note the following transactions names must be input in columns 1 through 30, i.e. left-justified.)
Transaction name 1
Transaction name 2
.
.
Transaction name ntprob
Next ntprob lines (2 numeric values on each line, separated by one or more spaces):
(First event code) (Second event code) for first transaction
(First event code) (Second event code) for second transaction
.
.
(First event code) (Second event code) for last transaction
Notes:
1. A “birth” is not a valid transaction, as mentioned above, so must not be input.
2. The event codes used in this section must be in the set of events defined and input in Section
E above.
3. A second event code of -1 is used if the transaction is “death on premises.” In this case, the
first event is “death,” a terminal event, and here there is no second event.
4. A second event code of -25 is used if the second event is “sent to slaughter.” In this case, the
second event is “death,” a terminal event, and here there is no subsequent follow-on event.
H. Animal Transactions Probability Event Matrix
Lines 1 through ntbins:
1 p1,1 p1,2 p1,3 …p1,ntprob – integer number of animal transactions for 1 animal transaction followed
by transaction event probabilities for transaction events of types 1 through
ntprob
2 p2,1 p2,2 p2,3 …p1,ntprob – integer number of animal transactions for 2 animal transactions followed
by transaction event probabilities for transaction events of types 1 through
ntprob
.
.
Page 8 of 13
533568720
ntbins pntbins,1 pntbins,ntprob –number of animal transactions for ntbins animal transactions followed by
transaction event probabilities for transaction events of types 1 through
ntprob
Notes:
1. These transactions probabilities are input in sequence as are the transactions defined in the
previous section G.
2. When entering the lines describing the bins, the first entry is an integer and the following
entries are fraction, i.e. for 2 animal transactions and fractions of 40%, 50% and 10% (for
sold/purchased, culled/purchased and died on premises, respectively), the input would appear
2 0.40 0.50 0.10
3. The ntbins lines defining the PDF must be input sequentially in order of increasing Ni, from 1
to ntbins.
4. The sum of all pnt,i for each line (row of the matrix) must be 1, or 100%.
I. Animal Premises PDF
Line 1 for Animal Premises PDF:
npbins –number of animal premises bins
Next npbins lines (values separated by one or more spaces):
N1 f1 (Number of animals at end of premises bin 1, and fraction of animals in premises bin 1)
N2 f2 (Number of animals at end of premises bin 2, and fraction of animals in premises bin 2)
N3 f3 (Number of animals at end of premises bin 3, and fraction of animals in premises bin 3)
.
.
Nnpbins fnpbins (Number of animals at end of premises bin npbins, and fraction of animals in premises
bin npbins)
Notes:
1. When entering the lines describing the bins, the first entry is an integer and the second entry is
a fraction, i.e. for 50 animals and a fraction of 30%, the input would appear
50 0.30
2. The npbins lines defining the PDF must be input in order of increasing Ni.
3. The sum of all fi must be 1, or 100%.
4. Example Input File
This section presents and discusses a simple input file, line by line. The input file must be named
nais1.in, and exist in the same directory where the code is being executed. The example input file is
given below. Recall that lines with an & in column 1 are treated as comment cards, ignored by the
code. Also, except where names are input, input is format free, that is, spaces may be added between
values input (indeed, at least one space is required between values, additional spaces may be added to
increase readability).
& Test input file for ver. 1.3
Test input file - ver. 1.3
& CC 1 input
& idata idebug iseed0 istat iprint offset_a offset_p
0 -1 0 1 1 0 0
& Animals input
& - na aspecies
100 bov
& Ages input
Page 9 of 13
533568720
& - nagebins
2
& - agebins agepdf
100 0.4
200 0.6
& Events input
& - nevents
6
& - event codes, must be 2-digit, positive definite
20
21
22
23
24
25
& - event names: include birth as the first event
Birth
Purchased
Sold
Culled
Died on premises
Slaughtered
& Transactions input
& - ntbins
2
& ntbins tpdf
1 0.6
2 0.4
& Transactions probabilities
& - ntprob: number of transactions, excludes birth
3
& - transaction names
Sold/Purchased
Culled/Sent to slaughter
Died on premises
& - "in event" "out event"
&
-1: death on premises - no successor "out event"
&
-25: slaughtered
& - trevents(1:2,:)
22 21
23 -25
24 -1
& - nin trpob(ntbins,1:ntprob)
&
input ntbins lines, and ntprob columns
1 0.1 0.3 0.6
2 0.6 0.3 0.1
& - Premises input
& - npbins
4
Page 10 of 13
533568720
& 20
50
100
500
pbins (size in no. of animals)
0.1
0.3
0.5
0.1
ppdf
The above input file is now discussed, with details given for each input section as identified in
Section 3 above, A-I.
A. Title – The title for this run is “Test input file – ver. 1.2”. Note that the title is limited to
32 characters.
B. Control information – for this run is
i. idata – 0, indicating that the solution phase will be run.
ii. idebug = -1, indicating that this is a debug run where a massive amount of
“debug” information will be written to the debug file. A value of idebug = 0
should be used for production runs.
iii. iseed0 = 0, indicating that a ‘random” initial seed will be generated internally
by the code. This is the recommended value for production runs.
iv. istat = 1, indicating that summary statistics will be generated and written to the
output file. This is the recommended value for production runs.
v. iprint = 1, indicating that transaction information will be written to the output
file, as well as all event information being written to the NAIS output file.
vi. Offset_a = 0, indicating that the starting animal ID will be 1.
vii. Offset_p = 0, indicating that the starting premises ID will be 1.
C. Number of animals – is 100, species is bovine ‘bov.’
D. Animal age PDF – with 2 bins. The first age bin is between 0 and 100 animals, and
40% of the animals are in this age bin. The second age bin is between 100 and 200
animals, and 60% of the animals are in this age bin. Note that the sum of animal age
fractions is 1, or 100%
E. Animal events. Here, there are six events, numbered 20 through 25. The event names
are left-justified, and must fit within 20 characters. Note that the first event is birth, as it
must be. The event codes need not be input sequentially, as long as the first event is
“birth.”
F. Animal transactions PDF – with 2 bins. The first bin, 1 transaction, represents 40% of
the animals. The second bin, 2 transactions, represents 60% of the animals. Note that
the sum of animal transactions fractions is 1, or 100%.
G. Animal transactions definitions consists of:
i. Number of transactions – is input, here 3.
ii. Animal transactions names– next, the names of the 3 transactions are input, and
must fit within the first 30 characters on each line.
iii. Animal transactions events codes – are input as pairs. Note that the second
transaction, “Culled/sent to slaughter” has a second event code of -25, thus
ensuring that the animal leaves the database after the second event of being sent
to the second premises (the slaughterhouse). The third transaction, “Died on
premises” has a second event code of -1, thus ensuring that the animal leaves
the database after the first event.
H. Animal transactions event probability matrix – with 2 rows and 3 columns (the number
of rows must equal the maximum number of animal transactions bins input in section F
above, and the number of columns must equal the number of transactions – here 3). The
probability matrix is input row by row, from 1 to the total number of possible animal
Page 11 of 13
533568720
transactions. Row 1, for 1 transaction, has probabilities of transactions of 10%, 30%
and 60% for transactions sold/purchased, culled/sent to slaughter, and died on premises,
respectively. Row 2, for 2 transactions, has probabilities of transactions of 10%, 30%
and 60% for transactions sold/purchased, culled/ sent to slaughter, and died on
premises, respectively. Note that the sum of probabilities for each row is 1, or 100%.
I. Animal premises PDF – with 4 bins. The first premises bin is between 0 and 20
animals, and 10% of the premises are in this bin. The second premises bin is between
20 and 50 animals, and 30% of the premises are in this bin. The third premises bin is
between 50 and 100 animals, and 50% of the premises are in this bin. The fourth
premises bin is between 100 and 500 animals, and 10% of the premises are in this bin.
Note that the sum animal premises fractions is 1, or 100%.
5. Files
This section describes the files used in the code, presented and discussed in the categories of input
files, scratch file and output files. Names and internal unit numbers are provided for the files. All file
names are fixed, i.e. not changeable by the user. Files that need to be saved must be copied and
renamed by the user before subsequent runs of the code.
A. Input file – name “nais1.in” unit number 1. The input file must be named “nais1.in.”
B. Scratch file – name ”nais1.scr.” This file is produced from the input file by “stripping” all
comment lines, i.e. those with an & in column 1.
C. Output files – several output files are produced by the code:
a. Output file – name nais1o.out. This file contains basic output information, including
an “echo” of the input file, the animal transaction information if the parameter iprint
is different from 0, and statistical information if the parameter istat is different from
0.
b. NAIS animal events data file – name nais1a.out. This file contains animal events
information produced by the code, in NAIS format, and is the file to be processed for
traceback and trace forward. In other words, this file contains the mock NAIS
database file.
c. Debug output file – name nais1d.out. This file is contains debug information that is
written if the control parameter idebug is different from 0.
The NAIS animal transactions output file deserves special consideration. It is produced in accordance
with the specifications on page 52 in version 4.1 of the US Animal Identification Plan (USAIP),
December 23, 2003 (see http://www.usaip.info). The output produced is one record per event. Note
that all characters produced by the current version of the code are lower case. Each record is in the
following format:
Table 3 Format for Animal Transactions Output File
Field Width
Description
Example
Notes
1
2
Event type code (20-24)
20
1
2
7
Sighting/reporting premises
x123451
2
3
7
Source/destination premises
x123452
2
4
12
Event date and time (yyyymmddhhmm)
200502031427
3
5
1
USAIN number used?
‘y’ or ‘n’
4
6
15
Animal ID number, beginning at 2,000,000,000
000002000000100
7
3
Species
bov
5
8
ID electronically read?
‘y’ or ‘n’
6
Page 12 of 13
533568720
9
10
11
12
Notes:
1.
2.
3.
4.
5.
6.
7.
8
3
1
2
Animal date of birth
Age of animal
Sex
Breed of animal
20040220
‘m’ or ‘f’
br
7
8
9
See section 3.
Must begin with the character ‘x’.
This is year, month, day, hour and minute.
Currently, set to ‘y’.
Must be one of the values in Table 1 in section 3.C.
Currently set to ‘n’.
Currently set to ‘age’ because the author does not understand the format in the USAIP
document.
8. Currently set to ‘m’.
9. Currently set to ‘br’.
An example line from the file naisa.out is given below:
23x000003x000003200501140615y000002000000006bovn20050104agembr
6. Coda Availability and Contact Information
The code is available at the URL http://www/colostate.edu/~pburns/nais.html (the URL is case
sensitive – make sure that all letters are lower case). This user’s manual, the nais1p1 source code
(nais1p2.f90), the Windows executable code (nais1p2.exe), and the input file described in Section 4
(nais1.in) are also available at that URL.
The author of the code may be contacted for additional information:
Patrick J. Burns, Professor of Mechanical Engineering and
Associate Vice President for Information and Instructional Technology
ACNS
Colorado State University
Fort Collins, CO 80523-2028
Voice: 970.491.5778
FAX: 970.491.1958
Patrick.Burns@ColoState.EDU
Page 13 of 13