DOCUMENTATION FOR THE  CRITTRZ POPULATION

SIMULATION KIT, VERSION 0.7.5

 

Revised October 20, 2006

From documentation for previous versions of CRITTRZ

 

© 2006 Tom Olivier

 

By Tom Olivier

Green Creek Paradigms, LLC

Schuyler, VA  22969  USA

tolivier@starband.net

 

Project Home Page

www.greencreekparadigms.com/CRITTRZ.htm

 

 

Table of Contents

 

 

Licenses

 

CRITTRZ is released under an open source license commonly known as an ‘MIT license’.  Here it is.

 

 


CRITTRZ Population Simulation Kit License

 


Copyright © 2006 Tom Olivier


Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

 

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

 

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

 

 


Module rv, in the CRITTRZ\libs directory, was written by Ivan Frohne (1998).  Ivan Frohne holds the copyright to module rv and has released rv under an open source license.  Copyright notice and licensing details for rv will be found both in the module source and in the documentation file in the CRITTRZ\docs directory.

 

Introduction

 

CRITTRZ is a population simulation construction kit.  It is intended for modeling animal populations containing a few dozen to several thousand individuals.   It supports modeling populations containing subpopulations with little internal structure as well as subpopulations with complex, dynamic structures seen in some mammalian social groups.  CRITTRZ permits examination of interactions of demographic, genetic, social and infectious disease processes.  The current release includes modules for construction of models of some Old World monkey populations.  The author hopes the CRITTRZ kit will prove extensible to modeling populations of other taxa.  The kit includes an interface to a geographic information system (GIS).  Through this interface, spatial structures and landscape states of areas occupied by simulated populations can be incorporated into model processes.  A simulation may contain multiple-populations, representing different species. 

The home page for the CRITTRZ population simulation kit project is www.greencreekparadigms.com/CRITTRZ.htm.  This page provides links to documentation, reports on applications of the modeling kit and links for downloading current CRITTRZ distributions.  You can download current and previous CRITTRZ distribution file sets at http://sourceforge.net/projects/crittrz.

Version 0.7.0, the initial version, was released in June 2004.  It contained core modules, some sample applications, inputs and brief documentation.   Version 0.7.1 was released in August 2004.  It added tools and some maintenance changes.  Version 0.7.2, released in February 2005, added density-dependent modeling of survival and birth processes and a variety of other refinements.  Version 0.7.3 was released in August 2005.  It adds a model of a monkey population with density-dependent birth and survival processes, a module for tracing descendants of female members of a simulation founding population and some other changes.  Version 0.7.4 added a simple, general base class for infectious disease modeling and separate distribution files for Windows computers without a GIS, Windows computers with the Idrisi GIS and Linux computers without a GIS. All releases to date are considered to be of alpha test development status.  The current version, 0.7.5, adds a raster module that reads and writes Idrisi raster files, a home range modeling module, a new population framework that integrates aspects of density-dependent survival and reproduction and a GIS-based monkey density-dependent population application.  The high-level organization of the agesex_dd_idrisi application has been revised in a form consistent with the new Idrisi-based monkey simulation.

 

CRITTRZ is open-source software; anyone receiving a copy is free to redistribute it, extend it and modify it, as explained in the license.   The author intends that the open-source release will make CRITTRZ readily available to scientists anywhere who might have use for it.

 

CRITTRZ is intended as a tool for biologists engaged in basic research and conservation. 

The kit is designed to allow biologists who are occasional programmers to build simulation applications from preexisting modules.  The architecture of the system is highly extensible, though construction of entirely new modules generally will require sophisticated software development skills. 

 

This modeling kit is an outgrowth of simulations of population genetic processes in social groups of savanna baboons and rhesus monkeys built by the author in the 1970’s and 1980’s.  One could see then that computer simulations allowed portrayal of complex population processes observed in real populations, processes that were too complex for ready mathematical treatment.  At the same time, construction of simulations of populations exhibiting different kinds of complexity raised new issues regarding general means of representing population structures and events that change them.  Olivier (1984, 1985, 2003a, 2003b, 2006) provide background on the biological modeling issues that led to the construction of CRITTRZ and details on organization and applications of earlier development versions.  Olivier (2004) reports on an application of CRITTRZ in a study of interactions between behavioral, genetic and demographic processes in simulated populations of Old World monkeys.  Olivier (2005) examines matriline numbers, sizes and genetics in simulated monkey populations.

 

