README.Rmd

---
output: github_document
bibliography: man/bibliography.bib
link-citations: TRUE
nocite: |
  @MarroigEtAl2009
  @BolstadEtAl2014
  @MeloEtAl2016
csl: man/cran_style.csl
---

<!-- 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%"
)
```
```{r setup, include = FALSE}
set.seed(601)
```


# avrevol: R Package for Average Evolvability Measures

<!-- badges: start -->
<!-- badges: end -->

This small package provides wrapper functions to evaluate average evolvability
measures in evolutionary quantitative genetics, based on the
implementation of recursion-based evaluation of moments of ratios of
quadratic forms in the package `qfratio`
([CRAN](https://CRAN.R-project.org/package=qfratio){target="_blank"};
[GitHub](https://github.com/watanabe-j/qfratio){target="_blank"}).

The package `qfratio` provides functions to evaluate moments of
ratios of quadratic forms in normal variables using recursive algorithms.
That package was originally developed for evaluating average evolvability
measures [@Watanabe2023cevo], but is capable of evaluating moments in rather
general conditions beyond those.
The idea of this package is to provide a simple, convenient interface
specifically aiming at average evolvability measures, by passing
appropriately specified arguments to functions from the `qfratio`
package.
All average evolvability measures treated by @Watanabe2023cevo are implemented,
accommodating arbitrary mean and covariance for the selection gradients.

As a supplement, this package also has functions to obtain Monte Carlo
samples for evolvability measures (including the random skewers correlation),
as well as the delta method approximations for average evolvability measures
by @HansenHoule2008.
Existing packages like `evolvability`
([CRAN](https://cran.r-project.org/package=evolvability))
and `evolqg` ([GitHub](https://github.com/lem-usp/EvolQG)) have these
functionalities, but this package's implementation is more general (Monte Carlo
versions accommodate arbitrary mean and covariance) and faster, at least as of
writing this.


## Installation

### From GitHub
```{r eval = FALSE}
# install.packages("devtools")
devtools::install_github("watanabe-j/avrevol")
```

### Dependencies

    Imports: qfratio, MASS


## Example

Here are hypothetical examples for typical use cases:

```{r example}
library(avrevol)

## Simple covariance matrices
nv <- 4
G1 <- diag(nv:1)
G2 <- diag(sqrt(1:nv))
nit <- 1000

## Average conditional evolvability using series expression
## Inspect plot to check for convergence
(res_cevo <- avr_cevo(G1))
plot(res_cevo)

## Hansen & Houle's (2008) delta method approximation of the same
hh_cevo(G1)

## Monte Carlo sample of conditional evolvability
## under spherical distribution of beta,
## and its mean as an estimate of average conditional evolvability
## plus its 95% CI
mcsample_cevo <- mc_cevo(nit, G1)
mean(mcsample_cevo)
mean(mcsample_cevo) + sd(mcsample_cevo) / sqrt(nit) *
    qt(c(0.025, 0.975), nit - 1)

## Average response difference using series expression,
## Hansen-Houle delta method approximation, and
## Monte Carlo estimate
(res_rdif <- avr_rdif(G1, G2))
plot(res_rdif)
hh_rdif(G1, G2)
mean(mc_rdif(nit, G1, G2))

## Average response correlation using series expression and
## its Monte Carlo estimate, aka "random skewers" correlation
(res_rcor <- avr_rcor(G1, G2, m = 500))
plot(res_rcor)
mean(mc_rcor(nit, G1, G2))

## Advanced: Average evolvability under
## non-spherical distribution of selection gradient
## (the same works for other evolvability measures as well)
mu <- nv:1 / nv
Sigma <- matrix(0.5, nv, nv)
diag(Sigma) <- 1
(res_evol_nsph <- avr_evol(G1, mu = mu, Sigma = Sigma))
plot(res_evol_nsph)
mean(mc_evol(nit, G1, mu = mu, Sigma = Sigma))
```

## References