## 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.

### 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_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_average_data [filename]
  A print_data shortcut that will print all of the population averages to the file "average.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_variance_data [filename]
  A print_data shortcut that will print all of the veriances of the population statistics to the file "variance.dat".
- print_dominant_data [filename]
  A print_data shortcut that will print all of the statistics relating to the dominant genotype to the file "dominant.dat".
- print_stats_data [filename]
  A print_data shortcut that will print all of the miscellanous population statistics to the file "stats.dat".
- print_counts_data [filename]
  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_totals_data [filename]
  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_time_data [filename]
  A print_data shortcut that will print all of the timing related statistics to the file "time.dat".
- print_tasks_data [filename]
  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]
  ???? prints to tasks_exe.dat
- print_mutation_data [filename]
  ???? prints to mutation.dat
- print_mutation_rate_data [filename]
  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_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_resource_data [filename]
  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_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.
- 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.
- detail_pop [filename]
  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.
  Colums in the output are as follows:
  1) organism ID
  2) parent ID
  3) distance from parent
  4) current number of organisms
  5) total number of organisms
  6) lenght
  7) merit
  8) gestation time
  9) fitness
  10) update born
  11) update deactivated
  12) depth
  13) genome (as a string)
- dump_historic_pop [filename]
  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.
- print_genotype_map [filename]
  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

### 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).

- calc_landscape [distance]
  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.
- 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.

- inject [filename] [cell_id] [merit] [lineage_id]
  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 [filename] [merit] [lineage_id]
  Same as inject, but no cell_id is specified and the organism is placed into all cells in the population.
- apocalypse [kill_prob]
  Using the specified probability, test each organism to see if it is killed off.
- serieal_transfer [num_organisms]
  Similar to apocalypse, but we specify the exact number of organisms to keep alive after the event.
- kill_rectanle [X1] [Y1] [X2] [Y2]
  Kill off all organisms in a rectangle defined by the points (X1, Y1) and (X2, Y2).

### Resource Events

Events that allow user to change amounts of resources in the system.
- 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.

### Misc. Events

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

- echo [message]
  Print the message included when the event is triggered. This is mostly used for debugging.
- exit
  Quit the current run.
- 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.
- 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_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.

Project hosted by: