about summary refs log tree commit diff
path: root/src
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-09 13:00:47 +0000
committerPjotr <wrk@bosa.lan>2026-11-09 13:00:47 +0000
commit216d1491435cce156f89a01684eb5c07e07db31e (patch)
treeee9eb9b183a60c4916ae9d26c60d7a26876a1fc6 /src
parentc560ce726bc0c45ac87b8f0f9bf83870e25ac195 (diff)
downloadgenenetwork4-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.rs121
-rw-r--r--src/routes/gemma.rs11
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);