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: number of units, mean and
19/// standard deviation `S` (divisor `size - 1`, as in Cochran).
20#[derive(Clone, Copy, Debug)]
21pub struct Domain {
22    pub size: usize,
23    pub mean: f64,
24    pub sd: f64,
25}
26
27/// Inputs of a dual-frame allocation.
28#[derive(Clone, Copy, Debug)]
29pub struct DualFrame {
30    pub a: Domain,
31    pub ab: Domain,
32    pub b: Domain,
33    /// Cost per sampled unit of frame A and B.
34    pub cost_a: f64,
35    pub cost_b: f64,
36    /// Design effects of the two samples relative to simple random sampling.
37    pub deff_a: f64,
38    pub deff_b: f64,
39}
40
41/// What the allocation targets.
42#[derive(Clone, Copy, Debug)]
43pub enum Target {
44    /// Minimum cost for this variance of the estimated total.
45    Variance(f64),
46    /// Minimum variance for this budget.
47    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    /// Variance contributed by each frame.
58    pub variance_a: f64,
59    pub variance_b: f64,
60    /// Expected overlap units in each sample.
61    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
84/// Standard deviation `S` (divisor N - 1) of `y` times `w` over a frame made
85/// of two domains, where `w` is 1 in the first domain and `theta` in the
86/// overlap: the within-domain sums of squares `(N_d - 1) w_d^2 S_d^2` plus
87/// the between-domain part `N_d (w_d mu_d - mu)^2`, divided by `N - 1`.
88fn 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
141/// Objective to minimise for the search over `theta`.
142fn objective(x: &DualFrameAllocation, target: Target) -> f64 {
143    match target {
144        Target::Variance(_) => x.cost,
145        Target::Budget(_) => x.variance,
146    }
147}
148
149/// Dual-frame allocation. With `theta = Some(t)` the mixing weight is fixed
150/// (0 is the screening design); with `None` it is optimised.
151pub 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    // grid, then golden-section refinement around the best grid point
173    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        // the cheap list should carry the overlap: theta small
246        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        // domain a: values {1, 3} (S = sqrt 2); overlap: values {10, 20}
267        // (S = sqrt 50); theta 0.5 turns the overlap into {5, 10}
268        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}