My aim in releasing alpha versions is to elicit comments from biologists with an interest in modeling kits like this, before firming up more system features with the beta release.  If you would like to offer some thoughts regarding CRITTRZ, please email the author (tolivier@starband.net).

 

Organization and Implementation

 

The modeling kit is written in Python, an open source, object-oriented language.   (see http://www.python.org/).  Object-oriented languages allow definition of classes of objects that combine data attributes and behaviors.  Many instances of a particular object class can exist simultaneously in a program.  Objects of one class can be embedded as data objects in another class.  New classes of objects can be derived from already defined classes.  These properties of objects make them convenient for many tasks in modeling population processes.  CRITTRZ uses object-oriented methods extensively.

 

Python is a dynamically typed language.  The types of objects referenced by names can vary during program execution.  Also, the types of objects stored in containers such as lists and hash tables (dictionaries in Python) can be varied quite freely.   This means, for example, that numbers and kinds of data fields associated with individuals in simulations can be varied readily to suit the purposes of different applications. 

 

Python also emphasizes dynamically sized data containers and automatic release of memory of data structures no longer in use.  As a result, there are virtually no fixed limits on numbers of individuals, subpopulations and so on that might be created in a CRITTRZ simulation.

 

An application written with CRITTRZ usually contains a simulation object with one or more population objects.  In turn, each population contains one or more subpopulation objects.  Subpopulations may be social groups with members belonging to different elements within the subpopulation.  For example, subpopulations in the sample monkey application are social groups divided internally into group elements, one containing immigrant adult males and a natal segment containing adult females and immature offspring of both sexes. 

 

In an application, a simulation steps populations through a series of discrete time periods, with births, deaths and other biological events potentially taking place in each time period.  Individual life histories are simulated in detail. 

 

Unique identifiers are given to subpopulations within each population, group elements of subpopulations and individuals.  Each identifier consists of a text string that identifies population component type and an integer number.  Internal organization of subpopulations is represented in keyed data structures.  These may be represented in syntactically organized character strings, Python dictionaries or indented text blocks.  See Olivier (1985) and Olivier (2003a, especially Appendix A) for more information on keyed structures, examples of their use in representing subpopulations with simple and complex internal structures and the use of template strings to asses structural correctness.

 

CRITTRZ architecture isolates many features of population structures and processes.  Framework objects store structural information on populations and subpopulations.  Separate event modeling objects simulate births, deaths, migrations and other biological events (group fissions, fusions; diploid inheritance; transmission of diseases).  A population model is created by binding a population framework with objects for modeling biological events of interest.  By design, these bindings occur at a high level in the source code, simplifying code changes required to build models with varying biological assumptions.

 

Object class derivations are used to extend and specialize modeling kit components for particular applications.  For example, a basic population framework that makes no assumptions about age or sex distinctions of population members is specialized in a derived framework to handle populations structured by age and male and female sexes.  Additional derivations are used to specialize this age and sex aware framework, and some event modeling classes, to customize them for use in the sample Old World monkey applications.

 

In basic CRITTRZ models, no spatial structuring of relationships among subpopulations is assumed.  However, geographic space can add structure to many population processes.  In a simple spatial model, subpopulations might be arranged on a homogeneous, Euclidean plane, with isolation by distance influencing processes such as the migration of individuals.  More realistically, landscapes may vary greatly in structure, with costs of movement, habitat suitability, disease risks and other factors varying irregularly or in complex patterns with location.

 

To facilitate sufficient realism in modeling spatial and landscape effects, one of the CRITTRZ for Windows distribution files includes a run-time interface to the Idrisi GIS (Clark Labs, 2003).      At present, this interface provides some foundation functionality, a module that models migration between subpopulations occupying subareas of a landscape where costs of movement vary over the landscape, as well as survival and reproduction modules where these events are affected by resources available in areas occupied by subpopulations. 

 

Idrisi was chosen as a foundation for this initial representation of spatial and landscape effects because this software emphasizes raster representation of data, which seem well suited to many conservation projects, the programming interface is relatively simple and quite powerful analytical tools are included.  Modules idripop, geo_idrisi, migration_idrisi, survival_dd_idrisi, reproduction_dd_idrisi, agesex_popframe_idrisi, applications agesex_base_dd_idrisi_app and cercomm_dd_idrisi_app and harness agesex_base_dd_idrisi_harness require presence of an Idrisi GIS system.  New modules raster_idrisi and home_range_idrisi are written in Python and directly access and manipulate Idrisi GIS files, without use of a separate GIS program.

 

CRITTRZ is designed for creation of models that run as unattended batch applications.  A simulation object is created to oversee each model run.  The simulation object manages most file input and output. Text file inputs and outputs are used primarily, for portability.   A simulation object obtains the run name from the command line.  At the start of model execution, the simulation opens and manages reading of an initialization file (run name + “. gin”).   Simulations generate various standard output files.  These standard files are written to the same directory as the gin file and have the same name but different extensions (extensions “fin”, “tym”, “ro” and “err”).  

 

The simulation opens a temporal log file (run name + “.tym”) that remains open until simulation termination.  Various CRITTRZ objects, including logs,  are able to write entries to this tym file, with entries potentially including details of biological events, summaries of population states and test data. At normal termination, the simulation opens and manages writing of a file with information on the terminal state of the simulation (name + “.fin”).  The terminal state files are useful for biological analyses and correctness checking. 

 

The formats of the gin and fin files for a particular application are identical.    These files are organized into labeled, hierarchically structured text blocks.  Each block consists of or one or more lines.  The simulation block is outermost.  At the beginning, it contains simulation related information (for example, simulation name, time periods, random number initialization).   The simulation block then contains information blocks for one or more constituent populations.  Each population block normally includes parameter values for methods it employs, a key structure template used for periodic checks of subpopulation structural correctness, a list of subpopulations with keyindent representations of their internal organizations and possibly other data, a list of attributes (or data fields) for individuals currently present in the population and kinship records for population members.  A fin file can be converted readily to a gin file, should the user wish to extend a simulation run.

 

A single line of text in one of the CRITTRZ I/O files may be too long for convenient inspection.  Long, logically single, lines of text may be broken into several physical lines in I/O files by the use of a line continuation string, “[\]”.  Module texio, which handles most file input and output, automatically handles these line continuations.

 

Should a simulation abort on detection of an error condition, the simulation object writes an error file (run name + “.err”) with information on the time and location of the error and some messages regarding other circumstances. 

 

As a programming guideline, CRITTRZ classes should provide methods for any file input and output that they require. 

 

At times, CRITTRZ classes may require I/O of extensive, possibly binary,  data that are not sensibly placed a standard CRITTRZ file.  One approach to such cases is input and output of these data via separate files, with the name of the separate file indicated in gin and fin files.  For example, at the end of each run, the rv random number generator library module saves its internal state by writing a table of values to a file with extension ‘ro’ ( run name + “ro”).  Rather than write this table into the fin file, the fin file simply contains a tagged line with the name of the ro file.  Should one wish to extend a simulation run, by converting its fin file to a gin file, on restart, CRITTRZ will automatically locate and read the ro file and use its contents to initialize the random number generator for the extension of the run.

 

Module pathserver provides each simulation with a mechanism for locating and naming input and output files other than previously discussed standard files.  These other files are referred to as auxiliary files in the remainder of this document.  Several considerations led to creation of patherserver: 1) increasing use of application-specific GIS files to store information on model landscape states 2) need to dynamically create data files related to subpopulations that appear during simulations 3) wish to specify input and output files in standard locations by name, without use of full pathnames.

 

