refactor(api)!: rename ASReml residual argument rcov -> residual (ASReml 4)

ASReml-R renamed the residual-structure argument from rcov (ASReml 3) to
residual (ASReml 4). flexyBayes now follows the ASReml 4 name across the whole
surface: the residual argument on flexybayes()/fb(), fb_from_asreml(), and the
engine pins; the IR field rcov_terms -> residual_terms; the codegen and INLA
emit helpers; the refusal identifiers; the print label; docs; README; vignettes.

BREAKING CHANGE: rcov is defunct. Supplying it raises a guiding
lifecycle::deprecate_stop() pointing to residual. The residual grammar is
unchanged.

Version bumped to 0.9.0; NEWS breaking-change entry; regression test
test-residual-arg-rename.R pins the tripwire across every entry.

Implements co-author Emi Tanaka: adopt the ASReml v4 input convention.

Author: Max Moldovan

API_STABILITY.md

@@ -31,7 +31,7 @@ engine:
 
 | Export | Stage | Notes |
 |---|---|---|
-| `flexybayes()` | experimental | The asreml-style entry (`fixed`, `random`, `rcov`); also accepts brms-style and greta-style grammar via `syntax = "auto"`. `backend = c("auto", "greta", "inla", "brms", "gretaR")`, default `"auto"`. `"auto"` never routes to Stan/brms. `prior` accepts an `fb_prior()` object. |
+| `flexybayes()` | experimental | The asreml-style entry (`fixed`, `random`, `residual`); also accepts brms-style and greta-style grammar via `syntax = "auto"`. `backend = c("auto", "greta", "inla", "brms", "gretaR")`, default `"auto"`. `"auto"` never routes to Stan/brms. `prior` accepts an `fb_prior()` object. |
 | `fb()` | experimental | Literal alias for `flexybayes()`; documented but not promoted. |
 
 **Engine pins** fix one engine and therefore take **no** `backend` argument —

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: flexyBayes
 Title: Flexible Bayesian Mixed Models with ASReml and 'brms'-Style Syntax
-Version: 0.8.3
+Version: 0.9.0
 Authors@R: c(
     person("Max", "Moldovan", email = "max.moldovan@adelaide.edu.au",
            role = c("aut", "cre"),
@@ -16,7 +16,7 @@ Description: Specify mixed models using familiar ASReml or brms-style formula
     syntax and estimate them via greta, INLA, or brms (Stan). Returns results
     in formats compatible with the standard R modelling ecosystem including
     'summary()', 'emmeans', 'marginaleffects', and 'effectsize'. The package
-    translates ASReml-style formulas (fixed, random, rcov) to backend-specific
+    translates ASReml-style formulas (fixed, random, residual) to backend-specific
     code (greta, INLA, or brms) using an indexing approach that scales to large
     agricultural datasets, and supports cross-engine posterior triangulation
     as a robustness signal. Supports Gaussian, binomial, Poisson, negative

NEWS.md

@@ -1,3 +1,20 @@
+# flexyBayes 0.9.0
+
+## Breaking changes
+
+* **The residual-structure argument `rcov` is renamed to `residual`, matching
+  ASReml 4.** ASReml-R renamed this argument from `rcov` (ASReml 3) to
+  `residual` (ASReml 4); flexyBayes now follows the ASReml 4 name across every
+  entry point (`flexybayes()` / `fb()`, `fb_from_asreml()`, and the engine pins
+  `fb_greta()` / `fb_inla()` / `fb_brms()`). Supplying the old `rcov =` argument
+  now raises a guiding error pointing to `residual =`; update calls such as
+  `rcov = ~ at(env):units` to `residual = ~ at(env):units`. The residual grammar
+  itself is unchanged. The print method now labels the residual structure
+  `Residual` rather than `Rcov`, and the two associated refusal identifiers are
+  renamed to match (`rcov_type_unsupported_for_aggregation` ->
+  `residual_type_unsupported_for_aggregation`, `rcov_term_type_inla` ->
+  `residual_term_type_inla`).
+
 # flexyBayes 0.8.3
 
 A documentation-honesty and ergonomics release on the 0.8.x line. There are no

R/canonical_names.R

@@ -220,7 +220,7 @@ register_canonical_mapper <- function(backend, mapper) {
     intercept = pi$fixed$intercept %||% TRUE,
     fixed_terms = pi$fixed$terms %||% list(),
     random_terms = pi$random %||% list(),
-    rcov_terms = pi$rcov %||% list()
+    residual_terms = pi$residual %||% list()
   )
 }
 

R/codegen.R

@@ -869,22 +869,22 @@
   ctx
 }
 
