203 conditional effects bmmfit

[GidonFrischkorn]

Summary

• Implement conditional_effects() S3 method for bmmfit objects, providing an intuitive interface to visualize predictor effects on model parameters ([feature-request] Adapt S3 method conditional_effects to bmmfit objects. #203)
• Add shared parameter helper functions (.get_parameter_info(), .is_softmax_param(), link_transform()) to helpers-parameters.R
• Update link specifications in mixture model objects to reflect actual transformations

Key changes

conditional_effects.bmmfit()

• Accepts model parameter names directly via par (e.g., "kappa", "thetat") and automatically routes to the correct brms dpar/nlpar
• Supports scale = "native" (default) to show parameters on their natural scale via inverse link transformations, or scale = "sampling" to show on the MCMC sampling scale
• Handles softmax-transformed parameters (thetat, thetant in mixture3p) correctly
• Filters internal model variables (e.g., fixed parameters, internal mixture components) from the output
• Works for single parameters or all estimated parameters at once (par = NULL)

Link corrections in mixture model objects

• mixture2p: thetat link changed from "identity" to "logit" — the mixing weight is estimated on the logit scale, and the link specification now reflects this
• mixture3p: thetat and thetant links changed from "identity" to "softmax" — these weights go through a softmax transformation, which is now explicitly declared

These link corrections are necessary for conditional_effects() to apply the correct inverse transformations when displaying parameters on their natural scale.

Shared helpers (helpers-parameters.R)

• link_transform(): forward/inverse link transformations for all brms link functions
• .get_parameter_info(): classifies a parameter as dpar/nlpar, retrieves its link, and detects softmax
• .is_softmax_param(): identifies parameters subject to softmax transformation

Test plan

• Unit tests for link_transform() round-trips across all supported links
• Unit tests for .is_softmax_param() and .get_parameter_info()
• Integration tests for conditional_effects.bmmfit() with SDM, mixture2p, and mixture3p models
• Comprehensive tests covering scale transformations, softmax handling, multi-parameter mode, and edge cases

[Copilot]

Pull request overview

This PR adds a conditional_effects() S3 method for bmmfit objects to make extracting/plotting predictor effects on model parameters more intuitive, including correct back-transformations to native parameter scales (and special handling for mixture-model weight parameters). It also updates mixture-model link specifications to reflect the actual transformations used internally.

Changes:

• Add conditional_effects.bmmfit() with par + scale support, internal-effect filtering, and special softmax handling for mixture3p.
• Add shared parameter/link helper utilities (.get_parameter_info(), .is_softmax_param(), link_transform() support).
• Correct declared links for mixture-model parameters (mixture2p/mixture3p), plus documentation/vignette/pkgdown updates and expanded tests.

Reviewed changes

Copilot reviewed 19 out of 21 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
R/conditional_effects.R	New conditional_effects.bmmfit() implementation + internal helpers (filtering, softmax path, multinomial path).
R/helpers-parameters.R	Adds internal helpers to classify parameters and detect softmax parameters.
R/model_mixture2p.R	Updates thetat link from identity to logit.
R/model_mixture3p.R	Updates thetat/thetant links from identity to softmax.
R/reexports.R	Reexports brms::conditional_effects.
tests/testthat/test-conditional_effects.R	Adds unit + integration tests for the new method and helpers.
tests/testthat/test-helpers-parameters.R	Adds tests for .is_softmax_param() / .get_parameter_info().
tests/testthat/test-update.R / tests/testthat/test-summary.R	Switch test skipping + use system.file() fixture path.
man/conditional_effects.bmmfit.Rd	New documentation page for the method.
man/mixture2p.Rd / man/mixture3p.Rd	Update documented default links to match model objects.
vignettes/articles/bmm_conditional_effects.Rmd	New vignette demonstrating usage and scale behavior.
_pkgdown.yml	Adds reference + article entry for conditional effects.
NEWS.md	Announces the new conditional_effects() method feature.
NAMESPACE	Registers S3 method and exports conditional_effects.
.Rbuildignore / DESCRIPTION	Minor build ignore + formatting update.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.