1use crate::allocation::{allocate_for_budget, allocate_for_variance, Stratum};
17
18#[derive(Clone, Copy, Debug)]
20pub struct Domain {
21 pub size: usize,
22 pub mean: f64,
23 pub sd: f64,
24}
25
26#[derive(Clone, Copy, Debug)]
28pub struct DualFrame {
29 pub a: Domain,
30 pub ab: Domain,
31 pub b: Domain,
32 pub cost_a: f64,
34 pub cost_b: f64,
35 pub deff_a: f64,
37 pub deff_b: f64,
38}
39
40#[derive(Clone, Copy, Debug)]
42pub enum Target {
43 Variance(f64),
45 Budget(f64),
47}
48
49#[derive(Clone, Debug, PartialEq)]
50pub struct DualFrameAllocation {
51 pub n_a: usize,
52 pub n_b: usize,
53 pub theta: f64,
54 pub cost: f64,
55 pub variance: f64,
56 pub variance_a: f64,
58 pub variance_b: f64,
59 pub overlap_a: f64,
61 pub overlap_b: f64,
62 pub bounded: bool,
63}
64
65fn validate(f: &DualFrame) -> Result<(), String> {
66 for (name, d) in [("a", f.a), ("ab", f.ab), ("b", f.b)] {
67 if !d.mean.is_finite() || !d.sd.is_finite() || d.sd < 0.0 {
68 return Err(format!("domain {name} has an invalid mean or sd"));
69 }
70 }
71 if f.a.size + f.ab.size < 2 || f.b.size + f.ab.size < 2 {
72 return Err("each frame needs at least two units".into());
73 }
74 if !(f.cost_a > 0.0 && f.cost_b > 0.0 && f.cost_a.is_finite() && f.cost_b.is_finite()) {
75 return Err("costs per unit must be positive".into());
76 }
77 if !(f.deff_a > 0.0 && f.deff_b > 0.0) {
78 return Err("design effects must be positive".into());
79 }
80 Ok(())
81}
82
83fn frame_sd(only: Domain, overlap: Domain, theta: f64) -> f64 {
87 let n = (only.size + overlap.size) as f64;
88 let m1 = (only.size as f64 * only.mean + overlap.size as f64 * theta * overlap.mean) / n;
89 let m2 = (only.size as f64 * (only.sd * only.sd + only.mean * only.mean)
90 + overlap.size as f64
91 * theta
92 * theta
93 * (overlap.sd * overlap.sd + overlap.mean * overlap.mean))
94 / n;
95 (m2 - m1 * m1).max(0.0).sqrt()
96}
97
98fn strata_for(f: &DualFrame, theta: f64) -> [Stratum; 2] {
99 [
100 Stratum {
101 size: f.a.size + f.ab.size,
102 sd: frame_sd(f.a, f.ab, theta) * f.deff_a.sqrt(),
103 cost: f.cost_a,
104 },
105 Stratum {
106 size: f.b.size + f.ab.size,
107 sd: frame_sd(f.b, f.ab, 1.0 - theta) * f.deff_b.sqrt(),
108 cost: f.cost_b,
109 },
110 ]
111}
112
113fn solve(f: &DualFrame, theta: f64, target: Target) -> Result<DualFrameAllocation, String> {
114 let strata = strata_for(f, theta);
115 let a = match target {
116 Target::Variance(v) => allocate_for_variance(&strata, v)?,
117 Target::Budget(c) => allocate_for_budget(&strata, c)?,
118 };
119 let var_of = |h: usize| {
120 let s = strata[h];
121 let big_n = s.size as f64;
122 let nh = a.n[h] as f64;
123 big_n * big_n * s.sd * s.sd / nh * (1.0 - nh / big_n)
124 };
125 let (va, vb) = (var_of(0), var_of(1));
126 Ok(DualFrameAllocation {
127 n_a: a.n[0],
128 n_b: a.n[1],
129 theta,
130 cost: a.cost,
131 variance: va + vb,
132 variance_a: va,
133 variance_b: vb,
134 overlap_a: a.n[0] as f64 * f.ab.size as f64 / (f.a.size + f.ab.size) as f64,
135 overlap_b: a.n[1] as f64 * f.ab.size as f64 / (f.b.size + f.ab.size) as f64,
136 bounded: a.bounded,
137 })
138}
139
140fn objective(x: &DualFrameAllocation, target: Target) -> f64 {
142 match target {
143 Target::Variance(_) => x.cost,
144 Target::Budget(_) => x.variance,
145 }
146}
147
148pub fn dual_frame_allocation(
151 f: &DualFrame,
152 theta: Option<f64>,
153 target: Target,
154) -> Result<DualFrameAllocation, String> {
155 validate(f)?;
156 match target {
157 Target::Variance(v) if !(v > 0.0 && v.is_finite()) => {
158 return Err("the target variance must be positive".into())
159 }
160 Target::Budget(c) if !(c > 0.0 && c.is_finite()) => {
161 return Err("the budget must be positive".into())
162 }
163 _ => {}
164 }
165 if let Some(t) = theta {
166 if !(0.0..=1.0).contains(&t) {
167 return Err("theta must lie in [0, 1]".into());
168 }
169 return solve(f, t, target);
170 }
171 let grid = 101;
173 let mut best: Option<DualFrameAllocation> = None;
174 for k in 0..grid {
175 let t = k as f64 / (grid - 1) as f64;
176 let x = solve(f, t, target)?;
177 if best
178 .as_ref()
179 .map_or(true, |b| objective(&x, target) < objective(b, target))
180 {
181 best = Some(x);
182 }
183 }
184 let b = best.unwrap();
185 let (mut lo, mut hi) = ((b.theta - 0.01).max(0.0), (b.theta + 0.01).min(1.0));
186 let phi = (5f64.sqrt() - 1.0) / 2.0;
187 for _ in 0..40 {
188 let t1 = hi - phi * (hi - lo);
189 let t2 = lo + phi * (hi - lo);
190 let f1 = objective(&solve(f, t1, target)?, target);
191 let f2 = objective(&solve(f, t2, target)?, target);
192 if f1 <= f2 {
193 hi = t2;
194 } else {
195 lo = t1;
196 }
197 }
198 let t = (lo + hi) / 2.0;
199 let x = solve(f, t, target)?;
200 Ok(if objective(&x, target) <= objective(&b, target) {
201 x
202 } else {
203 b
204 })
205}
206
207#[cfg(test)]
208mod tests {
209 use super::*;
210
211 fn frame() -> DualFrame {
212 DualFrame {
213 a: Domain {
214 size: 8000,
215 mean: 5.0,
216 sd: 6.0,
217 },
218 ab: Domain {
219 size: 1500,
220 mean: 40.0,
221 sd: 30.0,
222 },
223 b: Domain {
224 size: 500,
225 mean: 60.0,
226 sd: 50.0,
227 },
228 cost_a: 200.0,
229 cost_b: 40.0,
230 deff_a: 1.0,
231 deff_b: 1.0,
232 }
233 }
234
235 #[test]
236 fn optimal_theta_beats_fixed_choices() {
237 let f = frame();
238 let opt = dual_frame_allocation(&f, None, Target::Budget(100_000.0)).unwrap();
239 for t in [0.0, 0.25, 0.5, 0.75, 1.0] {
240 let fixed = dual_frame_allocation(&f, Some(t), Target::Budget(100_000.0)).unwrap();
241 assert!(opt.variance <= fixed.variance + 1e-6, "theta {t}");
242 assert!(fixed.cost <= 100_000.0 + 1e-6);
243 }
244 assert!(opt.theta < 0.5, "theta {}", opt.theta);
246 assert!(opt.n_a >= 2 && opt.n_b >= 2);
247 assert!((opt.overlap_a - opt.n_a as f64 * 1500.0 / 9500.0).abs() < 1e-9);
248 }
249
250 #[test]
251 fn variance_target_is_met_at_minimum_cost() {
252 let f = frame();
253 let x = dual_frame_allocation(&f, None, Target::Variance(1e8)).unwrap();
254 assert!(x.variance <= 1e8 * 1.001, "variance {}", x.variance);
255 for t in [0.0, 0.5, 1.0] {
256 let y = dual_frame_allocation(&f, Some(t), Target::Variance(1e8)).unwrap();
257 assert!(x.cost <= y.cost + 1e-6);
258 }
259 assert!(dual_frame_allocation(&f, Some(1.5), Target::Budget(1.0)).is_err());
260 assert!(dual_frame_allocation(&f, None, Target::Budget(-1.0)).is_err());
261 }
262
263 #[test]
264 fn frame_sd_matches_direct_computation() {
265 let a = Domain {
267 size: 2,
268 mean: 2.0,
269 sd: 1.0,
270 };
271 let ab = Domain {
272 size: 2,
273 mean: 15.0,
274 sd: 5.0,
275 };
276 let vals = [1.0, 3.0, 5.0, 10.0];
277 let m = vals.iter().sum::<f64>() / 4.0;
278 let sd = (vals.iter().map(|v| (v - m).powi(2)).sum::<f64>() / 4.0).sqrt();
279 assert!((frame_sd(a, ab, 0.5) - sd).abs() < 1e-12);
280 }
281}