Class Community¶
- Defined in File Community.h
Inheritance Relationships¶
Derived Type¶
public necsim::Metacommunity
(Class Metacommunity)
Class Documentation¶
-
class
Community
¶ A class to contain the tree object lineages and reconstructing the coalescence tree. Contains functions for calculating the number of species for a given speciation rate, outputting spatial data and generating species abundance distributions. Requires a link to the SQLite database from simulation output, and produces results within the same database file.
Subclassed by necsim::Metacommunity
Public Functions
Contructor for the community linking to Treenode list.
- Parameters
r
: Row of TreeNode objects to link to.
-
Community
()¶ Default constructor.
-
virtual
~Community
()¶ Default destructor.
Set the nodes object to the input Row of Treenode objects.
- Parameters
l
: the Row of Treenode objects to link to.
Sets up the community from a set of simulation parameters and the sqlite3 database connection.
- Return
- Parameters
sim_parameters
: parameters to use for setting up the communitydatabase
: points to the database object to open
Sets the database object for the sqlite functions.
- Parameters
dbin
: the sqlite3 input database.
-
bool
hasImportedData
()¶ Get the boolean of whether the data has been imported yet.
- Return
- true if database has been imported.
-
long double
getMinimumSpeciation
()¶ Get the minimum speciation rate the simulation was originally run with. This value is read in from the SIMULATION_PARAMETERS table in the database file.
- Return
- the minimum speciation rate.
-
void
importSamplemask
(string sSamplemask)¶ Imports the samplemask if it hasn’t already been imported.
- Parameters
sSamplemask
: the path to the samplemask file.
-
unsigned long
countSpecies
()¶ Counts the number of species that have speciated currently on the tree.
- Return
- the number of species
-
unsigned long
calculateCoalescenceTree
()¶ Calculate the number of species in the list for the parameters in the current_community_parameters object. This is the main function which reconstructs the coalescence tree. Each Treenode object will end having its existence value set correctly after a call to this function.
- Return
- the number of species present.
-
void
addSpecies
(unsigned long &species_count, TreeNode *treenode, set<unsigned long> &species_list)¶ Speciates TreeNode and updates the species count.
For systems which are not using a metacommunity, this function will just perform basic speciation.
- Note
- species_list is not updated in unless the function is overridden for metacommunity application.
- Parameters
species_count
: the total number of species currently in the communitytreenode
: pointer to the TreeNode object for this lineagespecies_list
: the set of all species ids.
-
void
calcSpeciesAbundance
()¶ Calculates the species abundance of the dataset. The species abundances will be with rOut after a call do this function. If a samplemask has been applied, only lineages which originally existed in the samplemask will be counted.
-
void
resetTree
()¶ Resets the entire tree. Sets existance to false, speciation to false and removes any species ID.
-
void
openSqlConnection
(string input_file)¶ Opens the connection to the sql database file Note that this imports the database to memory, so functionality should be changed for extremely large database files.
- Parameters
input_file
: the sql database output from a necsim simulation.
-
void
closeSqlConnection
()¶ Safely destroys the SQL connection.
-
void
setInternalDatabase
()¶ Opens a connection to an in-memory database. This will eventually be written to the output file.
-
void
internalOption
()¶ Internally sets the file referencing, data import and sql connection flags to true, for allowing checks to pass from internal object creation (so no external files are needed)
-
void
importData
(string inputfile)¶ Imports the data from the desired SQL database object into the array.
- Note
- Opens the sql connection if it has not already been opened.
- Note
- If nodes is not of length 0, this function does nothing. This is so that any in-memory data is not overwritten.
- Parameters
inputfile
: the path to the input SQLite database.
Sets the simulation parameters from a SimParameters object.
- Parameters
sim_parameters
: pointer to the SimParameters object to set from
Sets the speciation parameters from a SpecSimParameters object.
- Note
- Be careful of the difference between this function and setSimParameters (which sets the main simulation parameters).
- Parameters
spec_sim_parameters
: pointer to the SpecSimParameters object containing community speciation parameters
-
void
importSimParameters
(string file)¶ Imports the simulation parameters by reading the SIMULATION_PARAMETERS table in the provided file. This imports the grid_x_size, grid_y_size (which should also be the sample map dimensions) and the minimum speciation rate.
- Note
- Opens the sql connection if it has not already been opened.
- Note
- If bDataImport has already been set, no operation is performed.
- Parameters
file
: the sqlite database simulation output which will be used for coalescence tree generation.
-
void
forceSimCompleteParameter
()¶ Forces the sim_complete parameter to be true in SIMULATION_PARAMETERS. Used when speciating all remaining lineages to force a simulation to completion.
-
bool
isSetDatabase
()¶ Gets if the database has been set yet.
- Return
- true if the database is already set
-
void
getMaxSpeciesAbundancesID
()¶ Gets the maximum species abundance ID from the database and stores it in the max_species_id variable.
- Note
- Does not check for SPECIES_ABUNDANCES existence and will throw an error if it cannot access it
-
shared_ptr<vector<unsigned long>>
getCumulativeAbundances
()¶ Changes the rOut object so that values represent cummulative species abundances.
Allows binary sort on rOut (much faster) and the previous rOut value can be obtained by value = rOut[i] - rOut[i-1]
- Return
- pointer to sorted Row of species abundances
-
shared_ptr<vector<unsigned long>>
getRowOut
()¶ Returns the row_out object, which should contain species abundances or cumulative abundances.
- Note
- Does not recalculate species abundances, so if getCumulativeAbundances has been called, will return the cumulative species abundances instead.
- Note
- Returns a copy, so could cause problems for extremely large simulations with immense numbers of species.
- Return
- row_out, the species abundances, or the cumulative abundances if getCumulativeAbundances has been called
-
unsigned long
getSpeciesNumber
()¶ Gets the number of species in the most recent calculation.
- Return
- the number of species in the most recent calculation
-
void
getMaxFragmentAbundancesID
()¶ Gets the maximum fragment abundance ID from the database and stores it in the max_fragment_id variable.
- Note
- Does not check for FRAGMENT_ABUNDANCES existence and will throw an error if it cannot access it
-
void
getMaxSpeciesLocationsID
()¶ Gets the maximum species locations ID from the database and stores it in the max_locations_id variable.
- Note
- Does not check for SPECIES_LOCATIONS existence and will throw an error if it cannot access it
-
void
setProtractedParameters
(const ProtractedSpeciationParameters &protracted_params)¶ Sets the protracted parameters for application of protracted speciation.
This overloaded version is for setting protracted parameters before a full simulation has been outputted (i.e. immediately after completion of the simulation).
- Parameters
protracted_params
: protracted speciation parameters to add
-
void
overrideProtractedParameters
(const ProtractedSpeciationParameters &protracted_params)¶ Overrides the protracted parameters for the Community object.
- Parameters
protracted_params
: the protracted parameters to override with
-
void
setProtracted
(bool protracted_in)¶ Sets the protracted boolean to the input.
- Parameters
protracted_in
: the protracted boolean to set
-
void
createDatabase
()¶ Creates a new table in the database file and outputs the database object to the same file as the input file. Calculates the community structure for the set of community parameters in current_community_parameters.
The new SPECIES_ABUNDANCES table contains the species abundance distribution for the whole samplemask. A similar tabe FRAGMENT_ABUNDANCES is generated by createFragmentDatabase() if specified via the command line parameters.
-
void
generateBiodiversity
()¶ Calculates the coalescence tree and generates species abundances.
-
void
outputSpeciesAbundances
()¶ Outputs the species abundances into the database.
-
bool
checkCalculationsPerformed
(const long double &speciation_rate, const double &time, const bool &fragments, const MetacommunityParameters &metacomm_parameters, const ProtractedSpeciationParameters &proc_parameters)¶ Checks if calculations with the given set of parameters has already been performed.
- Return
- Parameters
speciation_rate
: the speciation rate to check fortime
: the time to check forfragments
: if true, checks fragments have been usedmetacommunity_size
: the metacommunity size to check formetacommunity_speciation_rate
: the metacommunity speciation rate to check forproc_parameters
: protracted speciation parameters to add
-
void
addCalculationPerformed
(const long double &speciation_rate, const double &time, const bool &fragments, const MetacommunityParameters &metacomm_parameters, const ProtractedSpeciationParameters &protracted_parameters)¶ Adds a performed calculation to the lists of calculations. Also sets the current_community_parameters pointer to the set of parameters to be applied.
- Parameters
speciation_rate
: the speciation rate of the performed calculationtime
: the time of the performed calculationfragments
: if true, fragments were usedmetacommunity_size
: the metacommunity size of the performed calculationmetacommunity_speciation_rate
: the metacommunity speciation rate of the performed calculationprotracted_parameters
: protracted speciation parameters to add
-
void
createFragmentDatabase
(const Fragment &f)¶ Creates a new table in the database file and outputs the database object to the same file as the input file. Essentially creates a species abundance distribution (as in createDatabase()), but for the specified fragment within the samplemask.
- Parameters
f
: the Fragment to sample from.
-
void
exportDatabase
()¶ Output the database from memory to the database file. Most of the time, it is desirable for the outputfile to be the same path as the input file and will write to the same object.
-
bool
checkSpeciesLocationsReference
()¶ Checks for the current CommunityParameters reference in the SPECIES_LOCATIONS table.
- Return
- true if the reference exists in the SPECIES_LOCATIONS table
-
bool
checkSpeciesAbundancesReference
()¶ Checks for the current CommunityParameters reference in the SPECIES_ABUNDANCES table.
- Return
- return true if the reference exists in the SPECIES_LOCATIONS table
-
void
recordSpatial
()¶ Record the full spatial data. Creates a new table, SPECIES_LOCATIONS containing every species and their parameters. This allows for more in-depth analysis to be performed if necessary.
-
void
calcFragments
(string fragment_file)¶ Calculates the limits of each fragment in the sample map and adds it to the vector of fragments. If the fragment_file is null, then the program will attempt to calculate fragments from the map.
- Parameters
fragment_file
: the fragment file to read from.
-
void
applyFragments
()¶ Calculate species abundances for each fragment, and call createFragmentDatabase() for each Fragment.
-
void
getPreviousCalcs
()¶ Gets the previous calculations that have already been performed.
-
vector<unsigned long>
getUniqueCommunityRefs
()¶ Gets the unique community references from the SQL database.
- Return
- a vector containing the unique references
-
vector<unsigned long>
getUniqueMetacommunityRefs
()¶ Gets the unique metacommunity reference from the SQL database.
- Return
- a vector containing the unique references
-
void
writeNewCommunityParameters
()¶ Write all performed calculations to the output database.
-
void
writeNewMetacommunityParameters
()¶ Write all performed calculations to the output database.
-
void
createSpeciesList
()¶ Creates a new table, SPECIES_LIST in the output database.
-
void
deleteSpeciesList
()¶ Drops the SPECIES_LIST table from the database.
-
void
writeSpeciesList
(const unsigned long &enddata)¶ Writes the coalescence tree to a table called SPECIES_LIST.
-
void
updateCommunityParameters
()¶ Updates the fragments tag on those simulations which now have had fragments added.
-
void
writeSpeciationRates
()¶ Prints speciation rates to terminal.
-
void
calculateTree
()¶ Calculates the coalescence tree for each set of parameters in speciation_parameters;.
-
void
output
()¶ Outputs the data to the SQL database.
-
void
printEndTimes
(time_t tStart, time_t tEnd)¶ Prints the application times.
- Parameters
tStart
: the start timetEnd
: the end time
Apply the given speciation parameters to the coalescence tree. Overridden for metacommunity application.
- Parameters
sp
: speciation parameters to apply, including speciation rate, times and spatial sampling procedure
Applies the given speciation parameters to the coalescence tree, but does not write the output.
- Parameters
sp
: speciation parameters to apply, including speciation rate, times and spatial sampling procedure
Applies the given speciation parameters to the coalescence tree, but does not write the output.
- Parameters
sp
: speciation parameters to apply, including speciation rate, times and spatial sampling proceduretree_data
: the coalescence tree containing simulation data
Sets up the community application by reading parameters and data.
- Parameters
sp
: the speciation parameters to use for generating the communitydata
: the list of all nodes on the coalescence tree
Creates the coalescence tree for the given speciation parameters.
- Parameters
sp
: speciation parameters to apply, including speciation rate, times and spatial sampling procedure
Creates the coalescence tree for the given speciation parameters.
- Parameters
sp
: speciation parameters to apply, including speciation rate, times and spatial sampling proceduredata
: the Row of TreeNodes that contains the coalescence tree.
Creates the coalescence tree for the given speciation parameters, using internal file referencing to avoid any actual file creation.
- Parameters
sp
: speciation parameters to apply, including speciation rate, times and spatial sampling proceduredata
: the Row of TreeNodes that contains the coalescence tree.
-
void
speciateRemainingLineages
(const string &filename)¶ Speciates the remaining lineages in an incomplete simulation to force it to appear complete.
-
unsigned long
getSpeciesRichness
(const unsigned long &community_reference)¶ Gets the species richness for the community reference from the database.
- Return
- the number of species
- Parameters
community_reference
: the community reference to obtain the species richness for
-
shared_ptr<map<unsigned long, unsigned long>>
getSpeciesAbundances
(const unsigned long &community_reference)¶ Gets the species abundances of the community.
- Return
- a map of species ids to species abundances
- Parameters
community_reference
: the reference of the desired community
-
shared_ptr<vector<unsigned long>>
getSpeciesAbundances
()¶ Gets the species abundance from the species_abundances internal object.
- Return
- the species abundances
-
bool
isDatabaseNullPtr
()¶ Check if the database is a null pointer.
- Return
- true if the database is a null pointer.
Protected Attributes
-
bool
in_mem
¶
-
bool
database_set
¶
-
shared_ptr<SQLiteHandler>
database
¶
-
bool
bSqlConnection
¶
-
shared_ptr<vector<unsigned long>>
species_abundances
¶
-
unsigned long
iSpecies
¶
-
bool
has_imported_samplemask
¶
-
bool
has_imported_data
¶
-
Samplematrix
samplemask
¶
-
shared_ptr<CommunityParameters>
current_community_parameters
¶
-
shared_ptr<MetacommunityParameters>
current_metacommunity_parameters
¶
-
long double
min_spec_rate
¶
-
unsigned long
grid_x_size
¶
-
unsigned long
grid_y_size
¶
-
unsigned long
samplemask_x_size
¶
-
unsigned long
samplemask_y_size
¶
-
unsigned long
samplemask_x_offset
¶
-
unsigned long
samplemask_y_offset
¶
-
CommunitiesArray
past_communities
¶
-
MetacommunitiesArray
past_metacommunities
¶
-
bool
protracted
¶
-
ProtractedSpeciationParameters
minimum_protracted_parameters
¶
-
ProtractedSpeciationParameters
applied_protracted_parameters
¶
-
unsigned long
max_species_id
¶
-
unsigned long
max_fragment_id
¶
-
unsigned long
max_locations_id
¶
-
shared_ptr<SpecSimParameters>
spec_sim_parameters
¶