By default,  pathserver looks for auxiliary files in the same directory as standard files.  An optional directory field in gin files allows the user to specify that auxiliary files will be found in a subdirectory (“auxstuff”) of the standard file directory or be stored in a subdirectory with a name derived by pathserver from the simulation name.   Input file names may be specified as entries in gin files with only file names and extensions.  When read, pathserver appends a file name to an auxiliary file path based on the simulation directory option.  To support creation of new files during a simulation, pathserver methods can generate new file names that include substrings derived from combinations of simulation, population and subpopulation names. 

 

 

Discussion of CRITTRZ Packages, Modules and Classes

 

CRITTRZ is structured as a Python package, with subpackages built of Python modules.  The packages are organized hierarchically and follow the structure of the CRITTRZ directory.  The use of packages permits firmer control of module importations and facilitates coexistence of different versions of CRITTRZ on a single computer. 

 

A brief explanation of some interrelationships between modules follows.  Although tedious, this discussion should be useful to anyone who wishes to examine kit code.

 

Module CRITTRZ_labels, found in the CRITTRZ package directory, assigns values to variables that are used as constants widely throughout the CRITTRZ system.  

 

Next, I consider modules found in the mods subpackage. Module simulation defines a simulation class that manages much file input and output, manages the progression of time periods and oversees error handling.  A pathserver object is embedded in each simulation object.  By convention, population objects are created as attributes of simulation instances.

 

