Honeybee simulation parameters

Source: R/Class-SimParamBee.R

Container for global honeybee simulation parameters. Saving this object as SP will allow it to be accessed by SIMplyBee functions without repeatedly (and annoyingly!) typing out someFun(argument, simParamBee = SP). SimParamBee inherits from AlphaSimR SimParam, so all SimParam slots and functions are available in addition to SimParamBee-specific slots and functions. Some SimParam functions could have upgraded behaviour as documented in line with honeybee biology.

Details

This documentation shows details specific to SimParamBee. We suggest you also read all the options provided by the AlphaSimR SimParam. Below we show minimal usage cases for each SimParamBee function.

See also vignette(package = "SIMplyBee") for descriptions of how SIMplyBee implements the specific honeybee biology.

References

Bovo et al. (2021) Application of Next Generation Semiconductor-Based Sequencing for the Identification of Apis mellifera Complementary Sex Determiner (csd) Alleles from Honey DNA. Insects, 12(10), 868. doi:/10.3390/insects12100868

Lechner et al. (2014) Nucleotide variability at its limit? Insights into the number and evolutionary dynamics of the sex-determining specificities of the honey bee Apis mellifera Molecular Biology and Evolution, 31, 272-287. doi:/10.1093/molbev/mst207

Seeley (2019) The Lives of Bees: The Untold Story of the Honey Bee in the Wild. Princeton: Princeton University Press. doi:/10.1515/9780691189383

Zareba et al. (2017) Uneven distribution of complementary sex determiner (csd) alleles in Apis mellifera population. Scientific Reports, 7, 2317. doi:/10.1038/s41598-017-02629-9

Super class

AlphaSimR::SimParam -> SimParamBee

Public fields

nWorkers

numeric or function, a number of workers generated in a colony - used in createWorkers, addWorkers, buildUp.

The default value is 100, that is, queen generates 100 workers - this is for a down-scaled simulation (for efficiency) assuming that this represents ~60,000 workers in a full/strong colony (Seeley, 2019). This value is set in SimParamBee$new() to have a number to work with.

You can change this setting to your needs!

When nWorkers is a function, it should work with internals of other functions. Therefore, the function MUST be defined like function(colony, arg = default) someCode , that is, the first argument MUST be colony and any following arguments MUST have a default value. For flexibility you can add ... argument to pass on any other argument. See nWorkersPoisson, nWorkersTruncPoisson, or nWorkersColonyPhenotype for examples.

You can provide your own functions that satisfy your needs!

nDrones

numeric or function, a number of drones generated in a colony - used in createDrones, addDrones, buildUp.

The default value is 100, that is, queen generates 100 drones - this is for a down-scaled simulation (for efficiency) assuming that this represents ~1,000 drones in a full/strong colony (Seeley, 2019). This value is set in SimParamBee$new() to have a number to work with.

You can change this setting to your needs!

When nDrones is a function, it should work with internals of other functions. Therefore, the function MUST be defined like function(x, arg = default) someCode , that is, the first argument MUST be x and any following arguments MUST have a default value. For flexibility you can add ... argument to pass on any other argument. See nDronesPoisson, nDronesTruncPoisson, or nDronesColonyPhenotype for examples.

You can provide your own functions that satisfy your needs!

nVirginQueens

numeric or function, a number of virgin queens generated when a queen dies or other situations - used in createVirginQueens and addVirginQueens.

The default value is 10, that is, when the queen dies, workers generate 10 new virgin queens (Seeley, 2019). This value is set in SimParamBee$new() to have a number to work with.

You can change this setting to your needs!

When nVirginQueens is a function, it should work with internals of other functions. Therefore, the function MUST be defined like function(colony, arg = default) someCode , that is, the first argument MUST be colony and any following arguments MUST have a default value. For flexibility you can add ... argument to pass on any other argument. See nVirginQueensPoisson, nVirginQueensTruncPoisson, or nVirginQueensColonyPhenotype for examples.

You can provide your own functions that satisfy your needs!

nFathers

numeric or function, a number of drones a queen mates with - used in pullDroneGroupsFromDCA, cross.

