## The Events File

The events file controls events that need to occur throughout the course of a run. This includes the output of data files as well as active events that effect the population (such as extinction events or changes to the mutation rate). This is not a complete list, but should include all of the most used and useful events.

### File Formats

This file consists of a list of events that will be triggered either singly or periodically. The format for each line is:

type timing event arguments

The type determines what kind of timings the event will be based off of. This can be immediate [i], based on update [u], or based on generation [g].

The timing should only be included for non-immediate events. If a single number is given for timing, the event occurs at that update/generation. A second number can be included (seperated by a colon ':') to indicate how often the event should be repeated. And if a third number is listed (again, colon seperated) this will be the last time the event can occur on. For example, the type and timing "u 100:100:5000" would indicate that the event that follows first occurs at update 100, and repeats every 100 updates thereafter until update 5000. A type timing of "g 10:10" would cause the event to be triggered every 10 generations for the entire run.

The event is simply the name of the event that we want to trigger, and the arguments detail exactly how it should work when it is triggered. Each event has its own arguments.

Some examples:

`i pause` Pause avida as soon as the run first starts.
`u 100:100 print_average_data` Print out all average measurements collected every one hundred updates, starting at update 100.

`g 10000:10:20000 print_data dom_info.dat update,dom_fitness,dom_depth,dom_sequence`
Between generations 10,000 and 20,000, append the specified information to the file "dom_info.dat" every ten generations. Specifically, the first column in the file would be update number, second is the fitness of the dominant genotype, followed by the depth in the phylogentic tree of the dominant genotype, and finally its genome sequence.

### Types of events:

Output | Output events are the primary way of saving data from an avida experiments.
Analysis | Analysis events use data from the current state of avida, process it and then output the results.
Population | Population events modify the state of the population, and will actually change the course of the run.
Resource | Events that allow user to change amounts of resources in the system.
Miscellaneous |
Exit | Events that allow user to end the program.

### The available events are:

analyze_landscape
analyze_population
apocalypse
calc_consensus
calc_landscape
connect_cells
detail_parasite_pop detail_pop (deprecated)
disconnect_cells
dump_fitness_grid
dump_genotype_grid
dump_task_grid
dump_donor_grid
dump_receiver_grid
dump_historic_pop (deprecated)
dump_memory
dump_pop
echo
exit
exit_if_ave_lineage_label_larger
exit_if_ave_lineage_label_smaller
exit_if_generation_greater_than
exit_if_update_greater_than
genetic_distance_pop_dump
hillclimb
hillclimb_neut
hillclimb_rand
inject
inject_all
inject_random
inject_range
inject_range_pair
inject_range_parasite
inject_resource

inject_sequence
kill_rectangle
load_clone
load_dump_file
load_population
mod_copy_mut
mod_div_mut
mod_point_mut
pairtest_landscape
parasite_debug
predict_nu_landscape
predict_w_landscape
print_average_data
print_count_data
print_data
print_depth_histogram
print_detailed_fitness_data
print_divide_mut_data
print_dom
print_dom_parasite
print_dom_parasite_data
print_dominant_data
print_error_data
print_genetic_distance_data
print_genotype_abundance_histogram
print_genotype_map
print_genotypes
print_instruction_abundance_histogram
print_instruction_data
print_lineage_counts

print_lineage_totals
print_mutation_data
print_mutation_rate_data
print_number_phenotypes
print_resource_data
print_species_abundance_histogram
print_stats_data
print_tasks_data
print_tasks_exe_data
print_threads
print_time_data
print_totals_data
print_tree_depths
print_variance_data
print_viable_tasks_data
random_landscape
rate_kill
sample_landscape
save_clone
save_population
serial_transfer
set_copy_mut
set_point_mut
set_resource
set_reaction_value
set_reaction_value_mult
set_reaction_inst
sever_grid_col
task_snapshot
test_dom
test_size_change_robustness
test_threads
zero_muts