Module base_popframe defines base classes for population and subpopulation frameworks.  Embedded in base_popframe class instances are objects that manage the assignment of unique identification numbers to simulated individuals, groups and other subpopulation elements (module idnserver), maintain a database on attributes of individuals present (module indfieldserver), maintain a database on parent-offspring links (module kinshipserver) and test structural correctness of subpopulations (modules template, templateserver and keystring).   Instances of class base_subpopframe each contain an instance of class keygraph (module keygraph).   Keygraphs store subpopulation key structural information using Python dictionaries and provide many tools for deterministic manipulation of the structures.  Module keyindent provides a means of convenient file input and output of key structures, using the indented text block format.

 

Module agesex defines classes agesex_popframe and agesex_subpopframe.  These are derived from counterparts in module base_popframe and add some handling for populations with age structuring and male and female sexes.

 

Modules geo, geoidrisi and idripop support modeling space and landscape features by providing an interface to the Idrisi GIS.  Modules raster_idrisi and home_range_idrisi also support use of  Idrisi GIS raster files to represent states of landscapes occupied by simulated populations, but do not require presence of Idrisi software.

 

Turning to biological events, module survival models survival, with probabilities fixed by age and sex.  Module reproduction models reproduction, with reproduction rates fixed by female age.  Poisson and binomial birth distribution models are provided.  Modules survival_dd and reproduction_dd provide density dependent versions of these events.  Modules survival_dd_idrisi and reproduction_dd_idrisi provide density dependent modeling of these events, with resources that influence survival and reproduction obtained from GIS rasters of subpopulation locations and resource distributions.  

 

Module migration models a random migration process, with no spatial structuring.  Module migration_idrisi uses a GIS raster representation of a cost-of-movement surface to model migration with distance effects.   Diploid inheritance (module diploid) and sexually transmitted diseases (module stdoffspring) also are modeled.  Module infection, provides a more general and basic representation of infectious disease processes.   Module diploidanalyst provides some tools for analyses of gene frequency distributions in subpopulations.

 

Fissions of subpopulation group elements are modeled by modules keyfission and linfission.  The latter divides a subpopulation or group element along unilineal, genealogical lines (for example, along matrilines).  Linfission requires that the population framework on which it acts be equipped with a uniline kinship data manager. Class uniline is derived from class kinshipserver and adds the ability to trace unilineal pedigree relationships through males or females.  Module uniline in turn employs classes in modules squarematrix and unimat.  Module femfounders traces descent of simulated individuals from females present in the population at the start of simulation

 

Some utility modules are used widely by other CRITTRZ components.   Module texio provides many functions for input, output and other processing of textual information, particularly lines labeled with tag identifiers.  Module log provides machinery for writing labeled entries in text logs.  Entries to log files are written in Python dictionary format.  Python scripts can easily read and analyze log contents; people can read logs as well, though perhaps not so easily.  Biological event modules generally contain embedded log objects that can be turned on to write data for code testing or analyses of simulated biological events.   Module tally provides methods for tallying individual field values in the entire population, subpopulation or elements of subpopulations.  Module tally is a useful foundation class for the construction of objects that statistically summarize population states.  CRITTRZ uses the “rv” random number generating package by Frohne (1998).  Module randy provides a light wrapper to the rv package. .

 

Modules in the cercomm subpackage directory (cercomm_fission, cercomm_fusion, cercomm_migration, cercomm_diploidanalyst, cercomm_popframe, cercomm_dd_events_idrisi) provide components for models of populations of Old World cercopithecine monkeys with multi-male groups.  These cercomm modules are built using extensions and combinations of more basic CRITTRZ modules.

 

The tools subpackage includes demograteplay, a script that allows exploration of population growth given fixed, age-specific survival and birth rates.  The  harness_base tool provides a Python class that can serve as a foundation for creation of scripts that oversee conduct of simulation run series.  Tool seedset uses the built-in Python random number generator, with initialization from the computer hardware state, to create a file with a list of random numbers.  Seedset output files are used to seed the random number generator for the different runs in simulation series overseen by scripts built with the harness_base tool.  Tool demogratedd deterministically models density dependent population growth.  Tool dd_extract, extracts population size data from tym files and exports them to comma-delimited files.

 

Classes and methods in CRITTRZ modules generally have been written with internal “docstrings”.   These docstrings provide brief comments on the function of the class or method and are accessible within the Python interpreter.   I have tried to use descriptive names for most classes and methods and in many cases the names of classes and methods are about as informative as the current docstrings.

 

