README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  # out.width = "100%",

  results = 'markup', # "hold", # display chunk output in one block
  tidy = TRUE, # better code organisation
  tidy.opts = list(width.cutoff = 80),
  strip.white = FALSE, # remove the white lines in the beginning or end of a source chunk


  fig.align = "center",
  fig.width = 9,
  fig.height = 5

)
```

# breedSimulatR

<!-- badges: start -->
[![codecov](https://codecov.io/gh/ut-biomet/breedSimulatR/branch/master/graph/badge.svg?token=4Uxp1ySLIn)](https://codecov.io/gh/ut-biomet/breedSimulatR)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![last-commit](https://img.shields.io/github/last-commit/ut-biomet/breedSimulatR.svg)](https://github.com/ut-biomet/breedSimulatR/commits/master)
[![CRAN status](https://www.r-pkg.org/badges/version/breedSimulatR)](https://CRAN.R-project.org/package=breedSimulatR)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)
[![R-CMD-check-Linux](https://github.com/ut-biomet/breedSimulatR/actions/workflows/R-CMD-check-Linux.yaml/badge.svg)](https://github.com/ut-biomet/breedSimulatR/actions/workflows/R-CMD-check-Linux.yaml)
[![R-CMD-check-Windows](https://github.com/ut-biomet/breedSimulatR/actions/workflows/R-CMD-check-Windows.yaml/badge.svg)](https://github.com/ut-biomet/breedSimulatR/actions/workflows/R-CMD-check-Windows.yaml)
[![R-CMD-check](https://github.com/ut-biomet/breedSimulatR/actions/workflows/R-CMD-check-MacOS.yaml/badge.svg)](https://github.com/ut-biomet/breedSimulatR/actions/workflows/R-CMD-check-MacOS.yaml)
<!-- badges: end -->

R package providing classes and functions to simulate breeding schemes.

The associated web-site for this package can be found at: https://ut-biomet.github.io/breedSimulatR/

## Installation

:octocat: You can install `breedSimulatR` from [GitHub](https://github.com/) with:

```{r, Installation_1, eval=FALSE}
if (!require("devtools")) {
  install.packages("devtools")
}
devtools::install_github("ut-biomet/breedSimulatR", build_vignettes = TRUE)
```


You can check the installation with these lines:

```{r, Installation_2, eval=FALSE}
library(breedSimulatR)
help(package = breedSimulatR)
```


## Example

```{r example_0, include=FALSE}
dta <- breedSimulatR::exampleData
set.seed(1804)
```

This is a basic example which shows how to use the package.

The package contains some example data that we will use for this example. These data are stored in the variable `exampleData`.

`exampleData` is a list containing 3 elements:

- `exampleData$genotypes`: `data.frame` containing the genotypic data encoded in allele doses of `r nrow(dta$genotypes)` fictitious individuals with `r ncol(dta$genotypes)` SNP markers. These individuals have 10 chromosomes of length 10^6 bases pairs.
- `exampleData$snpCoord`: `data.frame` containing the coordinates of the `r ncol(dta$genotypes)` individuals' markers. This data.frame contains 3 columns: `chr`, `pos` and `SNPid`.
- `exampleData$snpEffects `: `numeric` vector containing the "true" effects of the `r ncol(dta$genotypes)` individuals' markers about a fictitious quantitative trait based on an additive architecture.


#### initialization

First we must load the package:
```{r example_0.1, include=FALSE}
options("max.print" = 25)
```

```{r example_0.2}
library(breedSimulatR)
```

#### Specie specification

Let's specify the specie:

```{r example_1}
# create specie object
specie_statEx <- specie$new(specName = "Statisticae exempli",
                        nChr = 10,
                        lchr = 1e6,
                        lchrCm = 100)
```

#### SNP specification

We must specify the information about the positions of the genotypic markers used in the simulation.

Let's load these information (stored in `exampleData$snpCoord`) and create the `SNPinfo` object.

```{r example_2.1}
# data preview
head(exampleData$snpCoord)
```


```{r example_2.2}
# create SNPinfo object
SNPs <- SNPinfo$new(SNPcoord = exampleData$snpCoord,
                    specie = specie_statEx)
print(SNPs)
```


#### Population initialization

We can now generate an initial population from genotypic data.

Let's load the genotypic information  (stored in `exampleData$genotypes`) and create the `population` object:

```{r example_3.1}
# data preview
exampleData$genotypes[1:3,1:5]
```

```{r example_3.2, results='hide'}
# create population object
initPop <- createPop(geno = exampleData$genotypes,
                     SNPinfo = SNPs,
                     popName = "Initial population")
```


#### Traits and phenotyping initialization

Let's create 2 independent phenotypic traits that can be phenotyped.

```{r example_trait.1}
nQtn <- 1000

qtn <- sample(names(initPop$maf > 0.1), nQtn)
weight <- trait$new(name = "Weight",
                    qtn = qtn,
                    qtnEff = rnorm(nQtn, 0, 0.35))

