---
title: "Getting started with stability"
author: "Muhammad Yaseen"
date: last-modified
format:
  html:
    self-contained: true
    number-sections: true
    toc: true
    toc-depth: 3
    highlight-style: pygments
    code-tools: true
    html-math-method: mathjax
vignette: >
  %\VignetteIndexEntry{Getting started with stability}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
execute:
  echo: true
  warning: false
  message: false
---

{{< include _stability-macros.txt >}}

```{r setup, include = FALSE}
knitr::opts_chunk$set(collapse = FALSE, comment = "", fig.width = 7, fig.height = 4.6,
                      dev = if (knitr::is_latex_output()) "cairo_pdf" else
                        if (requireNamespace("svglite", quietly = TRUE)) "svglite" else "png")
if (requireNamespace("stability", quietly = TRUE)) library(stability) else
  pkgload::load_all(export_all = FALSE, helpers = FALSE, quiet = TRUE)
```

# Abstract

stability analyses multi-environment trials: the same genotypes grown in several environments, in randomized
complete blocks. This vignette goes from the data to the question every such trial asks (which genotypes yield well
and reliably) in a few steps, each followed by its interpretation.

# The data

`ge_data` holds the grain yield of 60 wheat genotypes in 11 environments with two replicates:

```{r data}
data(ge_data)
str(ge_data)
with(data = ge_data, expr = table(Env, Rep))[1:3, ]
```

Every analysis takes the data frame and the columns of response, replicate, genotype and environment.

# Is there an interaction?

```{r anova}
fit <-
  add_anova(
      .data = ge_data
    , .y    = Yield
    , .rep  = Rep
    , .gen  = Gen
    , .env  = Env
    )
fit
```

`stab_interpret()` reads the result for you:

```{r anova-int}
stab_interpret(
    x             = fit
  , higher_better = TRUE
  , top           = 5
  )
```

# Which genotypes are high-yielding and stable?

Eberhart and Russell's regression on the environment index:

```{r reg}
reg <-
  stab_reg(
      .data = ge_data
    , .y    = Yield
    , .rep  = Rep
    , .gen  = Gen
    , .env  = Env
    )
head(x = reg$StabIndvReg[order(-Mean)], n = 8)
plot(x = reg, which = "slope")
```

```{r reg-int}
stab_interpret(
    x             = reg
  , higher_better = TRUE
  , top           = 5
  )
```

# Which genotype wins where?

```{r gge, fig.height = 6}
p <-
  gge_biplot(
      .data  = ge_data
    , .y     = Yield
    , .rep   = Rep
    , .gen   = Gen
    , .env   = Env
    , .which = "which-won-where"
    , .svp   = "symmetric"
    )
p
```

```{r gge-int}
stab_interpret(
    x             = p
  , higher_better = TRUE
  , top           = 5
  )
```

# Summary

Three calls answer the three questions of a multi-environment trial: is there interaction (`add_anova()`), which
genotypes are stable (`stab_reg()` and the other stability statistics), and which genotype wins where
(`gge_biplot()`). `stab_interpret()` turns every result into sentences. The next vignettes take each method
further.

# References

Eberhart, S. A. and Russell, W. A. (1966). Stability parameters for comparing varieties. *Crop Science*, 6(1), 36--40.

Yan, W., Hunt, L. A., Sheng, Q. and Szlavnics, Z. (2000). Cultivar evaluation and mega-environment investigation based on the GGE biplot. *Crop Science*, 40(3), 597--605.