diff options
| author | Pjotr <wrk@bosa.lan> | 2026-11-09 13:00:47 +0000 |
|---|---|---|
| committer | Pjotr <wrk@bosa.lan> | 2026-11-09 13:00:47 +0000 |
| commit | 216d1491435cce156f89a01684eb5c07e07db31e (patch) | |
| tree | ee9eb9b183a60c4916ae9d26c60d7a26876a1fc6 /src | |
| parent | c560ce726bc0c45ac87b8f0f9bf83870e25ac195 (diff) | |
| download | genenetwork4-216d1491435cce156f89a01684eb5c07e07db31e.tar.gz | |
compute: report GEMMA's effect size next to the score
A GEMMA row now carries the effect beside the p-value it belongs to: `… beta, se, l_mle, additive, p_lrt`. `additive` is `-beta/2`, which is what GeneNetwork's own tables and CSV call the additive effect (gn2/wqflask/marker_regression/gemma_mapping.py:240). Halved because half the difference between the two homozygotes is the usual additive effect; negated because GN2's BIMBAM conversion codes `@mat` as 1, so GEMMA's beta is per *maternal* copy while GeneNetwork's published sign is anchored on the other allele. Two facts that make this worth doing carefully: * `beta` and `se` are left exactly where GEMMA put them. `se` is what makes the effect interpretable (`beta +/- 1.96*se` is a 95% interval) and both are GEMMA's own numbers, so replacing them with a derived one would lose information; * the derived column goes *before* the p-value, not after it. `p_lrt` must stay the last column: `gemma::peak_marker` reads `row.last()` for the peak (and with it the PheWAS and plot suggestions), and the plotters and the docs all say "the last column is the p-value". Appending would have silently pointed every peak at an effect size. The response also says what the three columns mean, and that they describe *this run* on these samples and this genotype version -- not the `additive` trait info reports, which came from the published mapping (trait 20010: this run -0.54, published +2.118, same peak marker). Nothing is added when GEMMA wrote no `beta` (a non-LMM run): the columns are then exactly GEMMA's. * src/gemma.rs: `with_effect_size`, applied by `parse_assoc_file`, so /compute/gemma and /compute/gemma/ravanan both get it. * src/routes/gemma.rs: the note. * tests: four unit tests (placement, sign and halving, `peak_marker` still finds the peak from the last column, a table without beta untouched, a null effect for a row with `NA` beta) and one end-to-end test asserting the column sits immediately before `p_lrt`, every value is `-beta/2`, `p_lrt` stays a probability, and the note is there. * README.md (the response example and what the column means), docs/www/SKILL.md (how to read and quote it). 286 tests pass; the same four as before do not.
Diffstat (limited to 'src')
| -rw-r--r-- | src/gemma.rs | 121 | ||||
| -rw-r--r-- | src/routes/gemma.rs | 11 |
2 files changed, 131 insertions, 1 deletions
diff --git a/src/gemma.rs b/src/gemma.rs index 124d68c..6da1d8d 100644 --- a/src/gemma.rs +++ b/src/gemma.rs @@ -266,7 +266,7 @@ fn parse_assoc_file(contents: &str) -> (Vec<String>, Vec<Vec<Value>>) { return (Vec::new(), Vec::new()); }; let columns: Vec<String> = header.split('\t').map(str::to_string).collect(); - let rows = lines + let rows: Vec<Vec<Value>> = lines .filter(|line| !line.is_empty()) .map(|line| { line.split('\t') @@ -279,6 +279,50 @@ fn parse_assoc_file(contents: &str) -> (Vec<String>, Vec<Vec<Value>>) { .collect() }) .collect(); + with_effect_size(columns, rows) +} + +/// Add the effect size GeneNetwork's own displays pair with the score. +/// +/// GEMMA already reports `beta` (its per-copy effect) and `se`, but in +/// GEMMA's own vocabulary and in GEMMA's own column order, where the +/// score is the last column and the effect is four columns earlier. +/// GeneNetwork's tables and CSV pair the two as **`additive` = +/// `−beta/2`** (GN2's `marker_regression/gemma_mapping.py`): halved, +/// because half the difference between the two homozygotes is the usual +/// additive effect, and negated, because GN2's BIMBAM conversion codes +/// `@mat` as 1 so GEMMA's beta is per *maternal* copy while GeneNetwork's +/// published sign convention is anchored on the other allele. +/// +/// The column goes **immediately before the score**, so a row reads +/// `… beta, se, l_mle, additive, p_lrt` -- next to the score, without +/// moving anything GEMMA wrote and without breaking "the last column is +/// the p-value", which `peak_marker` and the plotter both rely on. +/// +/// `beta` and `se` stay: `se` is what makes the effect interpretable, and +/// they are GEMMA's own numbers. Nothing is added when `beta` is absent +/// (a non-LMM run) -- the columns are then exactly GEMMA's. +fn with_effect_size( + mut columns: Vec<String>, + mut rows: Vec<Vec<Value>>, +) -> (Vec<String>, Vec<Vec<Value>>) { + let Some(beta_at) = columns.iter().position(|name| name == "beta") else { + return (columns, rows); + }; + // Before the score: the last column, which this module and the + // plotters treat as the p-value. + let score_at = columns.len().saturating_sub(1); + if score_at == 0 || !columns[score_at].starts_with('p') || score_at <= beta_at { + return (columns, rows); + } + for row in rows.iter_mut() { + let additive = match row.get(beta_at).and_then(Value::as_f64) { + Some(beta) => serde_json::json!(-beta / 2.0), + None => Value::Null, + }; + row.insert(score_at, additive); + } + columns.insert(score_at, "additive".to_string()); (columns, rows) } @@ -1060,3 +1104,78 @@ mod tests { ); } } + +#[cfg(test)] +mod effect_size_tests { + use super::*; + + fn header() -> &'static str { + "chr\trs\tps\tn_miss\tallele1\tallele0\taf\tbeta\tse\tl_mle\tp_lrt\n" + } + + /// The column GeneNetwork pairs with the score, in GeneNetwork's + /// convention: `additive = -beta/2`, placed immediately before the + /// p-value column so nothing else moves. + #[test] + fn the_additive_effect_sits_just_before_the_score() { + let contents = format!( + "{}1\trs1\t1000\t0\tX\tY\t0.3\t2.0\t0.5\t1.0\t0.01\n\ + 1\trs2\t2000\t0\tX\tY\t0.2\t-1.5\t0.4\t1.0\t0.2\n", + header() + ); + let (columns, rows) = parse_assoc_file(&contents); + assert_eq!( + columns, + vec![ + "chr", "rs", "ps", "n_miss", "allele1", "allele0", "af", "beta", "se", "l_mle", + "additive", "p_lrt" + ] + ); + // GEMMA's own numbers are untouched, in place... + assert_eq!(rows[0][7], serde_json::json!(2.0), "beta stays at index 7"); + assert_eq!(rows[0][8], serde_json::json!(0.5), "se stays at index 8"); + // ... and the derived column is next to the score, with the sign + // and halving GN2 uses. + assert_eq!(rows[0][10], serde_json::json!(-1.0), "additive = -beta/2"); + assert_eq!(rows[1][10], serde_json::json!(0.75), "sign follows beta"); + assert_eq!(rows[0][11], serde_json::json!(0.01), "p_lrt is still last"); + } + + /// Peak detection reads the last column; that must survive the + /// insertion, or every GEMMA peak link would silently point at an + /// effect size instead of a p-value. + #[test] + fn the_peak_is_still_the_smallest_last_column() { + let contents = format!( + "{}1\trs1\t1000\t0\tX\tY\t0.3\t2.0\t0.5\t1.0\t0.01\n\ + 1\trs2\t2000\t0\tX\tY\t0.2\t9.0\t0.4\t1.0\t1e-06\n", + header() + ); + let (_, rows) = parse_assoc_file(&contents); + let rows = Value::Array(rows.into_iter().map(Value::Array).collect()); + assert_eq!(peak_marker(&rows).as_deref(), Some("rs2")); + } + + /// A table without `beta` (a non-LMM run) is left exactly as GEMMA + /// wrote it. + #[test] + fn a_table_without_beta_is_untouched() { + let contents = "chr\trs\tps\tn_miss\tn_obs\tallele1\tallele0\taf\tscore\n\ + 1\trs1\t1000\t0\t8\tX\tY\t0.3\t0.5\n"; + let (columns, rows) = parse_assoc_file(contents); + assert_eq!(columns, vec!["chr", "rs", "ps", "n_miss", "n_obs", "allele1", "allele0", "af", "score"]); + assert_eq!(rows[0].len(), 9); + } + + /// A missing beta in one row is a null effect, not a shifted row. + #[test] + fn a_row_without_beta_gets_a_null_effect() { + let contents = format!( + "{}1\trs1\t1000\t0\tX\tY\t0.3\tNA\t0.5\t1.0\t0.01\n", + header() + ); + let (_, rows) = parse_assoc_file(&contents); + assert_eq!(rows[0].len(), 12); + assert_eq!(rows[0][10], Value::Null); + } +} diff --git a/src/routes/gemma.rs b/src/routes/gemma.rs index 6d5bcd8..78eb9e0 100644 --- a/src/routes/gemma.rs +++ b/src/routes/gemma.rs @@ -453,6 +453,17 @@ pub async fn compute_gemma( .with_note(&format!("Trait: {}", request_trait_label)) .with_note( "Rows come from GEMMA's own .assoc.txt output, positional (see meta.columns for names); column names depend on the lmm value used.", + ) + .with_note( + "Effect size: `beta` is GEMMA's effect per copy of the maternal allele on the \ + trait's own scale and `se` its standard error (95% CI = beta +/- 1.96*se); \ + `additive` is the same effect in GeneNetwork's convention, -beta/2 -- halved \ + because half the difference between the two homozygotes is the usual additive \ + effect, and negated because GEMMA counts maternal copies while GeneNetwork's \ + published sign is anchored on the other allele. It sits just before the \ + p-value, which stays the last column. These describe *this run*, on these \ + samples and this genotype version -- not the `additive` trait info reports, \ + which came from the published mapping.", ); for note in &output.notes { envelope = envelope.with_note(note); |