The default value is 15, that is, a virgin queen mates on average with 15 drones (Seeley, 2019). This value is set in SimParamBee$new() to have a number to work with.

You can change this setting to your needs!

When nFathers is a function, it should work with internals of other functions. Therefore, the function MUST be defined like function(arg = default) someCode , that is, any arguments MUST have a default value. We did not use the colony argument here, because nFathers likely does not depend on the colony. Let us know if we are wrong! For flexibility you can add ... argument to pass on any other argument. See nFathersPoisson or nFathersTruncPoisson for examples.

You can provide your own functions that satisfy your needs!

swarmP

numeric or a function, the swarm proportion - the proportion of workers that leave with the old queen when the colony swarms - used in swarm.

The default value is 0.50, that is, about a half of workers leave colony in a swarm (Seeley, 2019). This value is set in SimParamBee$new() to have a proportion to work with.

You can change this setting to your needs!

When swarmP is a function, it should work with internals of other functions. Therefore, the function MUST be defined like function(colony, arg = default) someCode , that is, the first argument MUST be colony and any following arguments MUST have a default value. For flexibility you can add ... argument to pass on any other argument. See swarmPUnif for examples.

You can provide your own functions that satisfy your needs!

swarmRadius

numeric, radius within which to sample a location of of the swarm - used in swarm - see its radius argument.

The default value is 0, that is, swarm gets the same location as the original colony.

You can change this setting to your needs!

splitP

numeric or a function, the split proportion - the proportion of workers removed in a managed split - used in split.

The default value is 0.30, that is, about a third of workers is put into a split colony from a strong colony (Seeley, 2019). This value is set in SimParamBee$new() to have a proportion to work with.

You can change this setting to your needs!

When splitP is a function, it should work with internals of other functions. Therefore, the function MUST be defined like function(colony, arg = default) someCode , that is, the first argument MUST be colony and any following arguments MUST have a default value. For flexibility you can add ... argument to pass on any other argument. See splitPUnif or splitPColonyStrength for examples.

You can provide your own functions that satisfy your needs!

downsizeP

numeric or a function, the downsize proportion - the proportion of workers removed from the colony when downsizing, usually in autumn - used in downsize.

The default value is 0.85, that is, a majority of workers die before autumn or all die but some winter workers are created (Seeley, 2019). This value is set in SimParamBee$new() to have a proportion to work with.

You can change this setting to your needs!

When downsizeP is a function, it should work with internals of other functions. Therefore, the function MUST be defined like function(colony, arg = default) someCode , that is, the first argument MUST be colony and any following arguments MUST have a default value. For flexibility you can add ... argument to pass on any other argument. See downsizePUnif for example.

You can provide your own functions that satisfy your needs!

colonyValueFUN

function, to calculate colony values - used in calcColonyValue - see also calcColonyPheno and calcColonyGv.

This function should work with internals of others functions - therefore the function MUST be defined like function(colony, arg = default) someCode , that is, the first argument MUST be colony and any following arguments MUST have a default value. For flexibility you can add ... argument to pass on any other argument. See mapCasteToColonyValue for an example.

You can provide your own functions that satisfy your needs!

Active bindings

caste

character, caste information for every individual ever created; active only when SP$setTrackPed(isTrackPed = TRUE)

lastColonyId

integer, ID of the last Colony object created with createColony

csdChr

integer, chromosome of the csd locus

csdPos

numeric, starting position of the csd locus on the csdChr chromosome (relative at the moment, but could be in base pairs in the future)

nCsdAlleles

integer, number of possible csd alleles

nCsdSites

integer, number of segregating sites representing the csd locus

csdPosStart

integer, starting position of the csd locus

csdPosStop

integer, ending position of the csd locus

version

list, versions of AlphaSimR and SIMplyBee packages used to generate this object

Methods

Public methods

Inherited methods

Method new()

Starts the process of building a new simulation by creating a new SimParamBee object and assigning a founder population of genomes to the this object.

Usage

