---
title: "Frequently asked questions"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Frequently asked questions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
editor_options:
  markdown:
    wrap: 80
    canonical: true
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  include = TRUE
)
```

# Introduction

This document collates other important points not mentioned in previous
vignettes or similar frequently asked questions. We will demonstrate some of the
questions and answers with the R code so we load the package:

```{r load}
library(package = "SIMplyBee")
```

# Why aren't drones removed from colonies when creating a DCA?

In SIMplyBee, when we modify an object, we return it following R's functional
style of programming. However, we do not by default return drone-donor colonies
when we sample the drones for mating and crossing the virgin queens. A virgin
queen can mate with several drones, say from $n$ colonies. These drones die
during mating. To reflect this reality, the drone sampling or the crossing
function should return $n$ updated colonies with the drones removed, which could
be cumbersome. To provide simple code, we by default only get a copy of drones
from colonies and change their caste from drones to fathers, which marks them as
mated and dead. This means they can't be used anymore as drones anymore, but
remain in the colony.

```{r drones_not_removed}
# Initiate simulation
founderGenomes <- quickHaplo(nInd = 3, nChr = 1, segSites = 10)
SP <- SimParamBee$new(founderGenomes, csdChr = NULL)

# Base virgin queens
baseVirginQueen <- createVirginQueens(founderGenomes)

# Base drones
baseDrones <- createDrones(baseVirginQueen[1])

# A colony
colony <- createColony(baseVirginQueen[2])
colony <- cross(x = colony, crossPlan = "create", drones = baseDrones, checkCross = "warning")
colony <- addDrones(colony, nInd = 100)
colony

# Crossing one of the remaining virgin queens with drones from the 
DCA <- createDCA(colony, nInd = 50)
DCA
queen <- cross(x = baseVirginQueen[3], crossPlan = "create", drones = DCA, checkCross = "warning")
queen
getFathers(queen)

# Note that we did not by default remove drones from the colony when we 
# created the DCA, but these drones now have a caste changed to fathers, so
# they are not available anymore for further mating
colony@drones # 100 drones
table(getCaste(colony@drones)) # 50 drones 50 fathers
getDrones(colony) # 50 drones
```