### Output Events

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_genotypes [data_fields("all")] [print_historic(0)] [filename("genotypes-<update>.dat")]
  This command is used to print out information about all of the genotypes in the population. It replaces both "detail_pop" and "historic_dump" as well as most of their variations. 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 other 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.
- detail_pop [filename]
  NOTE: This event is deprecated. See print_genotypes instead.
  Save the genotypes and lots of statistics about the population to the file specified; if not filename is given, use the name detail_pop.update#. 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. Ideally we will have a flexible version of this soon where the user will be able to specify the information that they are interested in saving.
- dump_historic_pop [filename]
  NOTE: This event is deprecated. See print_genotypes instead.
  This event is used to output all of the ancestors of the currently living population to the file specified, of "historic_dump.update#". It uses the same format as the "detail_pop" event.
- dump_genotype_pop
  Print out the grid of genotype IDs into idgrid.*.out", where '*' is replaced by the number of the current update.
- dump_task_grid
  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).
- dump_donor_pop
  Print out the grid of organisms who donated their merit into the "donor_grid.*.out", where '*' is replaced by the number of the current update.
- dump_donor_pop
  Print out the grid of organisms who received merit into the "receiver_grid.*.out", where '*' is replaced by the number of the current update.
- detail_parasite_pop [fname]
  Like dump_pop, but more detailed data is written out.
  Parameters:
  filename (string) default: "detail_pop.<update>" The name of the file into which the population dump should be written.
- genetic_distance_pop_dump [creature_name] [filename] [save_genotype(0)]
- load_clone [fname]
- load_dump_file [fname] [update(-1)]
  Sets up a population based on a dump file such as written out by detail_pop. It is also possible to append a history file to the dump file, in order to preserve the history of a previous run.
- load_population [fname]
  Loads the full state of the population.
  Parameters:
  filename (string) The name of the file to open.
- print_average_data [filename("average.dat")]
  A print_data shortcut that will print all of the population averages to the file "average.dat".
- print_count_data [filename("count.dat")]
  A print_data shortcut that will 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) to the file "count.dat".
- print_data [filename] [column list]
  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; click here for the complete list. See the last example above to see how this event can be put into use. 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.
- print_depth_histogram [filename("depth_histogram.dat")]
- print_detailed_fitness_data [save_max_f_genotype(0)] [print_fitness_histo(0)] [hist_fmax(1)] [hist_fstep(0.1)] [filename("fitness.dat")] [filename2("fitness_histos.dat")] [filename3("fitness_histos_testCPU.dat")]
- print_divide_mut_data [filename]
  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_dominant_data [filename("dominant.dat")]
  A print_data shortcut that will print all of the statistics relating to the dominant genotype to the file "dominant.dat".
- print_dom [filename]
  Print the dominant organism's genome (and lots of information about it) into the file specified. If no filename is given, just use the genotypes assigned name.
- print_dom_parasite [in_filename]
  Write the currently dominant injected genotype to disk.
  Parameters:
  filename (string) The name under which the genotype should be saved. If no filename is given, the genotype is saved into the directory genebank, under the name that the genebank has associated with this genotype.
- print_dom_parasite_data [filename]
  Print various quantites related to the dominant parasite to file "parasite.dat"
- print_error_data [filename]
  A print_data shortcut that will print all of the standard errors of the population statistics to the file "error.dat".
- print_genetic_distance_data [creature_name] [filename("genetic_distance.dat")]
- print_genotype_abundance_histogram [filename("genotype_abundance_histogram.dat")]
  Writes out a genotype abundance histogram.
  Parameters:
  filename (string) default: genotype_abundance_histogram.dat The name of the file into which the histogram is written.
- print_genotype_map [filename("genotype_map.m")]
  This event is used to ouput a map of the gentype IDs for the population grid to a file that is suitable to be read into Matlab. Default file name: genotype_map.m
- print_instruction_abundance_histogram [filename("instruction_histogram.dat")]
  Appends a line containing the bulk count (abundance) of each instruction in the population onto a file.
  Parameters:
  filename (string) default: "instruction_histogram.dat"