Installation

 

Three compressed distribution files are available for CRITTRZ Version 0.7.5.  CRITTRZ.0.7.5.Win.zip and CRITTRZ.0.7.5.WinIdr.zip  are intended for installations on computers running the Windows operating system.  CRITTRZ.0.7.5.Lin.tar.gz, is intended for installation on computers running the Linux operating system.  Files CRITTRZ.0.7.5.Win.zip and CRITTRZ.0.7.5.Lin.tar.gz  contain core modeling files and are nearly identical in content.  They differ in that scripts in the Windows file are of the batch type and scripts in the Linux file are bash shells and may vary slightly in name.  Also, end of line characters in text files differ in accordance with host operating system conventions.  CRITTRZ.0.7.5.WinIdr.zip includes files present in CRITTRZ.Win.0.7.5.zip plus others that provide a run-time interface to the Idrisi GIS or use Idrisi raster files directly.  Use of this interface requires installation on the computer of a recent version of the Idrisi GIS. Idrisi is sold by Clark Labs (2003; http://www.clarklabs.org/) and runs only on computers with the Windows operating system.   CRITTRZ 0.7.5 has been developed using the Kilimanjaro version of Idrisi.  It has not yet been tested with the more recent Andes Idrisi release. The WinIdr distribution file also includes additional example programs that make use of the Idrisi interface and related script and input files.  The terms ‘Win’, ‘Lin’ and ‘WinIdr’ are used  elsewhere in this document to refer to these different distribution files or their resultant installations.

 

Using Windows Distribution Files

 

At present, CRITTRZ is intended for use on computers running Microsoft Windows 2000 and Windows XP operating systems.  Running CRITTRZ requires presence of a Python interpreter, preferably version 2.3 (downloadable at http://www.python.org/).  In addition to requiring installation of a recent version of the Idrisi GIS, use of the WinIdr distribution file with the Idrisi interface also requires installation of Mark Hammond’s “Python for Windows Extensions” (Hammond, 2004; downloadable at http://sourceforge.net/projects/pywin32).   This package contains an integrated development environment (a combination editor, debugger and console window) that CRITTRZ users may find helpful even if they do not run Idrisi-dependent modules.

 

CRITTRZ has been designed to allow flexible location of the package on file systems and coexistence of multiple versions on a single computer.  CRITTRZ can be installed as a top-level directory on a hard drive (e.g.  C:\CRITTRZ) or a subdirectory (e.g. C:\Models\CRITTRZ).

 

To install CRITTRZ, unzip the distribution file, specifying the directory in which you wish CRITTRZ installed, indicating that directories should be preserved. You must tell the Python interpreter where to look for CRITTRZ.  This can be accomplished by creating a user environment variable named PYTHONPATH in the control panel with value set to the directory in which CRITTRZ is installed (do not include ‘CRITTRZ’ at the end of this variable value).  If PYTHONPATH already exists, append the location of the CRITTRZ package to the end of it. 

 

Alternately, one can create a  “path file” in the directory in which the Python interpreter is installed.  Directories specified in a path file are added to the list of directories on the Python interpreter search path.   A text file named ‘CRITTRZ.pth’, containing one line with the directory in which CRITTRZ is installed has worked.  Note that path file syntax requires directories be indicated with double, rather than single, slashes.  If CRITTRZ is installed in directory “Models” on drive “C”, a CRITTRZ path file would contain the line “C:\\Models”.  See the Python documentation for additional discussion on making the Python interpreter aware of packages such as CRITTRZ.

 

Using the Linux Distribution File

 

CRITTRZ has been tested on a computer running the SuSE Version 9.0 Linux distribution and bash shell scripting.  In its current form, the author expects CRITTRZ to generally be compatible with other Linux distributions.  Running CRITTRZ requires presence of a Python interpreter, preferably version 2.3.  Many Linux distributions include Python.  Information on downloading a Python interpreter is available at http://www.python.org/.   Some download links are to interpreter source files that must be compiled and linked before use. You may find an RPM package built for your Linux distribution the most convenient means of installing Python, but you may have to look around to find one.

 

CRITTRZ has been designed to allow flexible location of the package on file systems and coexistence of multiple versions on a single computer.  You may find it convenient to install a CRITTRZ distribution in a subdirectory of your home directory ( for example ‘~/CRTZ’.

 

To install CRITTRZ, place the distribution file in the directory in which you wish the distribution installed.  Extract the distribution file using the tar command with ‘-xzf’ as options ( for example ‘tar –xzf CRITTRZ.0.7.5.Lin.tar.gz’ ).  At this point, the distribution files should be installed in expected subdirectories.

 

You must tell the Python interpreter where to look for CRITTRZ.  One way to do this is to create in each session  a PYTHONPATH shell variable set to the location in which the CRITTRZ distribution resides ( for example with command‘PYTHONPATH=~/CRTZ’ ) and then export the variable ( with command ‘export PYTHONPATH’ ).  Alternately, you can place a command in the ‘.bashrc’ configuration file in your home directory ( for example ‘export PYTHONPATH=~/CRTZ’ ).

 

Notes for All Distribution Files

 

CRITTRZ applications and data sets may reside outside of the CRITTRZ directory tree. 

 

The CRITTRZ distribution files contain a copy of the rv.py open source random number generating module, written by Frohne (1998).   This module and its documentation are located in the CRITTRZ\libs directory.

 

Sample Applications

 

Nine sample applications with inputs are provided in all distribution files; two more are present in the WinIdr file.  Scripts for execution of sample applications are found in package directory CRITTRZ\apps.  Before executing any of these scripts, open a command prompt or console window and use the change directory command to make the CRITTRZ\apps directory your current directory. To execute a Windows batch file, simply type its name at the command line.  To execute a Linux bash shell file, type ‘bash ‘ and the name of the shell on the command line.   Output from a simulation is generated in the same directory as the gin file for the application or its auxiliary data directory.  Remarks in the script files, displayed on the console at execution, note the files that contain distinctive output from each sample simulation.

 

The agesex_base application models a population with multiple subpopulations and age and sex structuring.  Migration event logging is turned on; output is contained in the application tym file. The agesex_base_dd application models a population with density-dependent survival and reproduction. Resources available to each subpopulation that influence survival and reproduction rates are read from the gin file.  Population sizes at each time period are displayed on the console and entered in the tym file. Application agesex_dd_idrisi also models a population with density-dependent survival and reproduction.  However, in this model, resources for survival and reproduction are determined from GIS raster files that represent landscape states.  The agesex_diploid application adds diploid genetics to the base agesex model.  The presence of genotype fields for individuals can be seen in the gin and fin files.  Test logging in the diploid genetics modeler is turned on, with detailed testing output present in the application tym file.  The agesex_STD application adds modeling of a sexually transmitted disease to the base agesex application.  A tally object is added to the population to summarize numbers of individuals infected and not infected in the population.  These tallys are displayed on the console as the simulation proceeds through time periods.  Application agesex_infection uses the infection module instead to model infectious disease transmission.  It too provides screen tallies of population member infection states but uses a more elaborate set of infection states.

 

The cercomm applications model a population of Old World monkeys divided into multimale social groups.  The base cercomm application logs group fission and fusion events in its tym file.  Comparison of gin and fin files reflects changes in groups present detailed in the group fission and fusion logs.   Application cercomm_diploid adds diploid genetics to the base cercomm model.  A tally object is created for the population and used to create subpopulation genotype counts that are written to the application tym file.  Application cercomm_base_dd models a monkey population with density dependent birth and survival events.   Derived fission and fusion classes in the application code manage allocation of demographically important resources during group fissions and fusions.  Application cercomm_dd_idrisi_app models a monkey population with density dependent birth and survival events,  using GIS analyses and rasters to assist in modeling population interactions with landscapes.  Population size numbers are written to the console and tym files.  The auxiliary data directory for the application contains rasters representing subpopulation home ranges, population resources and demand.    Home ranges may shrink, expand, shift, fission and fuse, in concert with population events.  Application two_pops presents a simulation with two distinct populations.  The gin and fin files illustrate some I/O formatting for a multi-population simulation.

 

Simply changing the random number generator seed value will produce different simulation results.  This value is set in the gin file on the line with the tag “[random_initialization_seed:]”  The number of time periods in a simulation run can be altered by changing the time limit value, in the gin file on the line with the tag “[time_limit:]”.

 

The base agesex and cercomm applications both use the survival and reproduction modules, though agesex uses the Poisson  birth model and the cercomm models use the binomial birth model.  Both applications use the migration module, though the in the cercomm application, migration is used as a foundation for a more complex and specialized cercomm_migration module.  The cercomm application adds group fission and fusion processes.  Note that in the applications using diploid genetics, the initialization of the main population class includes a parameter reference to a diploid genetic event modeling class.  In the main loop of these models, after births have occurred, a call is added to simulate gene transmission from parents to newborns.  In the agesex_STD application one sees, similarly, the addition of a disease modeling class to the parameter list for the population initialization method and a call to a disease transmission method in the main simulation loop, between reproduction and survival modeling.  Within the population initialization routines, one sees creation of instances of the event modeling classes and a binding of the population and event modeling instances to each other.  The cercomm_dd_idrisi_app makes use of multiple class inheritance for the migration event and population framework 

 

Perusal of the different application sources will reveal many similarities.  User developed applications could be structured similarly.

 

Three examples of simulation series scripts built with the harness_base tool are provided in directory harns in all distribution files.  They provide examples of 1) a basic agesex  model 2) an agesex model with density-dependent modeling of survival and reproduction 3) cercomm population simulations that include diploid gene transmission.  The WinIdr distribution includes  an agesex model using GIS representation of resources influencing density-dependent survival and reproduction, as well as migration affected by distance and costs of movement that vary  with location on the landscape.

 

