Class Tree¶
- Defined in File Tree.h
Inheritance Relationships¶
Derived Types¶
public necsim::ProtractedTree
(Class ProtractedTree)public necsim::SpatialTree
(Class SpatialTree)
Class Documentation¶
-
class
Tree
¶ Main simulation class for performing a non-spatial neutral simulation and generating the phylogenetic tree of the individuals.
Subclassed by necsim::ProtractedTree, necsim::SpatialTree
Public Functions
-
Tree
()¶
-
virtual
~Tree
()¶
-
void
importSimulationVariables
(const string &configfile) Import the simulation variables from the command line structure.
This function parses the simulation variables, imports them from the config file, checks that the input files exist and checks for any paused simulations. The flags are then set correctly, meaning that setup() and runSimulation() can be run immediately afterwards.
- Parameters
configfile
: the path to the config file containing parameters to parse.
-
void
importSimulationVariables
(ConfigParser config) Import the simulation variables from a ConfigOption.
This function parses the simulation variables, imports them (from either the command line or a config file), checks that the input files exist and checks for any paused simulations. The flags are then set correctly, meaning that setup() and runSim() can be run immediately afterwards.
- Parameters
config
: the set of config parameters to import
-
void
runFileChecks
() Runs the basic file existence checks. Checks for paused simulations and file existence.
-
void
wipeSimulationVariables
() Resets all the simulation variables.
Sets up the simulation parameters from the one provided.
Intended for usage with metacommunity application. No output directory is expected.
- Parameters
sim_parameters_in
: the simulation parameters to set up the simulation with
-
bool
checkOutputDirectory
() Asserts that the output directory is not null and exists. If it doesn’t exist, it attempts to create it.
- Return
- true if output creates successfully
- Exceptions
Fatal_Exception
: if the output directory creation fails
-
void
checkSims
() Checks for existing paused simulations to resume from Sets bPaused if there are.
This version uses the default values read from the config file.
-
void
checkSims
(string output_dir, long seed, long job_type) Checks for existing paused simulations to resume from.
Sets bPaused if there are.
This version uses the values supplied to the function directly
- Parameters
output_dir
: the output directory to check forseed
: the seed for paused simsjob_type
: the job_type for paused sims
-
void
setParameters
() Move the parameters from the sim_parameters object to their relevant parameters.
-
void
setProtractedVariables
(double speciation_gen_min, double speciation_gen_max) Sets the protracted variables.
- Parameters
speciation_gen_min
: the minimum number of generations to have passed before speciation is allowedspeciation_gen_max
: the maximum number of generations a lineage can exist for before it is speciated.
-
bool
hasPaused
() Gets the has_paused variable for resuming sims.
- Return
- if the simulation has paused
-
vector<double>
getTemporalSampling
() Gets the map autocorrel times.
-
long long
getSeed
() Getter for the simulation seed.
- Return
- Returns the seed
-
long long
getJobType
() Gets the job type for the simulation. This is a reference number for the jobs.
- Return
- Returns the job type
-
void
setSeed
(long long seed_in) Sets the simulation seed for the random number generator.
This function should only be called once.
The seed is set within the NR object. This will be fixed for the simulation and is only performed once.
- Parameters
seed_in
: the desired seed to set for the simulation
-
double
getGeneration
() const Gets the generation timer for the simulation.
- Return
- the number of generations that have passed
-
unsigned long
getInitialCount
() Gets the initial number of individuals.
- Return
- the number of initial individuals to simulate
-
unsigned long
setObjectSizes
() Sets the sizes of grid, active and data, based on the number of individuals counted from the samplemask.
- Return
- a count of the number of individuals that exist in the simulation
-
void
setup
() The setup function for generating the simulation objects.
The simulation parameters are set from comargs using setParameters(). Generates and fills the active and grid objects as well as importing all the maps from the supplied files.
-
void
setInitialValues
() Sets the starting values for required parameters.
-
void
setSimStartVariables
() Sets the variables at the start of a simulation for temporary data.
This is not the main set-up routine, which creates the permanent data structures including maps, the coalescence tree and active lineage listings.
-
void
printSetup
() Prints the statement for the setup initiation.
This is stored in a separate function so that it can be called in isolation by child classes.
-
void
setTimes
() Sets the temporal sampling points from the time config file.
-
void
determineSpeciationRates
() Determines the speciation rates to apply and then applies them to the coalescence tree post-simulation.
Detects speciation rates from the config files supplied.
-
void
addSpeciationRates
(vector<long double> spec_rates_in) Adds the speciation rates to those to be applied.
-
void
generateObjects
() Assigns the objects sizes in memory and fills with the starting lineages.
-
unsigned long
fillObjects
(const unsigned long &initial_count) Fills the active and data objects with the starting lineages.
- Parameters
initial_count
: the number of individuals expected to exist
-
void
runSingleLoop
() Runs a single loop of the simulation.
-
bool
runSimulation
() Run the entire simulation given the start conditions already defined by setup().
Setup is assumed to have been run already. This function is the main function containing the main loop of the simulation. At the end of the simulation, returns true if the simulation is complete, false otherwise.
- Return
- true if the simulation has completed
-
bool
runSimulationNoGillespie
() Runs the simulation using the standard coalescence algorithm.
- Return
- true if the simulation has completed
-
void
writeSimStartToConsole
() Writes to the console that the simulation is beginning.
-
void
writeStepToConsole
() Write the step counter to console. This function should only be called in debugging mode.
-
void
incrementGeneration
() Increments the generation counter and step references.
-
void
chooseRandomLineage
() Chooses a random lineage from active.
The index of the random lineage is stored in this_step, as chosen. Also records the required variables for the step process, like x, y position.
-
void
updateStepCoalescenceVariables
() Updates the coalescence variables in the step object.
-
void
speciation
(const unsigned long &chosen) Speciation to supplied lineage.
Also calls the removeOldPos() and switchPositions() functions for removing the lineage out of active reference.
- Parameters
chosen
:
-
void
speciateLineage
(const unsigned long &data_position) Performs the actual speciation.
- Parameters
data_position
: the position in the array of TreeNodes for this lineage
-
void
removeOldPosition
(const unsigned long &chosen) Removes the old position within active.
- Parameters
chosen
: the desired active reference to remove from the grid.
-
void
switchPositions
(const unsigned long &chosen) Switches the chosen position with the endactive position.
- Parameters
chosen
: the chosen lineage to switch with endactive.
-
void
calcNextStep
() Calculates the next step for the simulation.
-
bool
calcSpeciation
(const long double &random_number, const long double &speciation_rate, const unsigned long &no_generations) Calculates the speciation probability from the random number, speciation rate and number of generations a lineage has existed for.
- Return
- if true, speciation has occured
- Parameters
random_number
: the generated random number from 0-1speciation_rate
: the speciation rate to be appliedno_generations
: the number of generations a lineage has existed for
-
void
coalescenceEvent
(const unsigned long &chosen, unsigned long &coalchosen) Perform the coalescence between lineages. Once coalesced, lineages are removed from the active scope.
- Parameters
chosen
: the chosen lineage for coalescencecoalchosen
: the target lineage for coalscence
-
void
checkTimeUpdate
() Checks if the number of lineages should be expanded at another sample point.
-
void
addLineages
(double generation_in) Adds the required lineages at the generation time.
- Parameters
generation_in
: the generation to add lineages at
-
bool
checkProportionAdded
(const double &proportion_added) Randomly checks if a lineage should be added, based on the proportion added.
- Return
- true if the lineage should be added, false otherwise
- Parameters
proportion_added
: the proportion of lineages that should be added
-
void
checkSimSize
(unsigned long req_data, unsigned long req_active) Checks the size of the main active and data objects is large enough.
- Parameters
req_data
: the required data object sizereq_active
: the required active object size
-
void
makeTip
(const unsigned long &tmp_active, const double &generation_in, vector<TreeNode> &data_added) Sets the active reference to a tip, if it isn’t one already. Otherwise, creates a new tip for the new generation time.
- Parameters
tmp_active
: the reference in activegeneration_in
: the generation to set for the new lineagedata_added
: vector of lineages to add to data
-
void
convertTip
(unsigned long i, double generationin, vector<TreeNode> &data_added) Creates a new reference in data containing the tip with a new generation counter.
- Parameters
i
: the reference in active of the lineage to make a tipgenerationin
: the generation to make the lineage a tip atdata_added
: vector of lineages to add to the data object
-
bool
stopSimulation
() Finalises the simulation, and performs the correct tasks depending if the sim has been paused or finished.
- Return
-
void
applySpecRate
(long double sr, double t) Applies the given speciation rate to the tree.
- Parameters
sr
: the required speciation ratet
: the required time of speciation
-
void
applySpecRateInternal
(long double sr, double t) Applies the given speciation rate to the tree, but does not output to a file. Instead returns a pointer to the nodes object.
- Parameters
sr
: the required speciation ratet
: the required time of speciation
-
shared_ptr<vector<unsigned long>>
getCumulativeAbundances
() Gets the sorted cumulative species abundances from the contained TreeList.
For use with metacommunity applications
- Return
- row of cumulative species abundances
-
shared_ptr<map<unsigned long, unsigned long>>
getSpeciesAbundances
(const unsigned long &community_reference) Gets the species abundances from the internal tree.
- Return
- the species abundances
- Parameters
community_reference
: the community reference
-
shared_ptr<vector<unsigned long>>
getSpeciesAbundances
() Gets the species abundances from the internal tree.
- Return
- the species abundances
-
ProtractedSpeciationParameters
setupCommunity
() Sets up Community member to point to the same output database as the simulation.
- Return
- the protracted speciation parameters to set up
-
void
setupCommunityCalculation
(long double sr, double t) Sets up the generation of the tree object.
- Parameters
sr
: the required speciation ratet
: the required time of speciation
-
void
applySpecRate
(long double sr) Overloaded version of applySpecRates for the default generation (0.0).
- Parameters
sr
: the speciation rate to apply to the tree
-
void
applyMultipleRates
() Applies multiple speciation rates to the coalescence tree, ignoring repeated speciation rates.
Speciation rates are read from the speciation_rates object, which should have already been calculated.
-
bool
getProtracted
() Gets the protractedness of the simulation. Overridden by protracted child classes.
- Return
-
string
getProtractedVariables
() Gets the protracted variables and returns them as a single, newline separated string. This method is intended to be overridden in derived classes.
- Return
- string containing the protracted variables, separated by newlines.
-
double
getProtractedGenerationMin
() Gets the minimum number of generations a lineage must exist.
Without overriding this function, should always return 0.0.
- Return
- double the number of generations a lineage must exist
-
double
getProtractedGenerationMax
() Gets the maximum number of generations a lineage can exist.
Without overriding this function, should always return 0.0 (no maximum).
- Return
- double the number of generations a lineage must exist
-
void
sqlOutput
() Copy the in-memory database to file.
This function should not be called if the database is already opened on disc, and won’t do anything if it is.
-
void
createAndOutputData
() Creates the output data objects and outputs important simulation data to a database file.
-
void
outputData
() Outputs the simulation data (including the coalescence tree) to an sql database.
-
void
sortData
() Sort and process the species list so that the useful information can be extracted from it.
-
void
writeTimes
() Writes the times to the terminal for simulation information.
-
void
openSQLDatabase
() Opens a connection to the in-memory database, or the on-disk database, depending on the compilation options.
-
void
sqlCreate
() Generates the SQL database file from the full simulation data. This allows for greater analysis of the data after completion of the simulation.
-
void
setupOutputDirectory
() Creates the output directory, if it doesn’t already exist, and deletes any existing database with the output name.
-
void
sqlCreateSimulationParameters
() Creates the SIMULATION_PARAMETERS table in the SQL database.
-
string
simulationParametersSqlInsertion
() Creates a string containing the SQL insertion statement for the simulation parameters.
- Return
- string containing the SQL insertion statement
-
string
protractedVarsToString
() Outputs the protracted variables to a string.
This function is intended to be overridden by derived classes. It is intended the output is used for writing to SQL databases.
- Return
- string containing a list of the protracted speciation variables.
-
void
simPause
() Pause the simulation and dump data from memory.
-
shared_ptr<ofstream>
initiatePause
() Checks the output folder exists and initiates the pause.
- Return
- the output file stream to save objects to
Saves the main simulation variables to file.
- Parameters
out
: the output file stream to save the object to
Saves the active object to file.
- Parameters
out
: the output file stream to save the object to
Saves the data object to file.
- Parameters
out
: the output file stream to save the object to
Completes the pause routine and outputs the sql dump.
- Parameters
out
: the output stream to close up
-
void
setResumeParameters
(string pausedir, string outdir, unsigned long seed, unsigned long job_type, unsigned long new_max_time) Sets the resume variables so that the simulation can be resumed.
The pause directory can be the same as the output directory if it is desirable to save to the same location.
- Parameters
pausedir
: the directory containing the pause folder for resuming the simulationoutdir
: the directory to write simulation output toseed
: the simulation seedjob_type
: the simulation job reference numbernew_max_time
: the maximum simulation time to run for in seconds (0 keeps old simulation max time)
-
void
setResumeParameters
() Sets the resume variables to the defaults.
-
shared_ptr<ifstream>
openSaveFile
()
Loads the main simulation parameters from the save file into memory.
Loads the data object from the save file into memory.
Loads the active object from the save file into memory.
-
void
initiateResume
() Checks for resuming and prints to the terminal.
-
void
simResume
() Resumes the simulation from a previous state.
Reads in the parameters and objects from file and re-starts the simulation.
-
void
addGillespie
(const double &g_threshold)
-
bool
runSimulationGillespie
()
Protected Attributes
-
shared_ptr<vector<TreeNode>>
data
-
unsigned long
enddata
-
shared_ptr<SimParameters>
sim_parameters
-
shared_ptr<RNGController>
NR
-
vector<long double>
speciation_rates
-
bool
seeded
-
long long
seed
-
long long
job_type
-
string
times_file
-
vector<double>
reference_times
-
bool
uses_temporal_sampling
-
time_t
start
-
time_t
sim_start
-
time_t
sim_end
-
time_t
now
-
time_t
sim_finish
-
time_t
out_finish
-
time_t
time_taken
-
vector<DataPoint>
active
-
unsigned long
endactive
-
unsigned long
startendactive
-
unsigned long
maxsimsize
-
Community
community
-
long
steps
-
unsigned long
maxtime
-
double
generation
-
double
deme
-
double
deme_sample
-
long double
spec
-
string
out_directory
-
shared_ptr<SQLiteHandler>
database
-
bool
sim_complete
-
bool
has_imported_vars
-
Step
this_step
-
string
sql_output_database
-
bool
bFullMode
-
bool
bResume
-
bool
bConfig
-
bool
has_paused
-
bool
has_imported_pause
-
bool
bIsProtracted
-
string
pause_sim_directory
-
bool
using_gillespie
-