SymWorld Class Documentation

class SymWorld : public emp::World<Organism>

Subclassed by EfficientWorld, LysisWorld, PGGWorld

Public Functions

inline SymWorld(emp::Random &_random, emp::Ptr<SymConfigBase> _config)

Input: The world’s random seed and a pointer to this world’s config object

Output: None

Purpose: To construct an instance of SymWorld

inline virtual ~SymWorld()

Input: None

Output: None

Purpose: To destruct the objects belonging to SymWorld to conserve memory.

inline emp::World<Organism>::pop_t GetPop()

Input: None

Output: The pop_t value that represents the world’s population.

Purpose: To get the world’s population of organisms.

inline emp::World<Organism>::pop_t GetSymPop()

Input: None

Output: The pop_t value that represent the world’s symbiont population.

Purpose: To get the world’s symbiont population.

inline void SetTagMetric(emp::Ptr<emp::BaseMetric<emp::BitSet<TAG_LENGTH>, emp::BitSet<TAG_LENGTH>>> _in)

Input: A pointer to the tag distance metric object

Output: None

Purpose: To set the world’s tag distance calculator

inline emp::Ptr<emp::BaseMetric<emp::BitSet<TAG_LENGTH>, emp::BitSet<TAG_LENGTH>>> GetTagMetric()

Input: None

Output: A pointer to the tag distance metric object

Purpose: To get the world’s tag distance calculator

inline emp::vector<emp::Ptr<Organism>> &GetGraveyard()

Input: None

Output: A reference to the world graveyard.

Purpose: To get the world’s graveyard.

inline const emp::Ptr<SymConfigBase> GetConfig() const

Input: None

Output: The configuration used for this world.

Purpose: Allows accessing the world’s config.

inline bool WillTransmit()

Input: None

Output: The boolean representing if vertical transmission will occur

Purpose: To determine if vertical transmission will occur

inline emp::Ptr<emp::Systematics<Organism, taxon_t::info_t, datastruct::HostTaxonData>> GetHostSys()

Input: None

Output: The systematic object tracking hosts

Purpose: To retrieve the host systematic

inline emp::Ptr<emp::Systematics<Organism, taxon_t::info_t, datastruct::SymbiontTaxonData>> GetSymSys()

Input: None

Output: The systematic object tracking hosts

Purpose: To retrieve the symbiont systematic

inline fun_calc_info_t GetCalcHostInfoFun()

Input: None

Output: The standard function object that determines which bin hosts should belong to depending on their interaction value

Purpose: To classify hosts based on their interaction value.

inline fun_calc_info_t GetCalcSymInfoFun()

Input: None

Output: The standard function object that determines which bin symbionts should belong to depending on their interaction value

Purpose: To classify symbionts based on their interaction value.

inline emp::Ptr<taxon_t::base_taxon_t> AddSymToSystematic(emp::Ptr<Organism> sym, emp::Ptr<taxon_t::base_taxon_t> parent_taxon = nullptr)

Input: The symbiont to be added to the systematic

Output: the taxon the symbiont is added to.

Purpose: To add a symbiont to the systematic and to set it to track its taxon

inline float PullResources(float desired_resources)

Input: The amount of resources an organism wants from the world.

Output: If there are unlimited resources or the total resources are greater than those requested, returns the amount of desired resources. If total_res is less than the desired resources, but greater than 0, then total_res will be returned. If none of these are true, then 0 will be returned.

Purpose: To determine how many resources to distribute to each organism.

inline void Resize(size_t new_width, size_t new_height)

Input: The size_t representing the world’s new width; the size_t representing the world’s new height.

Output: None

Purpose: To overwrite the Empirical resize so that sym_pop is also resized

inline void Resize(size_t new_size)

Input: The size_t representing the new size of the world

Output: None

Purpose: To override the Empirical Resize function with a single-arg method that can be used for AddOrgAt vector expansions

inline virtual void SendToGraveyard(emp::Ptr<Organism> org)

Input: An organism pointer to add to the graveyard

Output: None

Purpose: To add organisms to the graveyard (also sets it to dead)

inline void AddOrgAt(emp::Ptr<Organism> new_org, emp::WorldPosition pos, emp::WorldPosition p_pos = emp::WorldPosition())

Input: The pointer to the new organism; the world position of the location to add the new organism.

Output: None