SimParamBee$new(
  founderPop,
  nWorkers = 100,
  nDrones = 100,
  nVirginQueens = 10,
  nFathers = 15,
  swarmP = 0.5,
  swarmRadius = 0,
  splitP = 0.3,
  downsizeP = 0.85,
  csdChr = 3,
  csdPos = 0.865,
  nCsdAlleles = 128,
  colonyValueFUN = NULL
)

Arguments

founderPop

MapPop-class, founder population of genomes

nWorkers

see SimParamBee field nWorkers

nDrones

see SimParamBee field nDrones

nVirginQueens

see SimParamBee field nVirginQueens

nFathers

see SimParamBee field nFathers

swarmP

see SimParamBee field swarmP

swarmRadius

see SimParamBee field swarmRadius

splitP

see SimParamBee field splitP

downsizeP

see SimParamBee field downsizeP

csdChr

integer, chromosome that will carry the csd locus, by default 3, but if there are less chromosomes (for a simplified simulation), the locus is put on the last available chromosome (1 or 2); if NULL then csd locus is ignored in the simulation

csdPos

numeric, starting position of the csd locus on the csdChr chromosome (relative at the moment, but could be in base pairs in future)

nCsdAlleles

integer, number of possible csd alleles (this determines how many segregating sites will be needed to represent the csd locus from the underlying bi-allelic SNP; the minimum number of bi-allelic SNP needed is log2(nCsdAlleles)); if set to 0 then csdChr=NULL is triggered. By default we set nCsdAlleles to 128, which is at the upper end of the reported number of csd alleles (Lechner et al., 2014; Zareba et al., 2017; Bovo et al., 2021).

colonyValueFUN

see SimParamBee field colonyValueFUN

Examples

founderGenomes <- quickHaplo(nInd = 10, nChr = 3, segSites = 10)
SP <- SimParamBee$new(founderGenomes, nCsdAlleles = 2)
\dontshow{SP$nThreads = 1L}

# We need enough segregating sites
try(SP <- SimParamBee$new(founderGenomes, nCsdAlleles = 100))
\dontshow{SP$nThreads = 1L}
founderGenomes <- quickHaplo(nInd = 10, nChr = 3, segSites = 100)
SP <- SimParamBee$new(founderGenomes, nCsdAlleles = 100)
\dontshow{SP$nThreads = 1L}

# We can save the csd locus on chromosome 1 or 2, too, for quick simulations
founderGenomes <- quickHaplo(nInd = 10, nChr = 1, segSites = 100)
SP <- SimParamBee$new(founderGenomes, nCsdAlleles = 100)
\dontshow{SP$nThreads = 1L}

Method addToCaste()

Store caste information (for internal use only!)

Usage

SimParamBee$addToCaste(id, caste)

Arguments

id

character, individuals whose caste will be stored

caste

character, single "Q" for queens, "W" for workers, "D" for drones, "V" for virgin queens, and "F" for fathers

Examples

founderGenomes <- quickHaplo(nInd = 2, nChr = 1, segSites = 100)
SP <- SimParamBee$new(founderGenomes)
\dontshow{SP$nThreads = 1L}
SP$setTrackPed(isTrackPed = TRUE)
basePop <- createVirginQueens(founderGenomes)

drones <- createDrones(x = basePop[1], nInd = 10)
colony <- createColony(x = basePop[2])
colony <- cross(colony, drones = drones)
colony <- addWorkers(colony, nInd = 5)
colony <- addDrones(colony, nInd = 5)
colony <- addVirginQueens(colony, nInd = 2)

SP$pedigree
SP$caste

Method changeCaste()

Change caste information (for internal use only!)

Usage

SimParamBee$changeCaste(id, caste)

Arguments

id

character, individuals whose caste will be changed

caste

character, single "Q" for queens, "W" for workers, "D" for drones, "V" for virgin queens, and "F" for fathers

Examples

founderGenomes <- quickHaplo(nInd = 2, nChr = 1, segSites = 100)
SP <- SimParamBee$new(founderGenomes)
\dontshow{SP$nThreads = 1L}
SP$setTrackPed(isTrackPed = TRUE)
basePop <- createVirginQueens(founderGenomes)
SP$pedigree
SP$caste

