Appendix B — Development and verification

B.1 Editorial decisions

Decision Adopted approach
Audience Researchers with basic R knowledge; statistical concepts explained as needed
Chapter sequence Worked example, interpretation, assumptions and theory, implementation and limitations
R examples Tidyverse style, native pipes, simple tables, and default plot() calls; automated assertions belong in development checks
Theory Plain-language explanation first; define every symbol and explain each step of necessary equations
Derivations Linked appendices
Public coverage Every exported function, registered method, and scientifically distinct method option
Internal coverage Scientific algorithms explained through numerical demonstrations; all named helpers indexed
Example context Actual plant, animal, and human genotype datasets; human datasets for binary phenotypes; bring-your-own-data workflow first
Hosting Static book suitable for GitHub Pages; publication requires a separate maintainer decision

B.2 Dataset strategy

The opening workflow starts with a reader’s genotype file and supplies observed maize genotypes as the reproducible example. Organism breadth means substantive worked examples from different research communities, not artificial data with species labels. Small constructed examples remain useful for checking algebra.

Context Role in the book Current status
Plant Maize input, continuous traits, crossing, selection, and breeding schemes Bundled SNP55K_maize282_maf04 (Cook et al. 2012; 280 inbred lines, 10,650 markers, MAF > 0.4 subset, synthetic map); used throughout
Animal Relationship matrices, BLUP prediction, accuracy, and outbred allele frequencies Heterogeneous-stock mice distributed with the BGLR package (?BGLR::mice, Valdar et al. 2006; 1,814 mice, 10,346 SNPs with physical positions); loaded by _data.R
Human Binary phenotypes using the liability-threshold model; dominance on an outbred panel HapMap Phase II subset distributed with SNPRelate (279 CEU, YRI, HCB and JPT individuals; 9,028 SNPs after dropping duplicated identifiers; missing calls imputed); loaded by _data.R

Each dataset has documented provenance, redistribution through a CRAN or Bioconductor package, and a reproducible route from the distributed files to the chapter input (docs/book/_data.R, explained step by step in the genotype input chapter). The human and mouse datasets travel with their packages, so the book adds no data files of its own. The binary phenotype chapter distinguishes liability-scale parameters, observed prevalence, and case/control sampling.

B.3 Progressive chapter plan

The first simulation and conventions chapters establish the reading pattern. The following map assigns the public API to progressively more complex methods chapters. “Draft; Fable-reviewed” means the chapter is written, its examples execute, and a same-model theory review found and fixed its errors, but the independent cross-model review required by docs/THEORY_REVIEW.md is still pending. “Pilot draft” chapters have passed that independent review.

Chapter Scope Draft status
A first simulation Bring your own genotypes, observed maize example, diagnostics, export, and reproducibility Pilot draft
Notation and conventions Coding, scales, objects, identifiers, and replication Pilot draft
Genotype input and quality control File formats, allele orientation, missingness, filtering, and LD Draft; Fable-reviewed, Codex review pending
Maps, haplotypes, and founders Population input, synthetic maps, coalescent founders, and haplotype access Draft; Fable-reviewed, Codex review pending
Additive phenotype models Layer effects, causal loci, scaling, and additive diagnostics Draft; Fable-reviewed, Codex review pending
Dominance and epistasis Coding, orthogonal models, interacting loci, and variance components Draft; Fable-reviewed, Codex review pending
Pleiotropy, linkage, and multiple traits Architectures, feasible correlations, partial sharing, and residual correlation Draft; Fable-reviewed, Codex review pending
Binary phenotypes with human genotypes Human genotype input, liability thresholds, prevalence, liability and observed scales, and case/control sampling interpretation Draft; Fable-reviewed, Codex review pending
Complex phenotype architectures vQTL and combined simulations Draft; Fable-reviewed, Codex review pending
Meiosis and crossing Crossing, selfing, doubled haploids, pedigree, and family access Draft; Fable-reviewed, Codex review pending
Trait values across generations Fixed effects, reference scales, environments, and phenotyping Draft; Fable-reviewed, Codex review pending
Mating designs and crossbreeding Planned matings, ancestry composition, and heterosis Draft; Fable-reviewed, Codex review pending
Relationship matrices and prediction Animal-data worked examples: pedigree and genomic relationships, single- and multi-trait BLUP, accuracy Draft; Fable-reviewed, Codex review pending
Individual, family, and multivariate selection Truncation, family methods, indices, culling, BQP, and random controls Draft; Fable-reviewed, Codex review pending
Contributions and cross usefulness OCS objectives, coancestry constraints, allocation, and usefulness Draft; Fable-reviewed, Codex review pending
Marker-assisted breeding Gene pyramiding, foreground and background selection, recovery Draft; Fable-reviewed, Codex review pending
Combining ability and breeding schemes Testcrosses, progeny tests, repeated selection, and population management Draft; Fable-reviewed, Codex review pending
Transcriptome simulation and counts Expression generation, mimic calibration, and count observations Draft; Fable-reviewed, Codex review pending
Expression-mediated phenotypes Expression layers and genetic/environmental mediation summaries Draft; Fable-reviewed, Codex review pending
Inspecting and exporting results Long/wide tables, plots, QTN metadata, text/JSON and split-marker exports Draft; Fable-reviewed, Codex review pending
Legacy interface and migration Frozen create_phenotypes interface, independent theory, and migration Draft; Fable-reviewed, Codex review pending