Purpose: To overwrite the empirical AddOrgAt function to permit syms to be added into sym_pop

inline emp::WorldPosition DoBirth(emp::Ptr<Organism> new_org, emp::WorldPosition p_pos)

Input: (1) The pointer to the organism that is being birthed; (2) The size_t location of the parent organism.

Output: The WorldPosition of the position of the new organism.

Purpose: To introduce new organisms to the world.

inline void DoDeath(const emp::WorldPosition pos)

Input: The world position of the host to perform death upon

Output: None

Purpose: To overwrite the empirical DoDeath function to permit cleanup of false-start (<1 update duration) host taxa when unpruned trees are being recorded.

inline int GetNeighborHost(size_t id)

Input: The size_t value representing the location whose neighbors are being searched.

Output: If there are no occupied neighboring positions, -1 will be returned. If there are occupied neighboring positions, then the location of one occupied position will be returned.

Purpose: To determine the location of a valid occupied neighboring position.

inline void InjectHost(emp::Ptr<Organism> new_host)

Input: The pointer to a host that will be added to the world. This function assumes that the pop vector has not been resized to fit the world yet.

Output: None

Purpose: To add a host to the world.

inline void InjectSymbiont(emp::Ptr<Organism> new_sym)

Input: The pointer to an organism that will be injected into the world.

Output: None

Purpose: To add a symbiont to the world, either into a host or into a sym world cell.

virtual void CreateDataFiles()

Input: None.

Output: None.

Purpose: To create and set up the data files (excluding for phylogeny) that contain data for the experiment.

void MapPhylogenyInteractions()

Input: None.

Output: None.

Purpose: Helper function that makes map of all the symbiont taxa associated with each host taxon, (including counts of how common each interaction is)

void WritePhylogenyFile(const std::string &filename)

Input: The address of the string representing the suffixes for the files to be created.

Output: None.

Purpose: To setup and write to the files that track the symbiont systematic information and the host systematic information

void WriteOrgDumpFile(const std::string &filename)

Input: The address of the string representing the suffixes for the files to be created.

Output: None.

Purpose: To write the tags of hosts and symbionts to a data file after an experiment is concluded

emp::DataFile &SetupSymIntValFile(const std::string &filename)

Input: The address of the string representing the file to be created’s name

Output: The address of the DataFile that has been created.

Purpose: To set up the file that will be used to track the average symbiont interaction value, the total number of symbionts, the total number of symbionts in a host, the total number of free syms and set up a histogram of the symbiont’s interaction values.

emp::DataFile &SetupHostIntValFile(const std::string &filename)

Input: The address of the string representing the file to be created’s name

Output: The address of the DataFile that has been created.

Purpose: To set up the file that will be used to track host’s interaction values, the total number of hosts, the total number of colony forming units, and the histogram of the host’s interaction values. Prints header keys to the file.

emp::DataFile &SetupFreeLivingSymFile(const std::string &filename)

Input: The address of the string representing the file to be created’s name

Output: The address of the DataFile that has been created.

Purpose: To set up the file that will be used to track mean information about the free living symbionts in the world. This includes: (1) their total count, (2) the counts of the free and hosted symbionts, (3) the interaction values for the free and hosted symbionts, and (4) the infection chances from the total population, free symbionts, and hosted symbionts.

emp::DataFile &SetupReproHistFile(const std::string &filename)

Input: The address of the string representing the file to be created’s name

Output: The address of the DataFile that has been created.