drones <- createDrones(x = basePop[1], nInd = 10)
colony <- createColony(x = basePop[2])
colony <- cross(colony, drones = drones)
SP$pedigree
SP$caste

Method updateLastColonyId()

A function to update the colony last ID everytime we create a Colony-class with createColony. For internal use only.

Usage

SimParamBee$updateLastColonyId()

Arguments

lastColonyId

integer, last colony ID assigned

Method clone()

The objects of this class are cloneable with this method.

Usage

SimParamBee$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples


## ------------------------------------------------
## Method `SimParamBee$new`
## ------------------------------------------------

founderGenomes <- quickHaplo(nInd = 10, nChr = 3, segSites = 10)
SP <- SimParamBee$new(founderGenomes, nCsdAlleles = 2)
SP$nThreads = 1L

# We need enough segregating sites
try(SP <- SimParamBee$new(founderGenomes, nCsdAlleles = 100))
#> Error in initialize(...) : 
#>   Too few segregagting sites to simulate 100 csd alleles at the given position!
SP$nThreads = 1L
founderGenomes <- quickHaplo(nInd = 10, nChr = 3, segSites = 100)
SP <- SimParamBee$new(founderGenomes, nCsdAlleles = 100)
SP$nThreads = 1L

# We can save the csd locus on chromosome 1 or 2, too, for quick simulations
founderGenomes <- quickHaplo(nInd = 10, nChr = 1, segSites = 100)
SP <- SimParamBee$new(founderGenomes, nCsdAlleles = 100)
SP$nThreads = 1L

## ------------------------------------------------
## Method `SimParamBee$addToCaste`
## ------------------------------------------------

founderGenomes <- quickHaplo(nInd = 2, nChr = 1, segSites = 100)
SP <- SimParamBee$new(founderGenomes)
SP$nThreads = 1L
SP$setTrackPed(isTrackPed = TRUE)
basePop <- createVirginQueens(founderGenomes)
#> Error in get(x = "SP", envir = .GlobalEnv): object 'SP' not found

drones <- createDrones(x = basePop[1], nInd = 10)
#> Error in get(x = "SP", envir = .GlobalEnv): object 'SP' not found
colony <- createColony(x = basePop[2])
#> Error in get(x = "SP", envir = .GlobalEnv): object 'SP' not found
colony <- cross(colony, drones = drones)
#> Error in get(x = "SP", envir = .GlobalEnv): object 'SP' not found
colony <- addWorkers(colony, nInd = 5)
#> Error in get(x = "SP", envir = .GlobalEnv): object 'SP' not found
colony <- addDrones(colony, nInd = 5)
#> Error in get(x = "SP", envir = .GlobalEnv): object 'SP' not found
colony <- addVirginQueens(colony, nInd = 2)
#> Error in get(x = "SP", envir = .GlobalEnv): object 'SP' not found

SP$pedigree
#>      [,1] [,2] [,3]
SP$caste
#> factor()
#> Levels: queen fathers workers drones virginQueens

## ------------------------------------------------
## Method `SimParamBee$changeCaste`
## ------------------------------------------------

founderGenomes <- quickHaplo(nInd = 2, nChr = 1, segSites = 100)
SP <- SimParamBee$new(founderGenomes)
SP$nThreads = 1L
SP$setTrackPed(isTrackPed = TRUE)
basePop <- createVirginQueens(founderGenomes)
#> Error in get(x = "SP", envir = .GlobalEnv): object 'SP' not found
SP$pedigree
#>      [,1] [,2] [,3]
SP$caste
#> factor()
#> Levels: queen fathers workers drones virginQueens

drones <- createDrones(x = basePop[1], nInd = 10)
#> Error in get(x = "SP", envir = .GlobalEnv): object 'SP' not found
colony <- createColony(x = basePop[2])
#> Error in get(x = "SP", envir = .GlobalEnv): object 'SP' not found
colony <- cross(colony, drones = drones)
#> Error in get(x = "SP", envir = .GlobalEnv): object 'SP' not found
SP$pedigree
#>      [,1] [,2] [,3]
SP$caste
#> factor()
#> Levels: queen fathers workers drones virginQueens