---
title: "Interpreting the results"
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{Interpreting the results}
  %\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

`stab_interpret()` turns every result into a headline, findings, recommendations and cautions, computed from the
numbers of that result. This vignette shows how it works and how to use its parts in a report.

# The parts of an interpretation

```{r parts}
fit <-
  stab_reg(
      .data = ge_data
    , .y    = Yield
    , .rep  = Rep
    , .gen  = Gen
    , .env  = Env
    )
txt <-
  stab_interpret(
      x             = fit
    , higher_better = TRUE
    , top           = 5
    )
names(txt)
txt$headline
txt$facts$widely_adapted
```

`facts` holds the numbers and lists behind every sentence, so a statement can be checked or reused; `guide` says how
the statistics of the method are read.

# Specific to each method

The sentences differ by method: for a regression they speak of slopes and deviations, for AMMI of axes and scores,
for the GGE biplot of winners and mega-environments:

```{r methods}
am <-
  ammi(
      .data = ge_data
    , .y    = Yield
    , .rep  = Rep
    , .gen  = Gen
    , .env  = Env
    )
stab_interpret(
    x             = am
  , higher_better = TRUE
  , top           = 3
  )$headline
p <-
  gge_biplot(
      .data  = ge_data
    , .y     = Yield
    , .rep   = Rep
    , .gen   = Gen
    , .env   = Env
    , .which = "which-won-where"
    , .svp   = "symmetric"
    )
stab_interpret(
    x             = p
  , higher_better = TRUE
  , top           = 3
  )$headline
stab_interpret(
    x             = am
  , higher_better = TRUE
  , top           = 3
  )$guide
```

# Traits where lower is better

```{r lower}
gm <-
  ge_means(
      .data = ge_data
    , .y    = Yield
    , .gen  = Gen
    , .env  = Env
    )
stab_interpret(
    x             = gm
  , higher_better = FALSE
  , top           = 3
  )$headline
```

# In a report

`format()` returns Markdown that can be pasted into a Quarto or R Markdown report:

```{r md}
cat(
    format(
        x     = stab_interpret(
            x             = am
          , higher_better = TRUE
          , top           = 3
          )
      , style = "markdown"
      )
  , sep = "\n"
  )
```

# Summary

The interpretation is a starting point: it states what the numbers show and where to be careful. Decisions on
recommendations still need the breeder's knowledge of the environments and of more than one season.

# References

Becker, H. C. and Leon, J. (1988). Stability analysis in plant breeding. *Plant Breeding*, 101(1), 1--23.