Skip to main content

fieldopt_core/
dualframe.rs

1//! Dual-frame allocation (Hartley 1962, 1974).
2//!
3//! Two frames cover the population: frame A (say the area frame) and frame B
4//! (the list), with an overlap. The population splits into the domains `a`
5//! (A only), `ab` (both) and `b` (B only). The Hartley estimator of the total
6//! is `Y_a + theta * Y_ab(A) + (1 - theta) * Y_ab(B) + Y_b`, where the
7//! overlap is estimated from both samples and mixed with weight `theta`.
8//!
9//! Under simple random sampling in each frame (with optional design effects
10//! for other designs), the variance is the sum of two stratum-like terms,
11//! so for a fixed `theta` the cost-optimal sizes `n_A`, `n_B` follow the
12//! cost-weighted Neyman rule; the optimal `theta` is found by a grid search
13//! with golden-section refinement. `theta = 0` is the screening design in
14//! which overlap units found in the area sample contribute nothing.
15
16use crate::allocation::{allocate_for_budget, allocate_for_variance, Stratum};
17
18/// Moments of the study variable in one domain.
19#[derive(Clone, Copy, Debug)]
20pub struct Domain {
21    pub size: usize,
22    pub mean: f64,
23    pub sd: f64,
24}
25
26/// Inputs of a dual-frame allocation.
27#[derive(Clone, Copy, Debug)]
28pub struct DualFrame {
29    pub a: Domain,
30    pub ab: Domain,
31    pub b: Domain,
32    /// Cost per sampled unit of frame A and B.
33    pub cost_a: f64,
34    pub cost_b: f64,
35    /// Design effects of the two samples relative to simple random sampling.
36    pub deff_a: f64,
37    pub deff_b: f64,
38}
39
40/// What the allocation targets.
41#[derive(Clone, Copy, Debug)]
42pub enum Target {
43    /// Minimum cost for this variance of the estimated total.
44    Variance(f64),
45    /// Minimum variance for this budget.
46    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    /// Variance contributed by each frame.
57    pub variance_a: f64,
58    pub variance_b: f64,
59    /// Expected overlap units in each sample.
60    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
83/// Population standard deviation (divisor N) of `y` times `w` over a frame
84/// made of two domains, where `w` is 1 in the first domain and `theta` in the
85/// overlap.
86fn 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
140/// Objective to minimise for the search over `theta`.
141fn objective(x: &DualFrameAllocation, target: Target) -> f64 {
142    match target {
143        Target::Variance(_) => x.cost,
144        Target::Budget(_) => x.variance,
145    }
146}
147
148/// Dual-frame allocation. With `theta = Some(t)` the mixing weight is fixed
149/// (0 is the screening design); with `None` it is optimised.
150pub 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    // grid, then golden-section refinement around the best grid point
172    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        // the cheap list should carry the overlap: theta small
245        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        // domain a: values {1, 3}; overlap: values {10, 20}; theta 0.5 -> {5, 10}
266        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}