Add validation to ensure es_type parameter is only used with effectsize = "boot"

[Copilot]

Summary

This PR adds validation to ensure that the es_type parameter can only be used when effectsize = "boot" in estimate_contrasts(), addressing issue #575.

Problem

Previously, users could specify es_type with any value of effectsize, even though this parameter only applies when effectsize = "boot". This could lead to confusion as the parameter would be silently ignored for other effect size methods ("emmeans", "marginal", or NULL).

As noted in the issue:

es_type only applies when using effectsize = "boot". We should probably throw an error when attempting to specify es_type when effectsize != "boot".

Solution

Added validation that throws an informative error when es_type is explicitly provided but effectsize is not "boot":

# ❌ This now throws an error
estimate_contrasts(model, effectsize = "emmeans", es_type = "hedges.g")
# Error: `es_type` can only be used when `effectsize = "boot"`.

# ✅ This works correctly
estimate_contrasts(model, effectsize = "boot", es_type = "hedges.g")

# ✅ This also works (es_type not explicitly specified)
estimate_contrasts(model, effectsize = "emmeans")

Implementation Details

The validation uses match.call() to detect whether the user explicitly provided the es_type parameter. This approach:

• Prevents false positives when the default value is used internally
• Provides clear, actionable error messages
• Maintains backward compatibility for code that doesn't explicitly specify es_type

Changes

• Added validation logic in estimate_contrasts.default() (10 lines)
• Added comprehensive test suite covering error and success cases (36 lines)
• No documentation changes needed (existing docs already correctly describe the parameter)

Backward Compatibility

• ✅ Fully compatible: Existing code using es_type with effectsize = "boot" continues to work
• ✅ Fully compatible: Code not explicitly specifying es_type continues to work
• ⚠️ Breaking change: Code explicitly using es_type with other effectsize values will now error (this is intentional and addresses the issue)

Fixes #575

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Only allow es_type parameter when effectsize == "boot"</issue_title>
<issue_description>From #575, we should only allow es_type parameter when effectsize == "boot"

es_type only applies when using effectsize = "boot":

es_type	
Specifies the type of effect-size measure to estimate when using effectsize = "boot". One of 
"unstandardized",  "cohens.d", "hedges.g", "cohens.d.sigma", "r", or "akp.robust.d". See effect.type 
argument of bootES::bootES for details.

We should probably throw an error when attempting to specify es_type when effectsize != "boot".

So the marginal_d in the previous answer simply refers to the standardized effect size when effectsize = "marginal".</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #576

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[Copilot]

Pull Request Overview

This PR adds validation to ensure that the es_type parameter can only be used when effectsize = "boot" in estimate_contrasts(), addressing issue #575. The change prevents silent parameter ignoring and provides clear error messages when the parameter is misused.

Key changes:

• Added validation logic using match.call() to detect explicit es_type usage
• Added comprehensive test coverage for both error and success cases
• Fixed a spelling error in documentation from "representiv" to "representative"

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

File	Description
R/estimate_contrasts.R	Added validation logic to check es_type usage with appropriate effectsize values
tests/testthat/test-estimate_contrasts_effectsize.R	Added comprehensive test suite and reformatted existing tests for better readability
man/estimate_means.Rd	Fixed spelling error in documentation
inst/WORDLIST	Updated word list for spell checking

Comments suppressed due to low confidence (1)

man/estimate_means.Rd:1

• Corrected spelling of 'representiv' to 'representative'.

% Generated by roxygen2: do not edit by hand

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[strengejacke]

I think we should move these checks into the function that computes the effect sizes, .estimate_contrasts_effectsize().

[rempsyc]

But then we have a minor problem with the default effectsize = NULL (with es_type still specified) because then the checks get skipped and people will not see the error and therefore not understand why es_type is being ignored (or perceived as incorrect values):

modelbased/R/estimate_contrasts.R

Lines 366 to 376 in f2ba8b3

	if (!is.null(effectsize)) {
	out <- .estimate_contrasts_effectsize(
	model = model,
	estimated = estimated,
	contrasts_results = out,
	effectsize = effectsize,
	bootstraps = iterations,
	bootES_type = es_type,
	backend = backend
	)
	}

There's another area of confusion. If people are not allowed to manually specify es_type = "cohens.d" and be faced with the error, they might be confused as to why the defaultis es_type = "cohens.d" nonetheless? So if we change the default to es_type = NULL, then we possibly resolve this ambiguity and also the above problem (so checks can stay within .estimate_contrasts_effectsize()).