Allocate updates 20 jul2026

[jdbunker]

Original Overview

Overhauled allocate(), especially regarding the rounding and lbound/N.h/n.samp-based adjustments

• outputs Parameter: allows user to choose between raw, adjusted, and/or final (rounded) allocations
• c.h Check: no longer listing Neyman
• sum(lbound * c.h) > cost: bumped from warning to error after edits to adjustment/rounding step
• any(lbound > N.h): gives warning
• outputs check: every value must be 'raw', 'adjusted', and/or 'rounded'
• Adjustment Step: properly routed depending on allocation method
• Rounding: stochastic to deterministic
• Documentation: updated to reflect all of the above changes
• Tests: patched existing tests based on above changes (e.g., warning to error, adjustment/rounding handling); added a few new tests

---

Expanded Overview

This PR substantially refactors allocate() to improve reproducibility, constraint handling, and transparency of the allocation process.

Outputs Argument

• Added a new outputs argument so users can return any combination of "raw", "adjusted", and "rounded" results instead of only the final allocation
• Added validation of outputs parameter before proceeding

Length: ~40 lines of code.

Why: Makes the allocation process more transparent and easier to debug, validate, and explain.

---

Adjustment Logic Overhaul

• Rewrote the post-allocation adjustment step.
• Fixed-total methods (proportional, power, Neyman) now use a dedicated adjustment routine that simultaneously respects:
  • target sample size (n.samp),
  • lower bounds (lbound), and
  • upper bounds (N.h).
• Optimal allocation now routes to method-specific adjustment logic depending on whether the allocation is cost-constrained or precision-constrained.
  • cost-constrained optimal allocation under lower-bound and budget constraints, and
  • precision-constrained optimal allocation under variance, lower-bound, and population-size constraints.

Length: ~200 lines of code.

Why: The previous adjustment process could distort allocations after lower-bound enforcement and did not explicitly account for all constraints (e.g., total cost for optimal cost and variance for optimal variance).

---

Rounding Improvements

• Replaced stochastic/randomized rounding adjustments with deterministic rounding procedures.
• Added method-specific rounding strategies that preserve allocation objectives while satisfying constraints.

Length: ~160 lines of code

Why: Results are now fully reproducible across runs and no longer depend on random selection.

---

Validation and Error Handling

• Changed sum(lbound * c.h) > cost from a warning to an error because no feasible solution exists in this case.
• Added warning when any(lbound > N.h).
• Removed the (improper) requirement/check for c.h under Neyman allocation.
• Added feasibility checks and informative warnings/errors when targets cannot be achieved.

Length: ~10 lines of code

Why: Provides clearer feedback and prevents invalid or misleading allocations from being returned.

---

Documentation Updates

• Updated documentation to describe the new outputs argument

---

Test Updates

• Updated existing tests to match the revised adjustment/rounding logic and rounding behavior.
• Added tests covering:
  • the new outputs argument,
  • upper-bound (N.h) enforcement,
  • budget enforcement in cost-constrained optimal allocation,
  • precision-constrained variance targets,
  • lbound == N.h edge cases,
  • new warnings/errors, and
  • deterministic allocation behavior.

Why: Keeps documentation and test coverage aligned with the refactored implementation.

---

Addendum

After I made yesterday's patches, I noticed that I inadvertly switched back to non-ASCII symbols. I fixed that in allocate.R and allocate.Rd today.