A script for command line execution of the three harness scripts that do not require a GIS ( most_harness_examples.bat for the Win distribution installation; Lin_apps.sh for the Lin distribution ) is found in directory harns.  Before executing it, open a command prompt or console window and use the change directory command to make the harns directory your current directory.  In the WinIdr installation, script agesex_dd_idrisi_harness.bat executes the example that utilizes the Idrisi GIS.  Script call_dd_idrisi.bat is an auxiliary script used to invoke the Idrisi harness example and is not designed to run alone.

 

Console output from the agesex harnesses is minimal.    However, the density-dependent models record population sizes at different times in the run tym files.  The Idrisi-based density dependent harness model uses a base subdirectory to store raster files required for simulation runs.  These base directory files are copied by the harness to an auxiliary file directory, in keeping with the directory option specified in the example base gin file.

 

The cercomm harness application uses the diploidanalyst module to send FST gene frequency differentialion measures to the console.  Mean, minimum and maxium FST values for each simulation and for the series of simulations are provided. 

 

Note that the harness scripts and IO directories lies outside the CRITTRZ package directory structure.  This is done by design to allow relatively free location of harness scripts and IO within the user’s computer file system.

 

Development History and Plan

 

Design of CRITTZ began in August 2002, with coding begun in September 2002, with the intial public release in June 2004.  Version 0.7.5 is the sixth release of CRITTRZ.   This version presents essentially the full range of functions planned for Version 1.0.