B.4 Build the preview

From a checkout with the package build dependencies, R, Python 3, and Quarto:

Rscript --vanilla -e 'pkgload::load_all()'
quarto render docs/book
quarto preview docs/book

The R build dependencies include pkgload, knitr, rmarkdown, jsonlite, dplyr, tibble, tidyr, readr, SNPRelate, gdsfmt, and BGLR (the last three supply the human and mouse datasets). dev/book/run_chapter.R executes a single chapter’s R chunks with knitr, without Quarto, for a fast check while editing. The package itself requires its declared R dependencies and the Rust toolchain. The book’s hidden setup loads this checkout, preventing an older installed package from silently supplying the executed examples. Its visible examples use ordinary library(simplePHENOTYPES) calls for readers with the matching version.

dev/book/build_index.py regenerates the function indexes, checks coverage against NAMESPACE, verifies that referenced example labels exist, and copies the archival equation map into the rendered resources. The generated indexes, downloads, and HTML output are ignored by Git; the sources and coverage records are maintained in the repository.

B.5 Scientific review

For each scientific method, record its model assumptions, implemented expression, primary source and verified page where applicable, numerical checks, and independent review outcome. Algebraic derivations and package conventions must be identified as such. An unverified literature page is never replaced by a guess.

The repository’s docs/THEORY_REVIEW.md governs independent review before commit. Passing example execution alone does not validate the theory. Before publication, require complete example coverage, resolved scientific review, successful book rendering, and a passing package test suite.

B.6 Publication

The source lives under docs/book/, which is already excluded from the CRAN package through the repository’s ^docs$ build exclusion. The output directory is docs/book/_book/; the existing docs/ contents must not be overwritten by rendered website files.

GitHub Pages can serve these static files from a Pages deployment artifact. The preview workflow renders and uploads an artifact for inspection without deploying it. Deployment will be configured after the book and its publication scope have been reviewed. See the Quarto publishing guide.

B.7 Build record

  • Package version: 2.0.0.9003.
  • Source revision: 3c000630a5e566640b5eadfd429d0fcbfd5349b9.
  • Package source differs from that revision: no.
  • Public coverage assignments: 72.
  • Public functions/methods with authored examples: 72.
  • Pilot scientific review matches the current source and reviewed files: no.
  • This count records authored chunks, not completed independent scientific review. A successful fresh render is required to establish execution.
Code 
source("_setup.R")
sessionInfo()
#> R version 4.6.1 (2026-06-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.5 LTS
#> 
#> Matrix products: default
#> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=C.UTF-8       LC_NUMERIC=C           LC_TIME=C.UTF-8       
#>  [4] LC_COLLATE=C.UTF-8     LC_MONETARY=C.UTF-8    LC_MESSAGES=C.UTF-8   
#>  [7] LC_PAPER=C.UTF-8       LC_NAME=C              LC_ADDRESS=C          
#> [10] LC_TELEPHONE=C         LC_MEASUREMENT=C.UTF-8 LC_IDENTIFICATION=C   
#> 
#> time zone: UTC
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] simplePHENOTYPES_2.0.0.9003 testthat_3.3.2             
#> 
#> loaded via a namespace (and not attached):
#>  [1] digest_0.6.39       desc_1.4.3          R6_2.6.1            fastmap_1.2.0      
#>  [5] xfun_0.61           magrittr_2.0.5      knitr_1.52          htmltools_0.5.9    
#>  [9] rmarkdown_2.32      lifecycle_1.0.5     mvtnorm_1.4-2       cli_3.6.6          
#> [13] data.table_1.18.6.1 pkgload_1.5.3       compiler_4.6.1      rprojroot_2.1.1    
#> [17] tools_4.6.1         pkgbuild_1.4.8      brio_1.1.5          evaluate_1.0.5     
#> [21] yaml_2.3.12         otel_0.2.0          rlang_1.3.0         jsonlite_2.0.0