Purpose: To set up the file that will be used to track mean information about the number of reproductions in the world.[ If tag matching is on, this file also tracks tag similarity / dissimilarity to parents / partners.

emp::DataFile &SetupTransmissionFile(const std::string &filename)

Input: The address of the string representing the file to be created’s name

Output: The address of the DataFile that has been created.

Purpose: To set up the file that will be used to track symbiont transmission

emp::DataFile &SetupTagDistFile(const std::string &filename)

Input: The address of the string representing the suffixes for the files to be created.

Output: None.

Purpose: To write the tag distances of host-symbionts over time.

virtual void SetupTransmissionFileColumns(emp::DataFile &file)

Input: The reference of the datafile which is being constructed.

Output: None.

Purpose: To setup the columns tracking symbiont transmission.

virtual void SetupHostFileColumns(emp::DataFile &file)

Input: The Empirical DataFile object tracking data nodes.

Output: None.

Purpose: To define which data nodes should be tracked by this data file. Defines what columns should be called.

emp::DataMonitor<int> &GetHostCountDataNode()

Input: None

Output: The DataMonitor<int>& that has the information representing the host count.

Purpose: To collect data on the host count to be saved to the data file that is tracking host count

emp::DataMonitor<int> &GetSymCountDataNode()

Input: None

Output: The DataMonitor<int>& that has the information representing the symbiont count.

Purpose: To collect data on the symbiont count to be saved to the data file that is tracking symbiont count

emp::DataMonitor<int> &GetCountHostedSymsDataNode()

Input: None

Output: The DataMonitor<double>& that has the information representing the count of the hosted symbionts.

Purpose: To collect data on the count of the hosted symbionts to be saved to the data file that is tracking the count of the hosted symbionts.

emp::DataMonitor<int> &GetCountFreeSymsDataNode()

Input: None

Output: The DataMonitor<double>& that has the information representing the count of the free symbionts.

Purpose: To collect data on the count of the free symbionts to be saved to the data file that is tracking the count of the free symbionts.

emp::DataMonitor<int> &GetUninfectedHostsDataNode()

Input: None

Output: The DataMonitor<int>& that has the information representing the count of the uninfected hosts

Purpose: To collect data on the count of the uninfected hosts to be saved to the data file that is tracking the count of the uninfected hosts.

emp::DataMonitor<double, emp::data::Histogram> &GetHorizontalTransmissionAttemptCount()

Input: None

Output: The DataMonitor<double,emp::data::Histogram>& that has the information representing how many attempts were made to horizontally transmit.

Purpose: To retrieve the data nodes that is tracking the number of attempted horizontal transmissions.

emp::DataMonitor<double, emp::data::Histogram> &GetHorizontalTransmissionTagFailCount()

Input: None

Output: The DataMonitor<double,emp::data::Histogram>& that has the information representing how many horizontal transmissions failed ONLY due to tag mismatch.

Purpose: To retrieve the data nodes that is tracking how many horizontal transmissions failed ONLY due to tag mismatch.

emp::DataMonitor<double, emp::data::Histogram> &GetHorizontalTransmissionSizeFailCount()

Input: None

Output: The DataMonitor<double,emp::data::Histogram>& that has the information representing how many horizontal transmissions failed ONLY due to insufficient space in the host.

Purpose: To retrieve the data nodes that is tracking how many horizontal transmissions failed ONLY due to insufficient space in the host

emp::DataMonitor<double, emp::data::Histogram> &GetHorizontalTransmissionSuccessCount()

Input: None

Output: The DataMonitor<double,emp::data::Histogram>& that has the information representing how many successful attempts were made to horizontally transmit.

Purpose: To retrieve the data nodes that is tracking the number of successful horizontal transmissions.

emp::DataMonitor<double, emp::data::Histogram> &GetVerticalTransmissionAttemptCount()

Input: None

Output: The DataMonitor<double,emp::data::Histogram>& that has the information representing how many attempts were made to vertically transmit.

Purpose: To retrieve the data nodes that is tracking the number of attempted vertical transmissions.

emp::DataMonitor<double, emp::data::Histogram> &GetVerticalTransmissionSuccessCount()

Input: None

Output: The DataMonitor<double,emp::data::Histogram>& that has the information representing how many successful attempts were made to vertically transmit.

Purpose: To retrieve the data nodes that is tracking the number of successful vertical transmissions.

emp::DataMonitor<size_t> &GetHostReproCountDataNode()

Input: None

Output: The DataMonitor<size_t>& that has the information representing the average number of reproductions each host lineage has accumulated.

Purpose: To retrieve the data nodes that is tracking the average number of reproductions each host lineage has accumulated.

emp::DataMonitor<size_t> &GetSymReproCountDataNode()

Input: None

Output: The DataMonitor<size_t>& that has the information representing the average number of reproductions each symbiont lineage has accumulated.

Purpose: To retrieve the data nodes that is tracking the average number of reproductions each symbiont lineage has accumulated.

emp::DataMonitor<double> &GetSymTowardsPartnerRateDataNode()

Input: None

Output: The DataMonitor<double>& that has the information representing the average number of flips towards a partner each symbiont lineage has accumulated.

Purpose: To retrieve the data nodes that is tracking the average number of flips towards a partner each symbiont lineage has accumulated.

emp::DataMonitor<double> &GetSymFromPartnerRateDataNode()

Input: None

Output: The DataMonitor<double>& that has the information representing the average number of flips from a partner each symbiont lineage has accumulated.

Purpose: To retrieve the data nodes that is tracking the average number of flips from a partner each symbiont lineage has accumulated.

emp::DataMonitor<double> &GetHostTowardsPartnerRateDataNode()

Input: None

Output: The DataMonitor<double>& that has the information representing the average number of flips towards a partner each host lineage has accumulated.

Purpose: To retrieve the data nodes that is tracking the average number of flips towards a partner each host lineage has accumulated.

emp::DataMonitor<double> &GetHostFromPartnerRateDataNode()

Input: None

Output: The DataMonitor<double>& that has the information representing the average number of flips from a partner each host lineage has accumulated.

Purpose: To retrieve the data nodes that is tracking the average number of flips from a partner each host lineage has accumulated.

emp::DataMonitor<double> &GetHostTagPermissiveness()

Input: None

Output: The DataMonitor<double>& that has the information representing the average tag permissiveness of hosts.

Purpose: To retrieve the data nodes that is tracking the average tag permissiveness of hosts.

emp::DataMonitor<int> &GetHostTagRichness()

Input: None

Output: The DataMonitor<int>& that has the information representing the host tag richness this update.

Purpose: To retrieve the data node that is tracking the host tag richness this update.

emp::DataMonitor<double> &GetHostTagShannonDiversity()

Input: None

Output: The DataMonitor<double>& that has the information representing the host tag shannon this update.

Purpose: To retrieve the data node that is tracking the host tag shannon this update.

emp::DataMonitor<int> &GetSymbiontTagRichness()

Input: None

Output: The DataMonitor<int>& that has the information representing the host tag shannon this update.

Purpose: To retrieve the data node that is tracking the symbiont tag richness this update.

emp::DataMonitor<double> &GetSymbiontTagShannonDiversity()

Input: None

Output: The DataMonitor<double>& that has the information representing the symbiont tag shannon this update.

Purpose: To retrieve the data node that is tracking the host symbiont shannon this update.

emp::DataMonitor<double, emp::data::Histogram> &GetTagDistanceDataNode()

Input: None

Output: The DataMonitor<double, emp::data::Histogram>& that has the information representing the average tag distance between hosts and their symbionts.

Purpose: To retrieve the data nodes that is tracking the average tag distance between hosts and their symbionts.

emp::DataMonitor<double, emp::data::Histogram> &GetHostIntValDataNode()

Input: None

Output: The DataMonitor<double, emp::data::Histogram>& that has the information representing the host interaction value.

Purpose: To collect data on the host interaction value to be saved to the data file that is tracking host interaction value.

emp::DataMonitor<double, emp::data::Histogram> &GetSymIntValDataNode()

Input: None

Output: The DataMonitor<double, emp::data::Histogram>& that has the information representing the symbiont interaction value.

Purpose: To collect data on the symbiont interaction value to be saved to the data file that is tracking symbionts interaction value.

emp::DataMonitor<double, emp::data::Histogram> &GetFreeSymIntValDataNode()

Input: None

Output: The DataMonitor<double>& that has the information representing the free symbiont’s interaction value.

Purpose: To collect data on the interaction value of the free symbionts to be saved to the data file that is tracking the interaction value of the free symbionts.

emp::DataMonitor<double, emp::data::Histogram> &GetHostedSymIntValDataNode()

Input:None

Output:

Purpose: To access the data node that is tracking the hosted symbiont interaction value

emp::DataMonitor<double, emp::data::Histogram> &GetSymInfectChanceDataNode()

Input: None

Output: The DataMonitor<double, emp::data::Histogram>& that has the information representing the infection chance for each symbionts.

Purpose: To access the data node that is tracking the symbiont infection chance

emp::DataMonitor<double, emp::data::Histogram> &GetFreeSymInfectChanceDataNode()

Input: None

Output: The DataMonitor<double, emp::data::Histogram>& that has the information representing the free symbionts’ chance of infection

Purpose: To access the data node that is tracking the infection chance within the free symbionts.

emp::DataMonitor<double, emp::data::Histogram> &GetHostedSymInfectChanceDataNode()

Input: None

Output: The DataMonitor<double, emp::data::Histogram>& that has the information representing the infection chance for the hosted symbionts

Purpose: To retrieve the data nodes that is tracking the infection chance within the hosted symbionts.

virtual void Setup()

Input: None.

Output: None.

Purpose: Prepare the world for an experiment by applying the configuration settings and populating the world with hosts and symbionts.

virtual void SetupHosts(long unsigned int *POP_SIZE)

Input: The number of hosts.

Output: None.

Purpose: To populate the world with hosts with appropriate phenotypes.

virtual void SetupSymbionts(long unsigned int *total_syms)

Input: The number of symbionts.

Output: None.

Purpose: To populate the world with symbionts with appropriate phenotypes.

inline emp::WorldPosition MoveIntoNewFreeWorldPos(emp::Ptr<Organism> sym, emp::WorldPosition parent_pos)

Input: The pointer to the symbiont that is moving, the WorldPosition of its current location.

Output: The WorldPosition object describing the symbiont’s new location (it describes an invalid position if the symbiont is deleted during movement)

Purpose: To move a symbiont into a new world position in the sym pop.

inline bool IsInboundsPos(emp::WorldPosition pos)

Input: The WorldPosition object to be checked.

Output: Wether the input object is within world bounds.

Purpose: To determine whether the location of free-living organisms is within the bounds of the free-living worlds (the size of the pop and sym_pop vectors).

inline virtual emp::WorldPosition SymDoBirth(emp::Ptr<Organism> sym_baby, emp::WorldPosition parent_pos)

Input: The pointer to the organism that is being birthed, and the WorldPosition location of the parent symbiont.

Output: The WorldPosition object describing the position the symbiont was born into (index = position in a host, 0 for free living and offset by one for position in host sym vector. id = position of self or host in sym_pop or pop vector). An invalid WorldPosition object is returned if the sym was killed.

Purpose: To birth a new symbiont. If free living symbionts is on, the new symbiont can be put into an unoccupied place in the world. If not, then it will be placed in a host near its parent’s location, or deleted if the parent’s location has no eligible near-by hosts.

inline void MoveFreeSym(emp::WorldPosition pos)

Input: The WorldPosition location of the symbiont to be moved.

Output: None

Purpose: To move a symbiont, either into a host, or into a free world position

inline emp::Ptr<Organism> ExtractSym(size_t i)

Input: The size_t representing the location of the symbiont to be extracted from the world’s sym population.

Output: The pointer to the organism that was extracted from the world. Pointer will be null if there was no sym at the location.

Purpose: To extract a symbiont from the world without deleting it.

inline void DoSymDeath(size_t i)

Input: The size_t representing the location of the symbiont to be deleted from the world’s symbiont population.

Output: None

Purpose: To delete a symbiont from the world.

inline bool IsSymPopOccupied(size_t pos)

Input: A size_t location to check in the symbiont population vector.

Output: A boolean representing whether the the position is valid and occupied by a free living symbiont/

Purpose: To determine if a given index is valid and occipied in the symbiont population vector.

inline void SetMutationZero()

Input: None

Output: None

Purpose: To set all settings in the MUTATION group to 0 for the no-mutation updates.

inline emp::SignalKey OnAnalyzePopulation(const std::function<void()> &fun)

Input: A function to run after the experiment has finished but before any no mutation updates have been run.

Output: A key representing the added function, which can usually be ignored.

Purpose: Allow performing population-level analyses before running no mutation updates.

inline void CureHosts()

Input: None

Output: None

Purpose: Cure all hosts of symbionts

inline void RunExperiment(bool verbose = true)

Input: Optional boolean “verbose” that specifies whether to print the update numbers to standard output or not, defaults to true.

Output: None

Purpose: Run the number of updates and non-mutation updates specified in the configuration settings.

inline emp::vector<std::pair<emp::Ptr<Organism>, size_t>> GetDominantInfo() const

Get the top config.DOMINANT_COUNT organisms from the population, sorted by their abundance.

inline void CleanupGraveyard()

Input: None

Output: None

Purpose: To loop over and delete elements in the graveyard.

inline virtual void Update()

Input: None

Output: None

Purpose: To simulate a timestep in the world, which includes calling the process functions for hosts and symbionts and updating the data nodes.