use crate::error::{BarracudaError, Result};
#[derive(Debug, Clone, Copy)]
pub struct FstResult {
pub fst: f64,
pub f_is: f64,
pub f_it: f64,
}
pub fn fst_variance_decomposition(
allele_freqs: &[f64],
population_sizes: &[usize],
) -> Result<FstResult> {
let r = allele_freqs.len();
if r != population_sizes.len() {
return Err(BarracudaError::InvalidInput {
message: format!(
"fst_variance_decomposition: allele_freqs len {} != population_sizes len {}",
allele_freqs.len(),
population_sizes.len()
),
});
}
if r < 2 {
return Err(BarracudaError::InvalidInput {
message: "fst_variance_decomposition requires at least 2 populations".to_string(),
});
}
let n: Vec<f64> = population_sizes.iter().map(|&s| s as f64).collect();
let n_total: f64 = n.iter().sum();
if n_total < 1.0 {
return Err(BarracudaError::InvalidInput {
message: "fst_variance_decomposition: total sample size must be >= 1".to_string(),
});
}
for (i, &p) in allele_freqs.iter().enumerate() {
if !(0.0..=1.0).contains(&p) {
return Err(BarracudaError::InvalidInput {
message: format!(
"fst_variance_decomposition: allele_freqs[{i}] = {p} must be in [0,1]"
),
});
}
}
let n_bar = n.iter().sum::<f64>() / r as f64;
if n_bar <= 1.0 {
return Err(BarracudaError::InvalidInput {
message: "fst_variance_decomposition: mean sample size must be > 1".to_string(),
});
}
let n_c = (n_total - n.iter().map(|ni| ni * ni).sum::<f64>() / n_total) / (r - 1) as f64;
if n_c <= 0.0 {
return Err(BarracudaError::InvalidInput {
message: "fst_variance_decomposition: n_c <= 0 (check population sizes)".to_string(),
});
}
let p_bar: f64 = allele_freqs
.iter()
.zip(n.iter())
.map(|(p, ni)| p * ni)
.sum::<f64>()
/ n_total;
let s_squared: f64 = allele_freqs
.iter()
.zip(n.iter())
.map(|(p, ni)| ni * (p - p_bar) * (p - p_bar))
.sum::<f64>()
/ (n_bar * (r - 1) as f64);
let h_bar = 2.0 * p_bar * (1.0 - p_bar);
let a = (n_bar / n_c)
* (1.0 / (n_bar - 1.0)).mul_add(
-(p_bar.mul_add(1.0 - p_bar, -((r - 1) as f64 * s_squared / r as f64)) - h_bar / 4.0),
s_squared,
);
let b = (n_bar / (n_bar - 1.0))
* (p_bar.mul_add(1.0 - p_bar, -((r - 1) as f64 * s_squared / r as f64))
- (2.0f64.mul_add(n_bar, -1.0) * h_bar / (4.0 * n_bar)));
let c = h_bar / 2.0;
let denom = a + b + c;
let fst = if denom.abs() > 1e-300 { a / denom } else { 0.0 };
let denom_bc = b + c;
let f_is = if denom_bc.abs() > 1e-300 {
1.0 - c / denom_bc
} else {
0.0
};
let f_it = if denom.abs() > 1e-300 {
1.0 - c / denom
} else {
0.0
};
Ok(FstResult { fst, f_is, f_it })
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn complete_fixation_between_pops() {
let freqs = [0.0, 1.0];
let sizes = [10, 10];
let r = fst_variance_decomposition(&freqs, &sizes).expect("ok");
assert!(
r.fst > 0.9,
"complete fixation should give FST ≈ 1, got {}",
r.fst
);
}
#[test]
fn no_differentiation() {
let freqs = [0.5, 0.5, 0.5];
let sizes = [1000, 1000, 1000];
let r = fst_variance_decomposition(&freqs, &sizes).expect("ok");
assert!(
r.fst.abs() < 0.01,
"no differentiation should give FST ≈ 0, got {}",
r.fst
);
}
#[test]
fn moderate_differentiation() {
let freqs = [0.2, 0.5, 0.8];
let sizes = [100, 100, 100];
let r = fst_variance_decomposition(&freqs, &sizes).expect("ok");
assert!(
r.fst > 0.0 && r.fst < 1.0,
"moderate diff: FST in (0,1), got {}",
r.fst
);
}
#[test]
fn relationship_fis_fit_fst() {
let freqs = [0.3, 0.7];
let sizes = [50, 50];
let r = fst_variance_decomposition(&freqs, &sizes).expect("ok");
let lhs = 1.0 - r.f_it;
let rhs = (1.0 - r.f_is) * (1.0 - r.fst);
assert!(
(lhs - rhs).abs() < 1e-10,
"(1-FIT) = (1-FIS)(1-FST): lhs={lhs}, rhs={rhs}"
);
}
#[test]
fn len_mismatch_rejected() {
let r = fst_variance_decomposition(&[0.5, 0.5], &[10, 10, 10]);
assert!(r.is_err());
}
#[test]
fn single_pop_rejected() {
let r = fst_variance_decomposition(&[0.5], &[10]);
assert!(r.is_err());
}
#[test]
fn invalid_freq_rejected() {
let r = fst_variance_decomposition(&[0.5, 1.5], &[10, 10]);
assert!(r.is_err());
}
}