An additional alpha test release is planned for later 2006 or early 2007.   In the new cercomm model that uses rasters to portray group locations and landscape conditions, nearly all migration is spatially structured.  However, a routine that checks for groups that have lost all adult males and directs migrants to them does not yet incorporate spatial effects.  In the next release, spatial effects will be added to the method that directs adult male migrants to groups lacking them. I also intend in the next release to test and adapt CRITTRZ to Python Version 2.4 and the new Version 15 Andes release of Idrisi.  Documentation of parameters of models and scripts to assist in tabulating event statistics from logs are planned.  A beta test release is now planned for mid-2007, with a release of version 1.0 later in the year. 

 

Starting in early 2003, CRITTRZ modules have been tested frequently using unit test modules and the PyUnit test harness (Purcell, 2001).  Unit tests greatly facilitated refactorings that occurred, particularly during earlier releases.

 

The remainder of this section offers miscellaneous further thoughts on changes and extensions that may be made in the future.

 

At present, CRITTRZ represents landscape states through an interface to a GIS system that runs only under Microsoft Windows operating systems.   With the addition of raster_idrisi and home_range_idrisi modules CRITTRZ can read, analyze, modify and write Idrisi raster files without use of the Idrisi GIS.  These modules might provide a basis for a tiny GIS within CRITTRZ that would support raster-based landscape modeling  in applications without need for calls to a separate GIS program.

 

The STD transmission module is a crude, simple experiment written only to illustrate the ability of CRITTRZ to incorporate models of infectious disease transmission.  It may be supplanted by derivations from the infection module.

 

At some point, replacement of the rv random number generator module with a generator written for the current version of Python may be needed.  CRITTRZ module randy wraps and isolates the random number generator, potentially simplifying the tasks involved in swapping generators.

 

Creation of a tool to extract simulation kinship link files from CRITTRZ is likely, so that stand-alone kinship analysis programs can analyze kinship relationships in simulated populations.

 

To date, only very simple two population models have been built, essentially equivalent to the sample two population application.  Construction of more elaborate two population models may reveal some limitations or flaws that need to be addressed.

 

