Skip to contents

Functionally update a multisite simulation design

Source: R/class-multisitedgp_design.R
update_multisitedgp_design.Rd

Return a new multisitedgp_design with one or more fields changed, preserving immutability. Useful when sweeping a single parameter across a scenario grid, when correcting a constructor argument without rebuilding from scratch, or when handing a partially-updated design to design_grid as a base_design.

Usage

update_multisitedgp_design(design, ...)

Arguments

design

A multisitedgp_design object.

...

Fields to update using flat multisitedgp_design argument names. Unknown names error with a friendly hint.

Value

A new multisitedgp_design object (the original is unchanged).

Details

Updates are replayed through multisitedgp_design() so the result is fully validated. When dependence changes and record_permutation equals the old method's constructor default, the new method's default is recomputed; values that differ from the old method's default are carried forward. The design stores only the resolved value, not whether it was supplied explicitly.

Unknown update field names trigger a typed error pointing the caller to the canonical multisitedgp_design() argument list — no silent acceptance.

References

Lee, J., Che, J., Rabe-Hesketh, S., Feller, A., & Miratrix, L. (2025). Improving the estimation of site-specific effects and their distribution in multisite trials. Journal of Educational and Behavioral Statistics, 50(5), 731–764. doi:10.3102/10769986241254286 .

See also

multisitedgp_design for the constructor; validate_multisitedgp_design for the standalone constructor-replay validator; design_grid for the base_design reuse pattern that relies on this function under the hood; is_multisitedgp_design for the predicate test.

Other family-design: as_tibble.multisitedgp_data(), design_grid(), is_multisitedgp_data(), is_multisitedgp_design(), multisitedgp_design(), print.multisitedgp_data(), summary.multisitedgp_data(), validate_multisitedgp_design()

Examples

# Update a single field.
design <- multisitedgp_design(J = 20L, sigma_tau = 0.20)
design2 <- update_multisitedgp_design(design, sigma_tau = 0.25)
design2$sigma_tau   # 0.25
#> [1] 0.25
design$sigma_tau    # 0.20 (original unchanged)
#> [1] 0.2

# Switch dependence method; record_permutation default updates accordingly.
design3 <- update_multisitedgp_design(design, dependence = "rank",
                                      rank_corr = 0.3)
design3$dependence_spec$method   # "rank"
#> [1] "rank"