Return to the Index | The Events File | The Analyze File
There is a large library of actions available for scheduling as events. Additionally, all of these actions can be used within analyze scripts. Below you will find a listing of the high level groupings of these actions, along with detailed sections for each them.
For a brief overview of writing a new action, please see Creating an Action below.
Output events are the primary way of saving data from an Avida experiments. The main two types are continuous output, which append to a single file every time the event is trigged, and singular output, which produce a single, complete file for each trigger.
Print all of the population averages the specified file.
Print a count of the number of oraganisms belonging to a each coalescence clade currently in the population.
This action will only work in run mode.
This action will require TRACK_CCLADE to be enabled.
Print a histogram of fitnesses for each coalescence clade in the population.
This action will only work in run mode.
This action will rerequire TRACK_CCLADE to be enabled.
mode may be {CURRENT, ACTUAL, TESTCPU}, where
CURRENT uses the current phenotype value of fitness
Print a histogram of parent-relative fitness ratios for each coalescence clade in the population.
This action will only work in run mode.
This action will rerequire TRACK_CCLADE to be enabled.
mode may be {CURRENT, ACTUAL, TESTCPU}, where
CURRENT uses the current phenotype value of fitness
Print all of the standard errors of the average population statistics.
Print all of the variances of the average population statistics.
Print all of the statistics relating to the dominant genotype.
Print all of the miscellanous population statistics.
Print all of the statistics the keep track of counts (such as the number of organisms in the population or the number of instructions executed).
Print various totals for the entire length of the run (for example, the total number of organisms ever).
Print the number of organisms that are able to perform each task. This uses the environment configuration to determine what tasks are in use.
Print number of times the particular task has been executed this update.
Print the total quality of each task. By default a successful task is valued as 1.0. Some tasks, however, can grant partial values and/or special bonuses via the quality value.
Print the current counts of each resource available to the population. This uses the environment configuration to determine what resources are in use. Also creates seperate files resource_resource_name.m (in a format that is designed to be read into Matlab) for each spatial resource.
Print all of the timing related statistics.
Output (regular and log) statistics about individual copy mutation rates (aver, stdev, skew, cur). Useful only when mutation rate is set per organism.
Output (regular and log) statistics about individual, per site, rates divide mutation rates (aver, stdev, skew, cur) to divide_mut.dat. Use with multiple divide instuction set.
Print various quantites related to the dominant parasite.
Print the by-organisms counts of what instructions they _successfully_ executed beteween birth and divide. Prior to their first divide, organisms values for their parents.
This event is used to output a map of the genotype IDs for the population grid to a file that is suitable to be read into Matlab.
Print the number of phenotypes based on tasks executed this update. Executing a task any number of times is considered the same as executing it once.
Append to the file specified (continuous output), the data given in the column list. The column list needs to be a comma-seperated list of keywords representing the data types. Many possible data types can be output; see the complete listing for details. Note that this event will even create a detailed column legend at the top of your file so you don't need to seperately keep track of what the columns mean.
Appends a line containing the bulk count (abundance) of each instruction in the population onto a file.
Print the supplied message to standard output.
Writes out a genotype abundance histogram.
Writes out a species abundance histogram.
Print the dominant organism's genome (and lots of information about it) into the file specified. If no filename is given, the genotype's assigned name is used and the file is placed into the archive subdirectory.
Print the dominant parasite's genome (and lots of information about it) into the file specified. If no filename is given, the parasite's assigned name is used and the file is placed into the archive subdirectory.
Print a histogram of organism fitnesses in the current population.
This action will only work in run mode.
mode may be {CURRENT, ACTUAL, TESTCPU}, where
CURRENT uses the current phenotype value of fitness
Print a histogram of parent-relative fitness ratios for each coalescence clade in the population.
This action will only work in run mode.
mode may be {CURRENT, ACTUAL, TESTCPU}, where
CURRENT uses the current phenotype value of fitness
This function will take the initial genotype for each organism in the population/batch, align them, and calculate the per-site entropy of the aligned sequences. Please note that there may be a variable number of columns in each line if the runs are not fixed length. The site entropy will be measured in mers, normalized by the instruction set size. This is a population/batch measure of entropy, not a mutation-selection balance measure.
This function will provided detailed information about the phenotypic varients of the current population/batch by running each genome through a test cpu num_trials times. If this command is executed in run mode, the filename will be appeneded with -Update.dat where Update is the current update. In analyze mode, the default file is merely phenplast.dat. The output file contains the following: id, parent_id, phenotypic_varient_number, frequency, fitness, merit, gestation_time, and task counts for each phenotypic variant of each genotype.
This command is used to print out information about all of the genotypes
in the population. The file output from here can be read
back into the analyze mode of Avida with the LOAD command.
The data_fields parameter indicates what columns should be included in the file, which must be comma seperated. Options are: all, id, parent_id, parent2_id (for sex), parent_dist, num_cpus, total_cpus, length, merit, gest_time, fitness, update_born, update_dead, depth, lineage, sequence. Use all (the default) if you want all of the fields included.
The print_historic parameter indicates how many updates back in time should be included in this output. For example, '200' would indicate that any ancestor of the current population that died out in the last 200 updates should also be printed. A '-1' in this field indicates that all ancestors should be printed.
The filename parameter simply indicates what you want to call the file.
Example:
u 1000:1000 print_genotypes id,parent_id,fitness 1000
This will print out the full population every 1000 updates, including all
genotypes that have died out since the last time it was printed.
Run all organisms in the population through test cpus and print out the number of tasks each can perform.
Reconstruction of phylogenetic trees.
Dump memory summary information.
Print out the grid of organism fitness values.
Print out the grid of genotype IDs.
Print out the grid of takss that organisms do. For each organism, tasks are first encoded as a binary string (e.g. 100000001 means that organism is doing NOT and EQU and then reported as a base-10 number (257 in the example above).
Print out the grid of organisms who donated their merit.
Print out the grid of organisms who received merit.
Change the level of output verbosity. Verbose messages will print all
of the details of what is happening to the screen. Minimal messages
will only briefly state the process being run. Verbose messages are
recommended if you're in interactive analysis mode. When no arguments
are supplied, action will toggle between NORMAL and ON.
Levels: SILENT, NORMAL, ON, DETAILS, DEBUG
Population events modify the state of the population, and will actually change the course of the run. There are a wide variety of these.
Inject a single organisms into the population. Arguments must be included from left to right; if all arguments are left out, the default creature is the ancestral organism, and it will be injected into cell 0, have an uninitialized merit, and be marked as liniage id 0.
Injects a randomly generated genome of the supplied length into the population.
Same as Inject, but no cell_id is specified and the organism is placed into all cells in the population.
Injects identical organisms into a range of cells of the population.
Example:
InjectRange 000-aaaaa.org 0 10
Will inject 10 organisms into cells 0 through 9.
Injects identical organisms based on the supplied genome sequence into a range of cells of the population.
Example:
InjectSequence ckdfhgklsahnfsaggdsgajfg 0 10 100
Will inject 10 organisms into cells 0 through 9 with a merit of 100.
Attempt to inject a parasite genome into the supplied population cell range with the specified label.
Inject host parasite pairs into the population cell range specified.
Using the specified probability, test each organism to see if it is killed off.
Randomly removes a certain proportion of the population. In principle, this action does the same thing as the KillProb event. However, instead of a probability, here one has to specify a rate. The rate has the same unit as fitness. So if the average fitness is 20000, than you remove 50% of the population on every update with a removal rate of 10000.
Kill off all organisms in a rectangle defined by the points (x1, y1) and (x2, y2).
Similar to KillProb, but we specify the exact number of organisms to keep alive after the event. The ignore_deads argument determines whether only living organisms are retainted.
This event will set all mutation rates to zero.
Remove the connections between cells along a column in an Avida grid.
Remove the connections between cells along a row in an Avida grid.
Add connections between cells along a column in an Avida grid.
Add connections between cells along a row in an Avida grid.
Connects a pair of specified cells.
Disconnects a pair of specified cells.
Events that allow user to change environment properties, such as resources and reaction parameters.
Inject (add) a specified amount of a specified resource. res_name must already exist as a resource in environment file.
Set the resource amount to a specific level. res_name must already exist as a resource in environment file.
Set the reaction value to a specific level. reaction_name must already exist in the environment file. value can be negative.
Multiply the reaction value by the value. reaction_name must already exist in the environment file. value can be negative.
Set the instruction triggered by this reaction. reaction_name must already exist in the environment file. inst must be in the instruction set.
Save a clone of this organism to the file specified; if no filename is given, use the name clone.update. The update number allows regular clones with distinct filenames to be saved with the same periodic event. Running avida -l filename will start an Avida population with the saved clone. Note that a clone only consists of the genomes in the population, and their current state is lost, so the run may not proceed identically as to if it had continued as it was going.
Sets up a population based on a save file such as written out by SavePopulation. It is also possible to append a history file to the save file, in order to preserve the history of a previous run.
Save the genotypes and lots of statistics about the population to the file specified; if not filename is given, use the name detail-update.pop. As with clones, the update number allows a single event to produce many detail files. The details are used to collect crossection data about the population.
This action is used to output all of the ancestors of the currently living population to the file specified, or historic-update.pop.
Landscape analysis actions perform various types mutation studies to calculate properties of the fitness landscape for a particular genome. When scheduled as an event during a run, these actions will typically perform analysis on the dominant genotype. In analyze mode, analysis is performed on the entire currently selected batch.
These actions are often very computationally intensive, thus will
take a long time to compute. In order to take advantage of increasingly
available multi-processor/multi-core systems, a number of these actions
have been enhanced to make use of multiple threads to parallize work.
Set the configuration setting MT_CONCURRENCY to the number
of logical processors available to make use of all processor resources
for these compuations.
Precalculate the distance 1 full landscape for the current batch in parallel using multiple threads. The resulting data is stored into the current batch and can be used by many subsequent output commands within Analyze mode.
Do a landscape analysis of the dominant genotype or current batch of genotypes, depending on the current mode. The resulting output is a collection of statistics obtained from examining all possible mutations at the distance specified. The default distance is one.
Does a hill climb with the dominant genotype.
If sample_size = 0, pairtest the full landscape.
These actions control the driver object responsible for executing the current run.
Unconditionally terminate the current run.
Halts the run if the current average lineage label is larger than threshold.
Halts the run if the current average lineage label is smaller than threshold.
The action source code is contained in the source/action directory. Each of the individual action categories has its own source code files (e.g. Landcape Actions are located in the LandscapeActions files).
Each action is derrived from the cAction class. Briefly, to get an action to work you must create a child class that has a Process and GetDescription function defined as well as a constructor. You must also register this new class with the action library.
So, with that quick review of what must be done, here is a step by step guide to creating an action:
Create a new class in the file that follows proper naming conventions. Any class should begin with "cAction" and be followed by the name of the action command you will register with the library. For instance, if we were to create a new command "MyAction", we'd name the class cActionMyAction. Below is a stub for this new action class:
class cActionMyAction : public cAction
{
private:
// Private data members for this action
public:
cActionMyAction(cWorld* world, const cString& args) : cAction(world, args) { ; }
static const cString GetDescription() { return "Arguments: My Arguments"; }
void Process(cAvidaContext& ctx)
{
//Perform whatever processing is needed when the action is triggered.
}
};
Define the private data members, constructor, description string in GetDescription, and the Process function. Any arguments that you specify after the action name in the events configuration will be passed to your new class via the args argument in the constructor.
Register the new action with the action library. At the bottom of each action definitions file, there are the commands that register the individual actions with the action library. In the PrintActions.cc file, for instance, this function is called RegisterPrintActions.
To register our example action "MyAction", we'd write:
action_lib->Register<cActionMyAction>("MyAction");
Test your action.