about summary refs log tree commit diff
path: root/src
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-16 00:30:42 +0000
committerPjotr <wrk@bosa.lan>2026-11-16 00:30:42 +0000
commit1ae2f5d712e18c016fdb7bd04da99eab4da6915b (patch)
tree31bb20e52585506351d81198b65c13ec3a229af0 /src
parent9c3cd6f2300bb290ddd05c5a46c5b813b22c0ce1 (diff)
downloadgenenetwork4-1ae2f5d712e18c016fdb7bd04da99eab4da6915b.tar.gz
qtl2: permutations for the LOD thresholds
POST /compute/qtl2 gains nperm, perm_seed and perm_strata, and the reply
gains meta.permutation {n, seed, significant, suggestive, values} -- the
genome-wide maximum of every permutation, so a histogram needs no second
call. `data` stays the positional rows array on purpose: /plot/rqtl posts
it straight back and the monitor counts its rows, so the null went beside
the rows rather than around them (a generic Envelope::with_meta/Meta::extra,
skip_serializing_if, so no other endpoint's response changes).

Thresholds come from R/qtl2's scan1perm over the same genotype
probabilities, kinship and covariates as the scan, with chr_lengths from
the map -- without those it derives chromosome lengths from marker
positions and the numbers stop being comparable with R/qtl's. The
permutation CSV is written in R/qtl's two-column shape so one parser and
one percentile routine serve both engines: PermutationResult::from_values
is now shared with /compute/rqtl instead of duplicated.

Semantics, each with the note that says it:

* scan1perm shuffles phenotypes across individuals -- right for an
  outbred cross, only approximate for a selfing RIL panel, where qtl2perm
  is the correct package (not installed here, and not packaged);
* perm_strata takes a case attribute name (sex, Epoch, ...) and permutes
  within it, because shuffling across sexes inflates the null;
* fewer than 100 permutations gets a note that the 0.05 quantile is a
  quantile of too few values; more than 10 000 is refused, since each
  permutation is a whole genome scan;
* a seed is reported always -- without one, two identical requests would
  give different thresholds.

Cost, measured on BXD trait 10001 (34 phenotyped, 20 chromosomes, LOCO
kinship, 4 cores): 20 permutations 0.6 s, 100 in 2.2 s, 500 in 14 s,
1000 in 24 s through the API; 0.022-0.03 s per permutation. Thresholds
converge as expected (0.05: 4.331 at 100 and 200 permutations, 4.374 at
1000 on the raw probe) and are reproducible: the same seed gives the same
numbers on 1 and 4 cores.

Four things that only surfaced by running it, all commented where they
bit: optparse keeps the dash (--perm-out is opt[["perm-out"]], so
opt$perm_out was always NULL and the file landed somewhere the caller did
not look); perm_strata must be a named character vector, not a factor;
the LOD in the CSV is the LAST numeric field (R/qtl's shape puts the
permutation index first, and a first-field parser reads that as the LOD);
and percentiles interpolate at (n-1)p/100, so 100 maxima give 0.6733, not
0.67.

bin/monitor-gn4 gains compute-qtl2-perm (nperm 10, judging
meta.permutation) so a deploy that loses the R path shows up as a red
check rather than a surprise.
Diffstat (limited to 'src')
-rw-r--r--src/qtl2.rs123
-rw-r--r--src/response.rs18
-rw-r--r--src/routes/qtl2.rs195
-rw-r--r--src/rqtl.rs34
4 files changed, 370 insertions, 0 deletions
diff --git a/src/qtl2.rs b/src/qtl2.rs
index 318c2ee..2bb11f7 100644
--- a/src/qtl2.rs
+++ b/src/qtl2.rs
@@ -148,6 +148,11 @@ pub struct Qtl2Output {
     pub markers: usize,
     pub command: String,
     pub summary: String,
+    /// The permutation null, when `nperm > 0`: one genome-wide LOD maximum per
+    /// permutation, and the thresholds derived from them. `None` otherwise.
+    pub permutation: Option<crate::rqtl::PermutationResult>,
+    /// How the permutations were run, for the reply's notes.
+    pub permutation_note: Option<String>,
 }
 
 /// How many genotype cells carry one code -- the count a cached conversion
@@ -620,6 +625,7 @@ pub async fn compute(
     kinship: &str,
     model: &str,
     cores: u32,
+    permutations: Permutations<'_>,
 ) -> Result<Qtl2Output, Qtl2Error> {
     let out_dir = Path::new(cache_dir);
     std::fs::create_dir_all(out_dir).map_err(|e| io_error(out_dir, e))?;
@@ -671,6 +677,40 @@ pub async fn compute(
         args.push("--covarstruct".to_string());
         args.push(covarstruct.to_string());
     }
+    // The permutations write their own file: one LOD per permutation, in the
+    // same two-column shape R/qtl's scanone permutations produce, so the
+    // thresholds come from the same percentile code either way.
+    let perm_path = out_dir.join(format!("{unique}-perm.csv"));
+    let mut permutation_note = None;
+    let mut strata_path_arg: Option<String> = None;
+    if let Some(permutations) = permutations.enabled() {
+        if !permutations.samples.is_empty() {
+            let strata_path = out_dir.join(format!("{unique}-strata.txt"));
+            crate::rqtl::write_strata_file(&strata_path, permutations.samples)
+                .map_err(Qtl2Error::Io)?;
+            strata_path_arg = Some(strata_path.to_string_lossy().into_owned());
+        }
+        args.push("--nperm".to_string());
+        args.push(permutations.count.to_string());
+        args.push("--seed".to_string());
+        args.push(permutations.seed.to_string());
+        args.push("--perm-out".to_string());
+        args.push(perm_path.to_string_lossy().into_owned());
+        permutation_note = Some(format!(
+            "{} permutations (seed {}), strata: {}",
+            permutations.count,
+            permutations.seed,
+            if permutations.samples.is_empty() {
+                "none -- permuted across all individuals".to_string()
+            } else {
+                format!("{} (permuted within)", permutations.strata_name)
+            }
+        ));
+        if let Some(strata) = strata_path_arg.as_deref() {
+            args.push("--strata".to_string());
+            args.push(strata.to_string());
+        }
+    }
     let borrowed: Vec<&str> = args.iter().map(String::as_str).collect();
     let command = format!("Rscript {}", borrowed.join(" "));
     let output = streaming::run_streaming("Rscript", &borrowed, None)
@@ -715,10 +755,25 @@ pub async fn compute(
     }
     let contents = std::fs::read_to_string(&result_path).map_err(|e| io_error(&result_path, e))?;
     let rows = parse_rows(&contents);
+    let permutation = if permutations.enabled().is_some() {
+        let perm_contents =
+            std::fs::read_to_string(&perm_path).map_err(|e| io_error(&perm_path, e))?;
+        let values = parse_permutations(&perm_contents);
+        if values.is_empty() {
+            return Err(Qtl2Error::CommandFailed(
+                "R/qtl2 ran the permutations but wrote no values".to_string(),
+            ));
+        }
+        Some(crate::rqtl::PermutationResult::from_values(values))
+    } else {
+        None
+    };
     Ok(Qtl2Output {
         markers: rows.len(),
         rows: Value::Array(rows),
         command,
+        permutation,
+        permutation_note,
         summary: String::from_utf8_lossy(&output.stdout)
             .lines()
             .filter(|line| !line.trim().is_empty())
@@ -729,6 +784,49 @@ pub async fn compute(
     })
 }
 
+/// What a caller asked for in the way of permutations.
+///
+/// `count == 0` means "none", and then nothing else is read -- so a request
+/// that leaves the whole thing out behaves exactly as before this existed.
+pub struct Permutations<'a> {
+    pub count: u32,
+    pub seed: u64,
+    /// (individual, stratum) pairs, empty when permutation is not stratified.
+    pub samples: &'a [(String, String)],
+    /// The case attribute the strata came from, for the note.
+    pub strata_name: &'a str,
+}
+
+impl Permutations<'_> {
+    fn enabled(&self) -> Option<&Self> {
+        if self.count == 0 {
+            None
+        } else {
+            Some(self)
+        }
+    }
+}
+
+/// Parse the script's permutation CSV: a `lod` header and one value per line.
+///
+/// Deliberately tolerant of a blank second column: R/qtl's own permutation
+/// file is `"","lod"`, and writing the same shape from both engines is the
+/// goal, so a two-column file reads the same way here.
+fn parse_permutations(contents: &str) -> Vec<f64> {
+    contents
+        .lines()
+        .skip(1)
+        .filter(|line| !line.trim().is_empty())
+        .filter_map(|line| {
+            let fields: Vec<&str> = line.split(',').map(str::trim).collect();
+            fields
+                .iter()
+                .rev()
+                .find_map(|field| field.trim_matches('"').trim().parse::<f64>().ok())
+        })
+        .collect()
+}
+
 /// Parse the script's `marker,chr,pos,lod` CSV into positional rows.
 fn parse_rows(contents: &str) -> Vec<Value> {
     contents
@@ -755,6 +853,31 @@ mod tests {
     use super::*;
 
     #[test]
+    fn permutation_csv_is_one_lod_per_line() {
+        // What scripts/qtl2_scan.R writes: a `lod` header, then the genome-wide
+        // maximum of each permutation. Quoted or not, and with or without a
+        // leading empty column (R/qtl's shape), the numbers are what matter.
+        let one_column = "lod\n1.3574\n1.3550\n2.1\n";
+        assert_eq!(parse_permutations(one_column), vec![1.3574, 1.3550, 2.1]);
+        let two_column = "\"\",lod\n\"1\",1.5\n\"2\",2.5\n";
+        assert_eq!(parse_permutations(two_column), vec![1.5, 2.5]);
+        assert!(parse_permutations("lod\n").is_empty());
+    }
+
+    #[test]
+    fn permutation_thresholds_are_percentiles_of_the_maxima() {
+        // 100 maxima from 0.01 to 1.00. The percentiles are linearly
+        // interpolated at position (n-1)*p/100 -- numpy's default and R's
+        // quantile type 7 -- so the 67th is between 0.67 and 0.68 (0.6733) and
+        // the 95th between 0.95 and 0.96 (0.9505), not the round values.
+        let values: Vec<f64> = (1..=100).map(|n| n as f64 / 100.0).collect();
+        let result = crate::rqtl::PermutationResult::from_values(values);
+        assert!((result.suggestive - 0.6733).abs() < 0.0001, "{}", result.suggestive);
+        assert!((result.significant - 0.9505).abs() < 0.0001, "{}", result.significant);
+        assert_eq!(result.values.len(), 100);
+    }
+
+    #[test]
     fn rows_are_positional_marker_chr_pos_lod() {
         let rows = parse_rows("marker,chr,pos,lod\nrs1,9,74.99,4.85\nrs2,X,3.0,0.5\n");
         assert_eq!(rows.len(), 2);
diff --git a/src/response.rs b/src/response.rs
index 556a0f8..5e6fcff 100644
--- a/src/response.rs
+++ b/src/response.rs
@@ -53,6 +53,13 @@ pub struct Meta {
     /// to count it itself.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub num_cols: Option<usize>,
+    /// Endpoint-specific additions, flattened into `meta` so the shape stays
+    /// `meta.<name>` and never a nested `meta.extra`. Used where something
+    /// belongs beside the rows rather than around them: `/compute/qtl2`'s
+    /// permutation null is qualifier information about the scan in `data`.
+    #[serde(flatten, skip_serializing_if = "Option::is_none")]
+    #[schema(inline)]
+    pub extra: Option<serde_json::Map<String, serde_json::Value>>,
 }
 
 /// A success response: the payload, facts about the response, notes on
@@ -170,6 +177,16 @@ impl<T: Serialize + utoipa::ToSchema> Envelope<T> {
         self
     }
 
+    /// Adds one `meta.<key>` entry, for endpoint-specific facts that qualify
+    /// `data` (see `Meta::extra`).
+    pub fn with_meta(mut self, key: &str, value: serde_json::Value) -> Self {
+        self.meta
+            .extra
+            .get_or_insert_with(serde_json::Map::new)
+            .insert(key.to_string(), value);
+        self
+    }
+
     /// Marks the response `partial` and records why in `notes`.
     pub fn partial(mut self, note: &str) -> Self {
         self.meta.state = State::Partial;
@@ -246,6 +263,7 @@ impl Ctx {
                 columns: None,
                 num_rows: None,
                 num_cols: None,
+                extra: None,
             },
             notes: Vec::new(),
             next: Vec::new(),
diff --git a/src/routes/qtl2.rs b/src/routes/qtl2.rs
index c8929ac..896c0e9 100644
--- a/src/routes/qtl2.rs
+++ b/src/routes/qtl2.rs
@@ -31,6 +31,25 @@ use crate::qtl2;
 use crate::response::{Ctx, Envelope, RequestInfo, path_segment};
 use crate::rqtl::Sample;
 
+/// Each permutation is a whole genome scan, so this is not a knob to leave
+/// open: 10 000 is already thousands of scans (about five minutes measured on
+/// a 34-individual panel, and far more on a multiparent cross).
+const MAX_PERMUTATIONS: u32 = 10_000;
+
+/// Below this the 0.05 threshold is a quantile of too few values to lean on.
+/// A note says so; the request is still answered.
+const FEW_PERMUTATIONS: u32 = 100;
+
+/// A permutation null without a seed is not reproducible, so one is chosen and
+/// reported when the caller does not supply it.
+fn default_perm_seed() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|elapsed| elapsed.as_secs())
+        .unwrap_or(0)
+}
+
+
 #[derive(Deserialize, utoipa::IntoParams)]
 pub struct ComputeQtl2Params {
     /// Log progress for `GET /compute/rqtl/status/{id}` (shared with
@@ -108,6 +127,26 @@ pub struct Qtl2Request {
     pub winsor_quantile: Option<f64>,
     /// Winsorise at Tukey fences, as on `/compute/rqtl`.
     pub winsor_fences: Option<f64>,
+
+    /// Genome-wide LOD thresholds from permutations: every permutation is
+    /// another whole scan of a shuffled phenotype, so the cost is this many
+    /// scans. 0 (default) skips them and reports no thresholds. Measured on a
+    /// 34-individual BXD panel over 20 chromosomes with a LOCO kinship: about
+    /// 0.03 s per permutation on four cores, i.e. 1000 in half a minute.
+    /// Fewer than ~100 makes the 0.05 quantile a coin toss, so that is
+    /// reported as a note rather than refused.
+    pub nperm: Option<u32>,
+
+    /// Seed for the permutations. A permutation null is random, so without one
+    /// two identical requests give different thresholds; the seed used is
+    /// reported in `notes` either way. Ignored when `nperm` is 0.
+    pub perm_seed: Option<u64>,
+
+    /// Permute within strata instead of across all individuals: a case
+    /// attribute of the group by name (e.g. `sex`). Permuting across sexes
+    /// inflates the null, so a mixed-sex panel wants this. Ignored when
+    /// `nperm` is 0.
+    pub perm_strata: Option<String>,
 }
 
 #[utoipa::path(post, path = "/compute/qtl2",
@@ -507,6 +546,129 @@ pub async fn compute_qtl2(
     .await?;
     notes.extend(covariate_notes);
 
+    // ---- permutations: how many, which seed, and permute within what -----
+    let permutations = request.nperm.unwrap_or(0);
+    if permutations > MAX_PERMUTATIONS {
+        return Err(ApiError::new(
+            StatusCode::UNPROCESSABLE_ENTITY,
+            "too_many_permutations",
+            "Too many permutations",
+            format!(
+                "{} permutations is more than the {} allowed: each one is a whole genome \
+                 scan, so this is already thousands of scans.",
+                permutations, MAX_PERMUTATIONS
+            ),
+            "compute_qtl2",
+        )
+        .with_request_id(rid.clone()));
+    }
+    let perm_seed = request.perm_seed.unwrap_or_else(default_perm_seed);
+    let mut strata_pairs: Vec<(String, String)> = Vec::new();
+    let mut strata_name = String::new();
+    if permutations > 0 {
+        if permutations < FEW_PERMUTATIONS {
+            notes.push(format!(
+                "{permutations} permutations is few: the 0.05 threshold is a quantile of only                  {permutations} values, so treat it as indicative. 1000 is the usual number."
+            ));
+        }
+        if let Some(attribute) = request.perm_strata.as_deref() {
+            let group = request_group.as_deref().ok_or_else(|| {
+                ApiError::new(
+                    StatusCode::UNPROCESSABLE_ENTITY,
+                    "missing_group",
+                    "No group for permutation strata",
+                    "`perm_strata` names a case attribute of the group, so `group` is required."
+                        .to_string(),
+                    "compute_qtl2",
+                )
+                .with_request_id(rid.clone())
+            })?;
+            let group_owned = group.to_string();
+            let attribute_owned = attribute.to_string();
+            let (mut values, available) = tokio::task::spawn_blocking(move || {
+                let found = crate::db::get_group_by_name(&group_owned)?;
+                let Some(found) = found else {
+                    return Ok::<(std::collections::HashMap<String, String>, Vec<String>),
+                              crate::db::DbError>(
+                        (std::collections::HashMap::new(), Vec::new()),
+                    );
+                };
+                let attributes = crate::db::get_group_case_attributes(found.id)?;
+                let names = attributes.names.clone();
+                let mut by_strain = std::collections::HashMap::new();
+                for entry in attributes.values {
+                    if let Some(value) = entry.case_attributes.get(&attribute_owned) {
+                        // An empty cell is not a stratum, it is a missing value.
+                        if !value.trim().is_empty() {
+                            by_strain.insert(entry.strain, value.trim().to_string());
+                        }
+                    }
+                }
+                Ok((by_strain, names))
+            })
+            .await
+            .map_err(|error| {
+                ApiError::new(
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    "db_failure",
+                    "Database failure",
+                    format!("could not read the group's case attributes: {error}"),
+                    "compute_qtl2",
+                )
+                .with_request_id(rid.clone())
+            })?
+            .map_err(|error| {
+                ApiError::new(
+                    StatusCode::BAD_GATEWAY,
+                    "db_failure",
+                    "Database failure",
+                    error.to_string(),
+                    "compute_qtl2",
+                )
+                .with_request_id(rid.clone())
+            })?;
+            // Only individuals with a value are scanned, so only they need a
+            // stratum: counting the whole sample list made the note claim
+            // "195 of 198" for a request whose scan used 34.
+            let phenotyped: Vec<&Sample> =
+                samples.iter().filter(|sample| sample.value.is_some()).collect();
+            for sample in &phenotyped {
+                if let Some(stratum) = values.remove(&sample.name) {
+                    strata_pairs.push((sample.name.clone(), stratum));
+                }
+            }
+            if strata_pairs.is_empty() {
+                return Err(ApiError::new(
+                    StatusCode::UNPROCESSABLE_ENTITY,
+                    "invalid_perm_strata",
+                    "Invalid permutation strata",
+                    format!(
+                        "no individual in this request has a value for case attribute '{}'. \
+                         The group's attributes are: {}.",
+                        attribute,
+                        if available.is_empty() {
+                            "none".to_string()
+                        } else {
+                            available.join(", ")
+                        }
+                    ),
+                    "compute_qtl2",
+                )
+                .with_request_id(rid.clone()));
+            }
+            strata_name = attribute.to_string();
+            notes.push(format!(
+                "permutations are stratified by '{}': {} of {} individuals have a value, and an \
+                 individual without one is permuted with the rest.",
+                attribute,
+                strata_pairs.len(),
+                samples.len()
+            ));
+        }
+    }
+    let strata_pairs_for_job = strata_pairs.clone();
+    let strata_name_for_job = strata_name.clone();
+
     // The cross: converted from the .geno once, then cached.
     let cache_dir = config.qtl2_cache_dir.clone();
     let source_for_cross = source.clone();
@@ -700,6 +862,12 @@ pub async fn compute_qtl2(
                 &kinship,
                 &model,
                 cores,
+                qtl2::Permutations {
+                    count: permutations,
+                    seed: perm_seed,
+                    samples: &strata_pairs_for_job,
+                    strata_name: &strata_name_for_job,
+                },
             )
             .await
             .map_err(|e| {
@@ -734,6 +902,33 @@ pub async fn compute_qtl2(
              mitochondrion degenerate the per-chromosome kinship."
         ))
         .with_note(&output.command);
+    if let Some(permutation) = &output.permutation {
+        envelope = envelope.with_meta(
+            "permutation",
+            serde_json::json!({
+                "n": permutation.values.len(),
+                "seed": perm_seed,
+                "significant": permutation.significant,
+                "suggestive": permutation.suggestive,
+                "values": permutation.values,
+            }),
+        );
+        envelope = envelope.with_note(&format!(
+            "Permutation thresholds: significant (0.05) LOD {:.3}, suggestive (0.37) LOD {:.3},              from {} genome-wide maxima. `permutation` carries every maximum, so a histogram can              be drawn from this response alone.",
+            permutation.significant,
+            permutation.suggestive,
+            permutation.values.len()
+        ));
+        envelope = envelope.with_note(
+            "The permutations are qtl2's scan1perm: phenotypes are shuffled across individuals, \
+             which is the right null for an outbred cross and only approximate for a selfing RIL \
+             panel. `perm_strata` restricts the shuffle to one stratum (e.g. sex); the seed is \
+             reported so the run can be repeated.",
+        );
+    }
+    if let Some(note) = &output.permutation_note {
+        envelope = envelope.with_note(&format!("permutations: {note}"));
+    }
     if !output.summary.trim().is_empty() {
         envelope = envelope.with_note(&format!("qtl2: {}", output.summary.trim()));
     }
diff --git a/src/rqtl.rs b/src/rqtl.rs
index 3b77428..2bf6de3 100644
--- a/src/rqtl.rs
+++ b/src/rqtl.rs
@@ -272,10 +272,44 @@ fn parse_mapping_output(contents: &str) -> Vec<MarkerResult> {
 #[derive(Debug, Serialize, utoipa::ToSchema, PartialEq)]
 pub struct PermutationResult {
     pub values: Vec<f64>,
+    /// The 67th percentile: R/qtl's "suggestive" LOD.
     pub suggestive: f64,
+    /// The 95th percentile: the genome-wide alpha = 0.05 threshold.
     pub significant: f64,
 }
 
+impl PermutationResult {
+    /// Thresholds from a permutation null. Shared with `/compute/qtl2`, which
+    /// permutes with qtl2's own `scan1perm`: the null is the genome-wide LOD
+    /// maximum per permutation, so the percentiles mean the same thing
+    /// whichever engine produced them.
+    pub fn from_values(mut values: Vec<f64>) -> Self {
+        values.retain(|value| value.is_finite());
+        let mut sorted = values.clone();
+        sorted.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));
+        Self {
+            suggestive: percentile(&sorted, 67.0),
+            significant: percentile(&sorted, 95.0),
+            values,
+        }
+    }
+}
+
+/// Write (individual, stratum) pairs as the two-column file `--strata` reads:
+/// `Sample<TAB>stratum`. Written the way the scripts expect rather than by
+/// reusing the covariate writer, which emits one column per covariate.
+pub fn write_strata_file(path: &std::path::Path, samples: &[(String, String)]) -> std::io::Result<()> {
+    use std::io::Write;
+    let mut out = String::from("Sample\tstratum\n");
+    for (individual, stratum) in samples {
+        out.push_str(individual);
+        out.push('\t');
+        out.push_str(stratum);
+        out.push('\n');
+    }
+    std::fs::write(path, out)
+}
+
 /// Parse R/qtl's permutation output CSV: `"","lod"` header, then
 /// `"1",value` rows. Confirmed by actually running
 /// `scripts/rqtl_wrapper.R --nperm 50` against the BXD riset fixture.