From 4da1cd192b243f1903147788a71ceb38930f9f92 Mon Sep 17 00:00:00 2001
From: Daniel Sabanes Bove <danielinteractive@users.noreply.github.com>
Date: Fri, 17 Nov 2023 14:53:41 +0100
Subject: [PATCH] Improve emmeans doc with pairs / new release (another CRAN
 submission round) (#373)

---
 DESCRIPTION                                   |  2 +-
 NEWS.md                                       |  2 +-
 R/interop-emmeans.R                           |  4 ++++
 man/emmeans_support.Rd                        |  4 ++++
 .../subsections/_intro-hypothesis_testing.Rmd | 24 ++++++++++++-------
 5 files changed, 25 insertions(+), 11 deletions(-)

diff --git a/DESCRIPTION b/DESCRIPTION
index f7a833f24..6abc0cb09 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,7 +1,7 @@
 Type: Package
 Package: mmrm
 Title: Mixed Models for Repeated Measures
-Version: 0.3.5.9003
+Version: 0.3.6
 Authors@R: c(
     person("Daniel", "Sabanes Bove", , "daniel.sabanes_bove@roche.com", role = c("aut", "cre")),
     person("Julia", "Dedic", , "julia.dedic@roche.com", role = "aut"),
diff --git a/NEWS.md b/NEWS.md
index f8a648eb4..ba825ce2f 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,4 +1,4 @@
-# mmrm 0.3.5.9003
+# mmrm 0.3.6
 
 ### New Features
 
diff --git a/R/interop-emmeans.R b/R/interop-emmeans.R
index 144d698ff..6240f4c90 100644
--- a/R/interop-emmeans.R
+++ b/R/interop-emmeans.R
@@ -5,6 +5,9 @@
 #' This package includes methods that allow `mmrm` objects to be used
 #' with the `emmeans` package. `emmeans` computes estimated marginal means
 #' (also called least-square means) for the coefficients of the MMRM.
+#' We can also e.g. obtain differences between groups by applying
+#' [`pairs()`][emmeans::pairs.emmGrid()] on the object returned
+#' by [emmeans::emmeans()].
 #'
 #' @examples
 #' fit <- mmrm(
@@ -13,6 +16,7 @@
 #' )
 #' if (require(emmeans)) {
 #'   emmeans(fit, ~ ARMCD | AVISIT)
+#'   pairs(emmeans(fit, ~ ARMCD | AVISIT), reverse = TRUE)
 #' }
 #' @name emmeans_support
 NULL
diff --git a/man/emmeans_support.Rd b/man/emmeans_support.Rd
index b8f383bbd..cfee60f90 100644
--- a/man/emmeans_support.Rd
+++ b/man/emmeans_support.Rd
@@ -9,6 +9,9 @@
 This package includes methods that allow \code{mmrm} objects to be used
 with the \code{emmeans} package. \code{emmeans} computes estimated marginal means
 (also called least-square means) for the coefficients of the MMRM.
+We can also e.g. obtain differences between groups by applying
+\code{\link[emmeans:contrast]{pairs()}} on the object returned
+by \code{\link[emmeans:emmeans]{emmeans::emmeans()}}.
 }
 \examples{
 fit <- mmrm(
@@ -17,5 +20,6 @@ fit <- mmrm(
 )
 if (require(emmeans)) {
   emmeans(fit, ~ ARMCD | AVISIT)
+  pairs(emmeans(fit, ~ ARMCD | AVISIT), reverse = TRUE)
 }
 }
diff --git a/vignettes/subsections/_intro-hypothesis_testing.Rmd b/vignettes/subsections/_intro-hypothesis_testing.Rmd
index a6bc1bcbd..cfa7fc610 100644
--- a/vignettes/subsections/_intro-hypothesis_testing.Rmd
+++ b/vignettes/subsections/_intro-hypothesis_testing.Rmd
@@ -72,18 +72,24 @@ course together with multidimensional contrasts.
 
 This package includes methods that allow `mmrm` objects to be used with the
 `emmeans` package. `emmeans` computes estimated marginal means (also called
-least-square means) for the coefficients of the MMRM.
+least-square means) for the coefficients of the MMRM. For example, in order
+to see the least-square means by visit and by treatment arm:
 
 ```{r emmeans}
-fit <- mmrm(
-  formula = FEV1 ~ RACE + ARMCD * AVISIT + us(AVISIT | USUBJID),
-  data = fev_data
-)
-
-if (require(emmeans)) {
-  emmeans(fit, ~ ARMCD | AVISIT)
-}
+library(emmeans)
+lsmeans_by_visit <- emmeans(fit, ~ ARMCD | AVISIT)
+lsmeans_by_visit
 ```
 
 Note that the degrees of freedom choice is inherited here from the initial `mmrm`
 fit.
+Furthermore, we can also obtain the differences between the treatment arms for each visit
+by applying `pairs()` on the object returned by `emmeans()` earlier:
+
+```{r pdiff}
+pairs(lsmeans_by_visit, reverse = TRUE)
+```
+
+(This is similar like the `pdiff` option in SAS `PROC MIXED`.)
+Note that we use here the `reverse` argument to obtain treatment minus
+placebo results, instead of placebo minus treatment results.