emmeans R Package

For Bayesian models where the post.beta slot is populated with posterior samples, functions like emmeans, contrast, emtrends, and regrid apply their transformations to every row in the posterior sample.

When summary() is called on such an object, it automatically uses summary.hpd (Highest Posterior Density) instead of frequentist methods, provided frequentist = FALSE is set (or the default behavior is used). This allows for direct summarization of back-transformed posterior samples without needing the delta method.

The Satterthwaite method is used to estimate degrees of freedom ($\nu$) by assuming a variance estimator $W$ is proportional to a $\chi^2$ random variable. The degrees of freedom are estimated using the formula $\hat\nu = 2W^2 / \hat{\text{var}}(W)$.

In emmeans, the implementation depends on the model type:

• For nlme::gls objects: The package calculates the Jacobian of the variance matrix of the random effects using the gls_grad function.
• For lme4::mermod and nlme::lme objects: Since the variance matrix is not directly available, an approximate method ("appx-satterthwaite") is used. This method employs the gradV.kludge function, which perturbs response values slightly and refits the model to estimate the required variances.

The emmeans package assesses the estimability of predictions. This is critical when working with rank-deficient model matrices, where multiple solutions for fixed effects exist. A prediction $x'\beta$ is considered estimable if it remains the same regardless of which solution for $\beta$ is used. Mathematically, $x'\beta$ is estimable if and only if $x$ is in the row space of the model matrix $X$.

To perform this assessment, emmeans uses the estimability package to create a basis $N$ for the null space of $X$ (where $XN=0$). A prediction is estimable if $x'N=0$. The basis matrix $N$ is stored in the @nbasis slot of an emmGrid object.

Once checks are passed, follow these steps to submit:

1. Visit the CRAN submissions site.
2. Enter your name and email, select your tar.gz file, and upload.
3. Verification: You will receive a confirmation email. You must click the link in that email to verify your identity and confirm you have reviewed the CRAN policies and check results.
4. After verification, the submission process proceeds. You may receive follow-up emails regarding preliminary checks or potential failures in reverse dependency checks.

# To release without running checks (if already checked)
devtools::release(check = FALSE)

When performing post hoc analyses with emmeans, avoid blindly piping results into subsequent code blocks (e.g., using %>% or |>).

Why? Most emmeans functions produce results with critical annotations, such as:

• Transformations applied
• P-value adjustment methods
• Families used for adjustments

If you pipe results directly into further processing without inspecting them, you lose visibility into these statistical annotations, which can lead to incorrect interpretations.

You can install the stable version from CRAN or the latest development version from GitHub.

Install from CRAN

Visit the CRAN page for the latest stable release.

Install from GitHub (Development Version)

To install the latest development version, use the remotes package. Windows users should ensure Rtools is installed first.

remotes::install_github("rvlenth/emmeans", dependencies = TRUE, build_vignettes = TRUE)

Note: You can omit build_vignettes = TRUE to speed up installation if you do not need the vignettes immediately.

To prepare the package for CRAN, you need to build a source package (tarball) and run R CMD check to ensure it meets requirements.

Option 1: Command Line (Manual)

1. Build the tarball:

devtools::build(manual = TRUE)

2. Check the tarball (run in a shell/DOS window):

R CMD check --as-cran emmeans-xxx.tar.gz

Note: If you encounter errors, try manually deleting the emmeans.Rcheck/ directory before re-running the check.

Option 2: devtools (Integrated)

You can combine building and checking into a single step in an R session:

devtools::check(manual = TRUE, cran = TRUE)

# Build and check in one step
devtools::check(manual = TRUE, cran = TRUE)

Before submitting to CRAN, it is recommended to check the package against the R-devel version using the Win-Builder service:

1. Go to the Win-Builder site.
2. Select the second option: R-devel.
3. Upload your tar.gz file.
4. Wait approximately one hour for the check to complete.
5. If the status returns Status: OK, the package is ready for CRAN submission.

The emmeans vignettes use HTML comments to compile a simple index. If you add or change vignettes, you must manually update the index by running vigindex::vigindex(). This generates a new vignette named vigindex.Rmd.

Typical index tags follow this format:

<!-- @index Transformations; 
            Transformations!Bias correction;
            Examples!`pigs`   -->

Note: The closing comment tag --> must be on the same line as the last entry. Entries starting with a prefix followed by ! (e.g., Transformations!Bias correction) create sub-entries.

By default, emmeans uses an optimal-digits algorithm that rounds results to a useful number of digits relative to the confidence limits. This prevents cluttered output.

If you prefer standard R rounding behavior, you can disable this routine using the opt.digits option.

Note: The values stored in emm_summary objects are the actual unrounded values; only the displayed output is affected by this setting.

# Example of disabling optimal rounding (conceptually)
# Use opt.digits = FALSE in relevant functions if available