- print_instruction_data [fname("instruction.dat")]
  of the by-organisms counts of what instructions they _successfully_ beteween birth and divide. Prior to their first divide, organisms values for their parents.
- print_lineage_counts [fname("lineage_counts.dat")] [verbose(0)]
- print_lineage_totals [fname("lineage_totals.dat")] [verbose(1)]
- print_mutation_data [filename("mutation.dat")]
  Prints mutation information to file "mutation.dat"
- print_mutation_rate_data [filename("mutation_rates.dat")]
  Output (regular and log) statistics about individual copy mutation rates (aver, stdev, skew, cur) to "mutation_rates.dat".
  Useful only when mutation rate is set per organism.
- print_number_phenotypes [fname("phenotype_count.dat")]
  file with number of phenotypes based on tasks executed this update. Executing a task any numbers of times is considered same as executing it once.
- print_resource_data [filename("resource.dat")]
  Print the current counts of each resource available to the population to the file "resource.dat". 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_species_abundance_histogram [filename("species_abundance_histogram.dat")]
  Writes out a species abundance histogram.
  Parameters:
  filename (string) default: species_abundance_histogram.dat The name of the file into which the histogram is written.
- print_stats_data [filename]
  A print_data shortcut that will print all of the miscellanous population statistics to the file "stats.dat".
- print_tasks_data [filename("tasks.dat")]
  Print the number of organisms that are able to perform each task to the file "tasks.dat". This uses the environment configuration to determine what tasks are in use.
- print_tasks_exe_data [filename("tasks_exe.dat")]
  Print number of times the particular task has been executed this update to file "tasks_exe.dat"
- print_threads
- print_time_data [filename("time.dat")]
  A print_data shortcut that will print all of the timing related statistics to the file "time.dat".
- print_totals_data [filename("totals.dat")]
  A print_data shortcut that will print the same information as the previous event, but the counts will be the totals for the entire length of the run (for example, the total number of organisms ever) to the file "totals.dat".
- print_tree_depths [filename]
  Reconstruction of phylogenetic trees.
- print_variance_data [filename("variance.dat")]
  A print_data shortcut that will print all of the veriances of the population statistics to the file "variance.dat".
- print_viable_tasks_data [filename("viable_tasks.dat")]
- save_clone [filename]
  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.
- save_population [fname]
  Saves the full state of the population.
  Parameters:
  filename (string) default: save_pop.<update> The name of the file into which the population should be saved.

### Analysis Events

Analysis events use data from the current state of avida, process it (sometimes quite heavily) and then output the results. These are slowly migrating over to the analysis mode of avida (see the analysis documentation for more information).

- analyze_landscape [sample_size(1000)] [min_found(0)] [max_sample_size(0)]
- analyze_population [sample_prob(1)] [landscape(0)] [save_genotype(0)] [filename]
- calc_consensus [lines_saved(0)]
  Calculates the consensus sequence.
  Parameters:
  lines saved (integer) default: 0
- calc_landscape [distance(1)]
  Do a landscape analysis of the dominant genotype in the population and write the results to "landscape.dat". This is a collection of statistics obtained from examining all possible mutations at the distance specified. The default distance is one.
- hillclimb
  Does a hill climb with the dominant genotype.
- hillclimb_neut
- hillclimb_rand
- mod_copy_mut [cmut_inc] [cell(-1)]
- mod_div_mut [dmut_inc] [cell(-1)]
- mod_point_mut [pmut_inc] [cell(-1)]
- pairtest_landscape [sample_size(0)]
  If sample_size = 0, pairtest the full landscape.
- parasite_debug [in_filename]
- predict_nu_landscape [datafile("land-predict.dat")]
- predict_w_landscape [datafile("land-predict.dat")]
- random_landscape [landscape_dist(1)] [sample_size(0)] [min_found(0)] [max_sample_size(0)] [print_if_found(false)]
- sample_landscape [sample_size(0)]
- task_snapshot [filename]
  Run all organisms in the population through test cpus and print out the number of tasks each can perform. The default filename is "tasks_update#.dat".

