diff options
| author | Pjotr <wrk@bosa.lan> | 2026-11-16 00:30:42 +0000 |
|---|---|---|
| committer | Pjotr <wrk@bosa.lan> | 2026-11-16 00:30:42 +0000 |
| commit | 1ae2f5d712e18c016fdb7bd04da99eab4da6915b (patch) | |
| tree | 31bb20e52585506351d81198b65c13ec3a229af0 /src | |
| parent | 9c3cd6f2300bb290ddd05c5a46c5b813b22c0ce1 (diff) | |
| download | genenetwork4-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.rs | 123 | ||||
| -rw-r--r-- | src/response.rs | 18 | ||||
| -rw-r--r-- | src/routes/qtl2.rs | 195 | ||||
| -rw-r--r-- | src/rqtl.rs | 34 |
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. |
