Template Function fwdpp::ts::flag_mutations_for_recycling

• Defined in File recycling.hpp

Function Documentation

template<typename poptype, typename mutation_count_container, typename preserve_selected_fixations, typename record_fixations>
void fwdpp::ts::flag_mutations_for_recycling(poptype &pop, mutation_count_container &mcounts_from_preserved_nodes, const uint_t twoN, const uint_t generation, const preserve_selected_fixations preserve, const record_fixations record)

Mark mutations for recycling.

This function should be called immediately after simplification and mutation counting.

A mutation is marked for recycling if one of the following conditions holds:

1. The sum of pop.mcounts and mcounts_from_preserved_nodes is zero.

2. pop.mcounts == twoN, mcounts_from_preserved_nodes is zero, and record is std::false_type or the mutation is neutral.

Parameters

• pop: A mutation container

• mcounts_from_preserved_nodes: A container recording the counts of each mutation in ancient samples

• twoN: Twice the current population size

• generation: Current generation/time step in the simulation

• preserve: Policy for handling selected fixations. See below.

• record: Policy for recording fixation events. See below.

Condition 1 refers to extinct mutations and condition 2 refers to fixations.

When preserve is std::true_type, selected fixations are retained in the population. We do this because simulations of phenotypes (as opposed to relative fitness) require tracking the contribution of fixation to trait values.

All variants matching the above criteria have their record in pop.mcounts set to zero and their position is removed from pop.mut_lookup. Further, the mutation’s position in pop.mutations is set to std::numeric_limits<double>::max(), to signify an “invalid” mutation.

If record is std::false_type, no fixation recording takes place. However, if record is std::true_type, a record is entered into pop.fixations and pop.fixation_times. If preserve is also std::true_type, the recording is slightly more expensive because we have to guard against repeated recording. For this case, the fixations and fixation times containers in pop are kept sorted by fixation position.

An advanced use of this function is to create branchless code with respect to fixation handling. One can generate a closure wrapping this function with the desired values of preserve and record at the start of a simulation, thus avoiding a bunch of “if” statements prior to each call.

Todo:

Improve treatment of fixations by allowing for variants fixed in alive AND ancient samples to be flagged.

Return a recycling queue?

Note

There are several caveats to fixation recording (record == std::true_type). First, it is only as accurate as the time steps between simplifications is small. pop will only contain exact fixation times if simplification occurs every generation. The second limitation is that it will not give correct results if ancient samples are being tracked in a simulation. This has to do with a “todo” item for this function described below. Thus, fixation recording with this function should be considered limited to the case of regular simplification and no ancient sample preservation.

Warning

The preserve argument needs to be consistent with the desired behavior of ts::remove_fixations_from_gametes.

Version

0.7.0 Added to library

Version

0.7.1 Updated to change recycled mutation positions to max value of a double. Refactor API to take compile-time policies for fixation handling.