### Population Events

Population events modify the state of the population, and will actually change the course of the run. There are a wide variety of these.

- apocalypse [kill_prob(0.9)]
  Using the specified probability, test each organism to see if it is killed off.
- inject [fname("START_CREATURE")] [cell_id(0)] [merit(-1)] [lineage_label(0)] [neutral_metric(0)]
  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.
- inject_all [fname("START_CREATURE")] [merit(-1)] [lineage_label(0)] [neutral_metric(0)]
  Same as inject, but no cell_id is specified and the organism is placed into all cells in the population.
- inject_random [length] [cell_id(-1)] [merit(-1)] [lineage_label(0)] [neutral_metric(0)]
  Injects a randomly generated genome into the population.
  Parameters:
  length (integer) [required] Number of instructions in the randomly generated genome.
  cell ID (integer) default: -1 The grid-point into which the genome should be placed. Default is random.
  merit (double) default: -1 The initial merit of the organism. If set to -1, this is ignored.
  lineage label (integer) default: 0 An integer that marks all descendants of this organism.
  neutral metric (double) default: 0 A double value that randomly drifts over time.
- inject_range [fname("START_CREATURE")] [start_cell(0)] [end_cell(-1)] [merit(-1)] [lineage_label(0)] [neutral_metric(0)]
  Injects identical organisms into a range of cells of the population.
  Parameters:
  filename (string) The filename of the genotype to load. If this is left empty, or the keyword "START_CREATURE" is given, than the genotype specified in the genesis file under "START_CREATURE" is used.
  start_cell (int) First cell to inject into.
  stop_cell (int) First cell *not* to inject into.
  merit (double) default: -1 The initial merit of the organism. If set to -1, this is ignored.
  lineage label (integer) default: 0 An integer that marks all descendants of this organism.
  neutral metric (double) default: 0 A double value that randomly drifts over time.
  Example:
  inject_range creature.gen 0 10 Will inject 10 organisms into cells 0 through 9.
- inject_range_pair [fname("START_CREATURE")] [fname_parasite("organism.parasite")] [start_cell(0)] [end_cell(-1)] [merit(-1)] [lineage_label(0)] [neutral_metric(0)] [mem_space(2)]
  Injects identical organisms into a range of cells of the population.
  Parameters:
  filename (string) The filename of the genotype to load. If this is left empty, or the keyword "START_CREATURE" is given, than the genotype specified in the genesis file under "START_CREATURE" is used.
  start_cell (int) First cell to inject into.
  stop_cell (int) First cell *not* to inject into.
  merit (double) default: -1 The initial merit of the organism. If set to -1, this is ignored.
  lineage label (integer) default: 0 An integer that marks all descendants of this organism.
  neutral metric (double) default: 0 A double value that randomly drifts over time.
  Example:
  inject_range creature.gen 0 10 Will inject 10 organisms into cells 0 through 9.
- inject_range_parasite [fname_parasite("organism.parasite")] [start_cell(0)] [end_cell(-1)] [merit(-1)] [lineage_label(0)] [neutral_metric(0)] [mem_space(2)]
  Injects identical organisms into a range of cells of the population.
  Parameters:
  filename (string) The filename of the genotype to load. If this is left empty, or the keyword "START_CREATURE" is given, than the genotype specified in the genesis file under "START_CREATURE" is used.
  start_cell (int) First cell to inject into.
  stop_cell (int) First cell *not* to inject into.
  merit (double) default: -1 The initial merit of the organism. If set to -1, this is ignored.
  lineage label (integer) default: 0 An integer that marks all descendants of this organism.
  neutral metric (double) default: 0 A double value that randomly drifts over time.
  Example:
  inject_range creature.gen 0 10 Will inject 10 organisms into cells 0 through 9.
- inject_sequence [seq] [start_cell(0)] [end_cell(-1)] [merit(-1)] [lineage_label(0)] [neutral_metric(0)]
  Injects identical organisms into a range of cells of the population.
  Parameters:
  sequence (string) The genome sequence for this organism. This is a mandatory argument.
  start_cell (int) First cell to inject into.
  stop_cell (int) First cell *not* to inject into.
  merit (double) default: -1 The initial merit of the organism. If set to -1, this is ignored.
  lineage label (integer) default: 0 An integer that marks all descendants of this organism.
  neutral metric (double) default: 0 A double value that randomly drifts over time.
  Example:
  inject_range ckdfhgklsahnfsaggdsgajfg 0 10 100 Will inject 10 organisms into cells 0 through 9 with a merit of 100.
- kill_rectangle [cell_X1(0)] [cell_Y1(0)] [cell_X2(0)] [cell_Y2(0)]
  Kill off all organisms in a rectangle defined by the points (X1, Y1) and (X2, Y2).
- rate_kill [kill_rate]
  Randomly removes a certain proportion of the population. In principle, this event does the same thing as the apocalypse 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.
  Parameters:
  removal rate (double) The rate at which organisms are removed.
- serieal_transfer [transfer_size(1)] [ignore_deads(1)]
  Similar to apocalypse, but we specify the exact number of organisms to keep alive after the event.
  Parameters:
  transfer size (int) default: 1 The number of organisms to retain. If there are fewer living organisms than the specified transfer size, then all living organisms are retained.
  ignore deads (int) default: 1 When set to 1, only living organisms are retained. Otherwise, every type of organism can be retained.
- set_copy_mut [cmut] [start_cell(-1)] [end_cell(-1)]
- set_point_mut [pmut] [cell(-1)]
- zero_muts
  This event will set all mutation rates to zero...

### Resource Events

Events that allow user to change resources and reaction parameters.
- inject_resource [res_name] [res_count]
  Inject (add) a specified amount of a specified resource. res_name must already exist as a resource in environment file.
- set_resource [res_name] [res_count]
  Set the resource amount to a specific level. res_name must already exist as a resource in environment file.
- set_reaction_value [reaction_name] [reaction_value]
  Set the reaction value ("bonus") to a specific level. reaction_name must already exist in the environment file. reaction_value can be negative.
- set_reaction_value_mult [reaction_name] [value_mult]
  Multiply the reaction value ("bonus") by the value_mult. reaction_name must already exist in the environment file. value_mult can be negative.
- set_reaction_inst [reaction_name] [inst_name]
  Set the instruction triggered by this reaction. reaction_name must already exist in the environment file. inst_name must be in the instruction set.

### Misc. Events

These are other events that didn't seem to fit better anywhere else...

- connect_cells [cellA_x] [cellA_y] [cellB_x] [cellB_y]
  Connects a pair of specified cells. Arguments: cellA_x, cellA_y, cellB_x, cellB_y
- echo [message]
  Print the message included when the event is triggered. This is mostly used for debugging.
- sever_grid_col [col_id(-1)] [min_row(0)] [max_row(-1)]
  Remove the connections between cells along a column in an avida grid. Arguments: col_id: indicats the number of columns to the left of the cut. default (or -1) = cut population in half min_row: First row to start cutting from default = 0 max_row: Last row to cut to default (or -1) = last row in population.
- test_dom
- test_size_change_robustness [num_trials(100)] [filename("size_change.dat")]
- test_threads

### Exit Events

These are events that cause the program to end.
- exit
  Quit the current run at given timing event.
- exit_if_ave_lineage_label_larger [lineage_label_crit_value]
  Halts the avida run if the current average lineage label is larger than lineage_label_crit_value.
- exit_if_ave_lineage_label_smaller [lineage_label_crit_value]
  Halts the avida run if the current average lineage label is smaller than lineage_label_crit_value.
- exit_if_generation_greater_than [max_generation]
  Ends the Avida run when the current generation exceeds max_generation.
- exit_if_update_greater_than [max_update]
  Ends the Avida run when the current generation exceeds max_update.

Project hosted by: