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

How a new stability statistic is added so that it fits the package: a core, an exported function, a result with
methods, an interpretation, a help page and tests.

# The building blocks

```{r blocks}
cd <- stability:::.stab_ge_data(
    y    = ge_data$Yield
  , gen  = ge_data$Gen
  , env  = ge_data$Env
  , rep  = ge_data$Rep
  , fn   = "example"
  )
names(cd)
round(x = cd$M[1:3, 1:4])
cd$anova
```

`.stab_ge_data()` gives the table of means, the counts, the combined analysis of variance and the pooled error;
`.stab_ge_effects()` and `.stab_svd()` the interaction and its decomposition.

# A new statistic: the coefficient of regression of the interaction

```{r example}
Z <- stability:::.stab_ge_effects(cd$M)
I <- colMeans(cd$M) - mean(cd$M)
head(x = sort(drop(Z %*% I) / sum(I^2)), n = 5)
```

As an exported function it would check its arguments, wrap the result with `.stab_out()` (class, label, plot data),
define `.stab_print_<name>()`, `.stab_plot_<name>()` and an interpreter `.stab_int_<name>()` with its guide, and
come with tests against an independent computation.

# Summary

Every analysis follows one pattern; a new one reuses the table of means, the error, the result class, the plot
theme, the interpretation and the test helpers.