# Class Metacommunity¶

## Class Documentation¶

class Metacommunity : public virtual necsim::Community

Generates a metacommunity using spatially implicit neutral simulations, which is used to draw individuals from a community.

Public Functions

Metacommunity()
~Metacommunity()
void setCommunityParameters(shared_ptr<MetacommunityParameters> metacommunity_parameters)

Sets the parameters for the metacommunity.

Parameters
• community_size_in: the number of individuals in the metacommunity
• speciation_rate_in: the speciation rate to use for metacommunity creation
• database_name_in: the path to the database to store the metacommunity in
• metacommunity_option_in: the metacommunity option, either “simulated”, “analytical” or a path to a file
• metacommunity_reference_in: the metacommunity reference in the input metacommunity database

void checkSimulationParameters()

Gets the seed and the job_type from the SIMULATION_PARAMETERS database and stores them in the relevant variables.

Note
Should only be called once, and will have no effect if called multiple times.

void addSpecies(unsigned long &species_count, TreeNode *tree_node, set<unsigned long> &species_list)

Speciates TreeNode and updates the species count, including adding to the set of species ids, if a new species has been selected from the metacommunity.

Parameters
• species_count: the total number of species currently in the community
• tree_node: pointer to the TreeNode object for this lineage
• species_list: the set of all species ids.

void createMetacommunityNSENeutralModel()

Creates the metacommunity in memory using a non-spatially_explicit neutral model, which is run using the Tree class.

void applyNoOutput(shared_ptr<SpecSimParameters> sp, shared_ptr<vector<TreeNode>> tree_data)

Applies the speciation parameters to the completed simulation, including running the spatially implicit for the metacommunity structure, but doesn’t write the output.

Parameters
• sp: speciation parameters to apply, including speciation rate, times and spatial sampling procedure.

void approximateSAD()

Approximates the SAD from a NSE neutral model, based on Chisholm and Pacala (2010).

void readSAD()

Reads the SAD from the database provided in metacommunity_option. The database must exist and have a table called SPECIES_ABUNDANCES with the relevant community parameter.

void printMetacommunityParameters()

Prints the metacommunity parameters to the logger.

void setList(shared_ptr<vector<TreeNode>> l)

Set the nodes object to the input Row of Treenode objects.

Parameters
• l: the Row of Treenode objects to link to.

ProtractedSpeciationParameters setupInternal(shared_ptr<SimParameters> sim_parameters, shared_ptr<SQLiteHandler> database)

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 community
• database: points to the database object to open

void setDatabase(shared_ptr<SQLiteHandler> dbin)

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)

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

void setSimParameters(shared_ptr<SimParameters> sim_parameters)

Sets the simulation parameters from a SimParameters object.

Parameters
• sim_parameters: pointer to the SimParameters object to set from

void setSpecSimParameters(shared_ptr<SpecSimParameters> spec_sim_parameters)

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 for
• time: the time to check for
• fragments: if true, checks fragments have been used
• metacommunity_size: the metacommunity size to check for
• metacommunity_speciation_rate: the metacommunity speciation rate to check for
• proc_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 calculation
• time: the time of the performed calculation
• fragments: if true, fragments were used
• metacommunity_size: the metacommunity size of the performed calculation
• metacommunity_speciation_rate: the metacommunity speciation rate of the performed calculation
• protracted_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()

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 time
• tEnd: the end time

void apply(shared_ptr<SpecSimParameters> sp)

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

void applyNoOutput(shared_ptr<SpecSimParameters> sp)

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

void setupApplication(shared_ptr<SpecSimParameters> sp, shared_ptr<vector<TreeNode>> data)

Sets up the community application by reading parameters and data.

Parameters
• sp: the speciation parameters to use for generating the community
• data: the list of all nodes on the coalescence tree

void doApplication(shared_ptr<SpecSimParameters> sp)

Creates the coalescence tree for the given speciation parameters.

Parameters
• sp: speciation parameters to apply, including speciation rate, times and spatial sampling procedure

void doApplication(shared_ptr<SpecSimParameters> sp, shared_ptr<vector<TreeNode>> data)

Creates the coalescence tree for the given speciation parameters.

Parameters
• sp: speciation parameters to apply, including speciation rate, times and spatial sampling procedure
• data: the Row of TreeNodes that contains the coalescence tree.

void doApplicationInternal(shared_ptr<SpecSimParameters> sp, shared_ptr<vector<TreeNode>> data)

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 procedure
• data: 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

unsigned long seed
unsigned long job_type
bool parameters_checked
unique_ptr<SpeciesAbundancesHandler> species_abundances_handler
shared_ptr<RNGController> random
unique_ptr<Tree> metacommunity_tree
bool in_mem
bool database_set
shared_ptr<SQLiteHandler> database
bool bSqlConnection
shared_ptr<vector<TreeNode>> nodes
shared_ptr<vector<unsigned long>> species_abundances
unsigned long iSpecies
bool has_imported_samplemask
bool has_imported_data
Samplematrix samplemask
vector<Fragment> fragments
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