-# Generate code for residual (rcov) structure
-.code_rcov <- function(ctx, rcov_terms, data) {
+# Generate code for the residual structure
+.code_residual <- function(ctx, residual_terms, data) {
   ctx <- .add(
     ctx,
     "# -- Residual ------------------------------------------------"
   )
   pvc <- ctx$prior_vc
 
   has_at_units <- any(vapply(
-    rcov_terms,
+    residual_terms,
     function(t) t$type == "at_units",
     logical(1)
   ))
 
   if (has_at_units) {
-    term <- Filter(function(t) t$type == "at_units", rcov_terms)[[1]]
+    term <- Filter(function(t) t$type == "at_units", residual_terms)[[1]]
     tag <- term$var
     ctx <- .add(
       ctx,
@@ -921,7 +921,7 @@
 }
 
 # Generate code for the likelihood
-.code_likelihood <- function(ctx, fixed_info, rcov_terms, data, weights) {
+.code_likelihood <- function(ctx, fixed_info, residual_terms, data, weights) {
   ctx <- .add(
     ctx,
     "# -- Likelihood ----------------------------------------------"

R/dispatch.R

@@ -488,7 +488,7 @@
   the_call,
   fixed,
   random,
-  rcov,
+  residual,
   family,
   link,
   data_name,
@@ -543,7 +543,7 @@
       the_call = the_call,
       fixed = fixed,
       random = random,
-      rcov = rcov,
+      residual = residual,
       family = family,
       link = link,
       data_name = data_name
@@ -602,7 +602,7 @@
       the_call = the_call,
       fixed = fixed,
       random = random,
-      rcov = rcov,
+      residual = residual,
       family = family,
       link = link,
       data_name = data_name
@@ -694,7 +694,7 @@
       the_call = the_call,
       fixed = fixed,
       random = random,
-      rcov = rcov,
+      residual = residual,
       family = family,
       link = link,
       data_name = data_name
@@ -866,7 +866,7 @@
             the_call = the_call,
             fixed = fixed,
             random = random,
-            rcov = rcov,
+            residual = residual,
             family = family,
             link = link,
             data_name = data_name
@@ -998,7 +998,7 @@
     the_call = the_call,
     fixed = fixed,
     random = random,
-    rcov = rcov,
+    residual = residual,
     family = family,
     link = link,
     data_name = data_name
@@ -1072,7 +1072,7 @@
   the_call,
   fixed,
   random,
-  rcov,
+  residual,
   family,
   link,
   data_name
@@ -1111,12 +1111,12 @@
 
   # at_units on INLA: the multi-likelihood INLA stack is still
   # deferred at v0.3.3 (queued for a later minor). If we'd otherwise
-  # route to INLA AND the rcov uses at_units, force the eff_backend
+  # route to INLA AND the residual uses at_units, force the eff_backend
   # down to greta (which supports the heterogeneous-residual aggregated
   # path) or fall through to per-row when greta isn't an option.
-  uses_at_units <- length(fb$rcov_terms) > 0L &&
+  uses_at_units <- length(fb$residual_terms) > 0L &&
     any(vapply(
-      fb$rcov_terms,
+      fb$residual_terms,
       function(t) identical(t$type %||% "", "at_units"),
       logical(1L)
     ))
@@ -1181,7 +1181,7 @@
       the_call = the_call,
       fixed = fixed,
       random = random,
-      rcov = rcov,
+      residual = residual,
       family = family,
       link = link,
       data_name = data_name
@@ -1227,7 +1227,7 @@
       the_call = the_call,
       fixed = fixed,
       random = random,
-      rcov = rcov,
+      residual = residual,
       family = family,
       link = link,
       data_name = data_name

R/emit_brms.R

@@ -58,7 +58,7 @@ emit_brms <- function(
   the_call = NULL,
   fixed = NULL,
   random = NULL,
-  rcov = NULL,
+  residual = NULL,
   family = NULL,
   link = NULL,
   data_name = NA_character_,
@@ -250,13 +250,13 @@ emit_brms <- function(
           terms = fb$fixed_terms
         ),
         random = fb$random_terms,
-        rcov = fb$rcov_terms,
+        residual = fb$residual_terms,
         family = list(family = fb$family, link = fb$link)
       ),
       call_info = list(
         fixed = fixed,
         random = random,
-        rcov = rcov,
+        residual = residual,
         data_name = data_name,
         family = family,
         link = link,

R/emit_count_aggregated.R

@@ -40,7 +40,7 @@ emit_count_aggregated <- function(
   the_call = NULL,
   fixed = NULL,
   random = NULL,
-  rcov = NULL,
+  residual = NULL,
   family = NULL,
   link = NULL,
   data_name = NA_character_
@@ -99,7 +99,7 @@ emit_count_aggregated <- function(
     the_call = the_call,
     fixed = fixed,
     random = random,
-    rcov = rcov,
+    residual = residual,
     family = family,
     link = link,
     data_name = data_name,
@@ -446,7 +446,7 @@ emit_count_aggregated <- function(
   the_call,
   fixed,
   random,
-  rcov,
+  residual,
   family,
   link,
   data_name,
@@ -504,7 +504,7 @@ emit_count_aggregated <- function(
           terms = fb$fixed_terms
         ),
         random = fb$random_terms,
-        rcov = fb$rcov_terms,
+        residual = fb$residual_terms,
         family = list(
           family = fb$family,
           link = fb$link %||% .agg_count_link(fb$family)
@@ -514,7 +514,7 @@ emit_count_aggregated <- function(
       call_info = list(
         fixed = fixed,
         random = random,
-        rcov = rcov,
+        residual = residual,
         data_name = data_name,
         family = family,
         link = link,