The calculation of genealogical relationships by methods of module uniline slows rapidly  with increases in the number of individuals among which relationships are traced.  Unilineal relationships are traced, for example, as a prelude to group fissions in the cercomm models.  The matrix methods in module  squarematrix that are used by modules unimat and uniline are only slightly optimized.  No doubt, far more efficient implementations are possible.

 

Input consistency checks could be extended and messages on detection of some errors could be made more specific.

 

Many small code refinements are likely to be made in coming releases.  If you scan module source code, you will find comments that include ‘***’.   These indicate sections of code that are candidates for revision.  You also will find some module method docstrings contain the word ‘DEPRECATED’ (for example in module keygraph).   These methods may disappear in later versions and should not be used in new code.

 

Comments on potential extensions from readers are welcome.

 

Changes in this Version

 

Modules raster_idrisi, home_range_idrisi,  agesex_popframe_idrisi and cercomm_dd_events_idrisi have been added.

 

Application cercomm_dd_idrisi_app has been added. 

 

The optimal individual resources and power parameters  used for density dependent survival and reproduction have been combined in the existing agesex_base_dd_idrisi and new cercomm_dd_idrisi_app.  This integration is through use of classes in the new agesex_popframe_idrisi module.

 

Methods to delete matrix rows and columns were added to module squarematrix. 

 

A method to dispose of subpopulation properties was added to class agesex_subpopulation.  This is used to manage subpopulation raster files, such as those containing emigration cost surfaces in GIS based applications.

 

An option to delete subpopulation migration distance rasters after their use was added in module migration_idrisi.

 

The disperse_empty_natal_segment method in cercomm_migration classes has been modified to ensure dispersal of animals only to groups with nonempty segments if more than one group with an empty natal segment occurs at a particular time.

 

This documentation has been revised.

 

 

Acknowledgments

 

The author thanks his wife, Wren, for encouraging the development of CRITTRZ.  I also thank my son, David for prompting me to incorporate unit testing into the development process and for reviewing a draft of this documentation.

 

References

 

Clark Labs. 2003.  Idrisi Ver. 14.0 Kilimanjaro.  Worcester

 

Frohne, I. 1998.  rv.  Vers. 1.1  No known web download site now.  Copy of source and documentation included in CRITTRZ distribution zip file.

 

Hammond, M.  2004.  “Python for Windows Extensions”, also referred to as “pywin32”.  Home page at http://starship.python.net/crew/mhammond/win32.  Current download site at http://sourceforge.net/projects/pywin32.

 

Olivier, T.  J.  1984. “Some Issues in the abstraction of genetic structures of monkey societies.”  J. Social Biol. Struct.  7, 61-73.

 

Olivier, T. J.  1985.  “Use of Keyed Character String Data Structures and Operators in Models of Primate Gropus,”  J. Theor. Biol. 115, 539-549.

 

Olivier, T.J. 2003a.  “A Population Simulation System Written in Python.”  Paper presented to the PyCon Conference, Washington DC, 28 March 2003    www.python.org/pycon/papers/populationsim.html

 

Olivier, T.J. 2003b. “Design Goals and Application of a Simulation System for Conservation Biology.”  Poster presentation at the Society for Conservation Biology Meetings, 29 June – 2 July, 2003, Duluth, MN.  Link to PDF file at www.greencreekparadigms.com/CRITTRZ.htm.

 

Olivier, T.J. 2004.  “Interactions between Social, Genetic and Demographic Processes in Simulated Monkey Populations.”  Poster presentation at the Society for Conservation Biology Meetings, 29 July – 2 August, 2004, New York, NY.  .  Link to PDF file at www.greencreekparadigms.com/CRITTRZ.htm

 

Olivier, T.J. 2005. “Genetics and Population Dynamics of Matrilines in Simulated Monkey Populations.”  Oral presentation at the Society for Conservation Biology Meetings, 17 July,2005,  Brasilia, Brazil.  Link to HTML file at www.greencreekparadigms.com/CRITTRZ.htm.

 

Olivier, T.J. 2006.  “Experiences with Computer Simulations of Primate Populations.”  Oral presentation at NKS 2006 Wolfram Science Conference,  16 June, 2006, Washington, DC. www.wolframscience.com/conference/2006/presentations/materials/olivier.pdf

 

Purcell, S. 2001.  PyUnit Testing Framework. Ver. 1.4.1  Home page at http://pyunit.sourceforge.net.