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