qtn <- sample(names(initPop$maf > 0.1), nQtn)
height <- trait$new(name = "Height",
                    qtn = qtn,
                    qtnEff = rnorm(nQtn, 0, 0.25))

phenolab <- phenotyper$new(name = "Pheno lab",
                           traits = list(weight, height),
                           plotCost = 150,
                           mu = c(100, 75),
                           he = c(0.4, 0.6),
                           pop = initPop)

pheno <- phenolab$trial(pop = initPop, rep = 4)
head(pheno$data)
print(pheno$cost)
```

#### Selection Simulation

In order to perform crossing, we must specify which individuals must be mate together. Therefore, we must create functions which generate a crossing table from our population.

For this example, we will use the function `selectBV`, which returns the names of the best individuals according to their breeding values.

Then, the function `randomMate` will generate the crossing table.

```{r example_4.1}
exampleData$snpEffects
(selectedInds <- selectBV(pop = initPop,
                          QTNeffects = exampleData$snpEffects,
                          n = 10))

(crossTable <- randomMate(inds = selectedInds,
                          n = 120,
                          names = "generation_1"))
```

We can now generate the offspring:

```{r example_4.2, results='hide'}
newPop <- population$new(name = "1st offspring",
                         inds = makeCrosses(crosses = crossTable, pop = initPop))
```
```{r example_4.3}
newPop
```

This process can be included in loops in order to simulate several generations.


## Issues

When encountering a problem with the package or if you have questions, please
report issues on GitHub [here](https://github.com/ut-biomet/breedSimulatR/issues).

I will do my best to help you as soon as possible.


## Contributing

You can contribute in various ways:

- report an [issue](https://github.com/ut-biomet/breedSimulatR/issues) (online, see the above section)
- suggest improvements (in the same way as issues)
- propose a pull request (after creating a new branch)

When editing the content of this package, please run the following commands before
asking a pull request:

```{r Contributing, eval=FALSE}
devtools::document()
pkg <- devtools::build()
devtools::check_built(pkg)
```


## Citation

Please cite this package when using it for your projects:

```{r Citation, eval=FALSE}
citation("breedSimulatR")
```

See also `citation()` for citing R itself.

## Acknowledgments

Thanks to [Kosuke Hamazaki](https://github.com/KosukeHamazaki) for his feedbacks.


## References

`breedSimulatR` is written in **R**:

```{r References_0, echo=FALSE, results='asis'}
ref <- capture.output(print(citation(), style = "html", .bibstyle = NULL))
ref <- paste0(ref, collapse = "")
# ref <- gsub("(^<p>)|(<\\/p>$)", "", ref)
ref <- gsub("<p>", "<li>", ref)
ref <- gsub("</p>", "</li>", ref)
cat("<ul>")
cat(ref)
cat("</ul>")
```

`breedSimulatR` package or its development required the following R packages:

```{r References_1, echo=FALSE, results = 'asis'}
desc <- read.dcf(file.path(getwd(), "DESCRIPTION"))
pkgs <- unlist(strsplit(desc[,c("Depends", "Imports", "Suggests")], ",[\n]?"))
pkgs <- gsub(pattern = " (?=.*).*", "", pkgs, perl = TRUE)

cat("<ul>")
for (pkg in pkgs) {
  if (pkg == "R") {
    next
  } else cite <- citation(package = pkg)
  cat("<li>")
  cat("<b>", pkg, "</b> ")
  ref <- capture.output(print(cite, style = "html", .bibstyle = NULL, Encoding = "UTF-8"))
  ref <- paste0(ref, collapse = "")
  # ref <- gsub("(^<p>)|(<\\/p>$)", "", ref)
  ref <- gsub("<p>", "<li>", ref)
  ref <- gsub("</p>", "</li>", ref)
  cat("<ul>")
  cat(ref)
  cat("</ul>")
  cat("</li>")
}
cat("</ul>")
```


Example data were generated using the serious game "PlantBreedGame" available on GitHub https://github.com/timflutre/PlantBreedGame

<ul><li>
<b>PlantBreedGame</b>
<ul><li>
Flutre T, Diot J, and David J (2019). <em>PlantBreedGame</em>: A Serious Game that Puts Students in the Breeder’s Seat. <em>Crop Science.</em> [DOI 10.2135/cropsci2019.03.0183le](https://dl.sciencesocieties.org/publications/cs/abstracts/59/4/1374)
</li></ul>
</li></ul>







## License and copyright  :copyright:

The `breedSimulatR` package as a whole is licensed under the MIT.
See the [LICENSE.md](LICENSE.md) file for more details.

:copyright: The copyright holder is [The University of Tokyo, Laboratory of Biometry and Bioinformatics](https://sites.google.com/ut-biomet.org/lbm).


<img src="man/figures/biometLogo.png" style="display: block; margin: auto;max-height: 100px"/>