T cell simulation
version 0.17
Copyright (C) 2005 Dennis L. Chao


INSTRUCTIONS
------------

This program is designed to allow the user to set up a simulation run using 
a limited user interface, then run the simulation for the desired number of
time steps.  The progress of the run can be observed from within the 
program, which outputs data to stdout.  This data can be loaded into third-
party graphing software.


INITIALIZATION
--------------

After compiling the *.java source files, run driver/DriverView, which 
brings up an initialization screen.  There are several options you can 
set.  

For the random number seed, which is used to generate all random numbers in 
the simulation, can be set to "Random", which uses the system clock to 
generate a new seed, or "Specified", which allows the user to specify the 
random seed.  The option to "Reseed" will cause the simulation to choose a 
new random seed based on the system clock after the naive T cell repertoire 
is generated.  This is useful when you want to use the same repertoire for
multiple runs.

There are four options for T cell clones.  "One" creates a single high-
avidity clone of 50 cells.  "One big clone" creates a single high-avidity
clone of 50000 cells.  Two clones creates a high-avidity and a low-avidity
clone, both containing 50 cells.  "All clones" creates a full repertoire
of about 20 clones of various avidities, each with 10 cells.  The full 
repertoire is created using the random number generator, so it is 
dependent on the random number seed.

The number of epitopes expressed by infected cells can be set to "One" or
"Two".  If there are two epitopes, then T cell clones will be generated
for both according to the "Clones" options described above.  
The epitope expression density can be set to values between 0 and 1.  The 
stimulation that T cells receive from infected cells is proportional to
the number of infected cells times their epitope density.

The primary exposure to antigen can be a "Virus", which reproduces by 
infecting target cells, a "Vaccine", which is a virus that can infect
cells but can not reproduce, or a "Slow virus", which is a virus that
has a much lower reproductive rate.  The antigen dose size can be set
using the desired number.  The antigen is introduced to the system on
the beginning of day 0.

The secondary exposure options are the same as those for the primary
exposure with the addition of the "Variant virus", which is a virus
that expresses an epitope that is slightly different from that of the
primary.  The secondary exposure occurs on day 28.

The "Antibiotic" option, when checked, will eliminate all virus and
infected cells at hour 36.  Not a very useful option.  It was used to
produce one of the figures in the JTB paper.

The buttons in the "JTB" and "ICB" boxes will set the above options to
those used to produce the figures in these papers.  "JTB" refers to
"A stochastic model of cytotoxic T cell responses," and "ICB" buttons
are for "Modelling the impact of antigen kinetics on T-cell activation 
and response."  You can modify the options after hitting one of these
buttons if you wish.

When you push the "Ok" button, the simulation will start.  It may take
a few moments for the program to generate the T cell repertoire if the
"All clones" option was selected.


RUNNING THE PROGRAM
-------------------

The program outputs data to stdout.  Some information is output with
a "#" at the beginning of the line, while the numerical data is not.
This allows one to easily parse the data for graphing software - 
removing (or ignoring) all lines beginning with "#" will leave only
the raw time series data.  Each line of numerical data is space-
separated floating point numbers consisting of: the time in days,
the number of infected cells and the number of virus units for each
antigen, the numbers of T cells in each of the clones, and the average
avidity of all the T cell clones to the first antigen's first epitope.

The simulation run is controlled using the following buttons:

Go - Advances simulation time (and the state of the simulation) until 
"Stop" or "Step" are pressed.  If shown, the graph that displays the 
antigen levels will be continuously updated.  The simulation time, 
displayed below the controls in day:hour format, is also updated.

Step - Advances the simulation by a single time step of 10 minutes.

Inject - Injects antigen into the simulation.  A dialog allows the user
to choose which antigen to inject and the amount.  The first antigen 
choice is usually the one used for the primary exposure.  Thus, if you
are injecting a vaccine as the primary challenge followed by a viral
secondary challenge, the first choice is the vaccine and the second is
the virus.  Hitting "ok" adds the specified amount of antigen to the 
system.

Graph - Displays a graph that shows the levels of antigen and number of
T cells of each clone.

cjgraph - Outputs a "jgraph" file to plot in color the antigen levels and 
T cell numbers in the simulation.  The output file is called "cgraph.jgr".
jgraph is a program that produces PostScript plots.

bwjgraph - Outputs a "jgraph" file to plot in black and white the antigen 
levels and T cell numbers in the simulation.  The output file is called 
"bwgraph.jgr".

Map - Displays a plot that represents the antigenic distance relationships 
among the antigens and the T cell clones.  Distances between displayed 
items is proportional to their corresponding antigenic distances.  Antigens 
are X's surrounded by concentric circles representing iso-distance contours.  
The epitopes of multi-epitope antigens are connected by straight lines.  The 
bright outermost circle is the cross-reactive cutoff.  T cell clones are 
O's.  The sizes of the X's and O's are proportional to their population 
sizes.  Click on the individual symbols in the map to get more information 
about them.

Save - Outputs the state of the simulation to the file "savefile".  There 
is no "Load" function.  The save file is used by the batch-mode version 
(see below) for initialization.


BATCH-MODE VERSION
------------------

There is an alternate version of the simulation that runs without a user
interface.  It uses the savefile generated by the regular version for
initialization.  If you run the batch-mode version, it will produce 
results identical to the graphical version.  Even the stochastic events
will be identical.

To do this, run driver/DriverNoView.  It looks at the file "savefile"
for parameters.

