about summary refs log tree commit diff
path: root/src
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-12 14:45:16 +0000
committerPjotr <wrk@bosa.lan>2026-11-12 14:45:16 +0000
commitd507d3220910f528d95932f7772f80a902ec6fe9 (patch)
treebed56d83e8d621b6e9d88aa0a685297bf73fd6d8 /src
parent60420b6e076ea16109d54789cfcd89262a01ae57 (diff)
downloadgenenetwork4-d507d3220910f528d95932f7772f80a902ec6fe9.tar.gz
gemma/ravanan: resolve the same inputs as the direct runner; refuse what it cannot do
Two gaps, both invisible until a real request ran against a cluster.

The endpoint read only genotype_file, snps_file and trait_values from the
request; group, genotype_version and samples were accepted by the shared
request type and silently dropped. A /compute/gemma-shaped request
(group + samples) therefore arrived as empty paths and empty values and
died with "I/O error: No such file or directory (os error 2)" from
reading "". Running it exposed the second gap in the same breath: the
gate sized the request from trait_values.len(), so a samples-only request
was sized 0 and took no concurrency slot at all.

resolve_inputs is now one function in routes/gemma.rs, called by both
handlers: upload materialised into the pair the engine reads, basket
resolved to named values, group prepared with the parent/F1 and
empty-genotype rules, named samples aligned by name onto whatever
individuals the file has, positional values checked against the panel
size. That block was ~250 lines of duplicated rules inside compute_gemma,
which is how it drifted in the first place; the direct runner now calls
the same function and keeps only its covariates, normalization and gate.

The ravanan reply also carries the input notes now (which genotype
version, how many values aligned, what was dropped), so a run says what it
mapped as well as where the peak is.

Refused rather than ignored, because the CWL workflow has no step for
either: covariates (422 covariates_not_supported) and normalize (422
normalization_not_supported), each naming /compute/gemma as the endpoint
that can do it. A new test asserts both refusals happen before any job is
submitted, so it needs no ravanan, ccwl or cluster.

Verified against the Slurm container from gn-machines: group: BXD became
40 Slurm jobs (20 kinship + 20 GWA, scattered over the snps file's
chromosomes), all completed, 21 055 rows in ~3.5 min. README and
docs/ravanan-slurm.md record the four requirements that run turned up,
three of them not obvious: ccwl on PATH, a ravanan build with the
--slurm-api-endpoint fix, the *server's* HOME writable by the job user
inside the cluster (gemma-wrapper locks $HOME/.<hash>.lck there), and
GUIX_PACKAGE_PATH for the manifest.
Diffstat (limited to 'src')
-rw-r--r--src/routes/gemma.rs721
1 files changed, 408 insertions, 313 deletions
diff --git a/src/routes/gemma.rs b/src/routes/gemma.rs
index 2211c35..d774336 100644
--- a/src/routes/gemma.rs
+++ b/src/routes/gemma.rs
@@ -122,31 +122,48 @@ pub struct GemmaSample {
     pub value: Option<f64>,
 }
 
-#[utoipa::path(post, path = "/compute/gemma",
-    summary = "Map a QTL from a genotype file and trait values using GEMMA",
-    description = "Runs gemma-wrapper's K-matrix step, then its LMM \
-association step, over the given genotype and SNP annotation files and \
-trait values, and returns the resulting rows of GEMMA's own \
-.assoc.txt output. Pass ?id= to log progress for GET \
-/compute/gemma/status/{id} to poll concurrently.",
-    params(ComputeGemmaParams),
-    request_body = GemmaRequest,
-    responses(
-        (status = 200, description = "Mapped QTL rows from GEMMA's .assoc.txt output, as positional arrays (column names in meta.columns)", body = Envelope<serde_json::Value>),
-        Unauthorized,
-        (status = 409, description = "id is already in use by another run", body = ApiError),
-        (status = 422, description = "lmm not one of the known-working values (1, 2, 3, 4, 9), or id not alnum/-/_ (max 64 chars)", body = ApiError),
-        (status = 502, description = "gemma-wrapper or GEMMA failed", body = ApiError)
-    ))]
-#[gnauth(token_only)]
-#[compute_gate(gemma, run_id = params.id.as_deref())]
-pub async fn compute_gemma(
-    ctx: Ctx,
-    token: AuthToken,
-    Query(params): Query<ComputeGemmaParams>,
-    Json(mut request): Json<GemmaRequest>,
-) -> Result<Json<Envelope<serde_json::Value>>, ApiError> {
-    let rid = ctx.request_info();
+
+/// What a mapping request resolves to before any engine runs: the genotype
+/// file the engine reads, the SNP map beside it, the trait values in that
+/// file's individual order, how many individuals that is, and the notes
+/// describing what was aligned, dropped or refused along the way.
+///
+/// Both GEMMA runners -- the direct one and the ravanan one -- go through
+/// this, because the rules are fiddly and had drifted once already: an
+/// upload is materialised into the pair the engine reads, a group is
+/// prepared with the parent/F1 and empty-genotype rules applied, named
+/// samples are aligned by name onto whatever individuals the file has, and
+/// positional `trait_values` are checked against the panel size. Writing
+/// them twice means fixing them twice.
+pub(crate) struct ResolvedInputs {
+    pub genotype_file: String,
+    pub snps_file: String,
+    pub trait_values: Vec<Option<f64>>,
+    /// Individuals the fit will see: the gate's size for this request.
+    pub individuals: usize,
+    /// Their names, in the same order, for a group-scoped request -- the
+    /// only kind whose individuals are named (covariates align against
+    /// these).
+    pub names: Option<Vec<String>>,
+    pub group: String,
+    pub notes: Vec<String>,
+}
+
+/// Resolve a request's genotype input and trait values.
+///
+/// `endpoint` names this endpoint in errors ("compute_gemma" or
+/// "compute_gemma_ravanan"), so a caller is never told about the other one.
+pub(crate) async fn resolve_inputs(
+    config: &Config,
+    request: &mut GemmaRequest,
+    token: &AuthToken,
+    endpoint: &'static str,
+    rid: RequestInfo,
+) -> Result<ResolvedInputs, ApiError> {
+    let mut notes: Vec<String> = Vec::new();
+    let mut aligned_names: Option<Vec<String>> = None;
+    let mut aligned_group = String::new();
+
     if let Some(upload) = request.genotype_upload.clone() {
         if request.genotype_file.is_some() || request.group.is_some() {
             return Err(ApiError::new(
@@ -154,26 +171,24 @@ pub async fn compute_gemma(
                 "ambiguous_genotype",
                 "Ambiguous genotype input",
                 "give genotype_upload, genotype_file or group -- one of the three.".to_string(),
-                "compute_gemma",
+                endpoint,
             )
             .with_request_id(rid));
         }
         // GEMMA reads BIMBAM, not `.geno`, so the upload is written out as
         // the pair (`-g`/`-a`) that the deployment's own GTEx/BXD runs use.
         let upload_for_values = upload.clone();
+        let upload_for_note = upload.clone();
         let (geno, snps) = crate::routes::genoupload::resolve_upload(
             token.sub.clone(),
-            Config::load().basket_dir,
-            Config::load().genotype_files_dir,
+            config.basket_dir.clone(),
+            config.genotype_files_dir.clone(),
             upload,
-            "compute_gemma",
+            endpoint,
             rid.clone(),
             true,
         )
         .await?;
-        // GEMMA reads BIMBAM, which has no individual names, so the values are
-        // ordered here -- by the upload's own individual list -- rather than
-        // aligned later against a file that cannot answer.
         let named: Vec<(String, Option<f64>)> = request
             .samples
             .as_ref()
@@ -184,13 +199,13 @@ pub async fn compute_gemma(
                     .collect()
             })
             .unwrap_or_default();
-        if request.trait_values.is_none() && !named.is_empty() {
-            let config = Config::load();
-            let individuals = tokio::task::spawn_blocking({
-                let dir = config.basket_dir.clone();
-                let owner = token.sub.clone();
-                let wanted = upload_for_values.clone();
-                move || crate::genoupload::individuals(std::path::Path::new(&dir), &owner, &wanted)
+        let trait_values = if let Some(values) = request.trait_values.clone() {
+            values
+        } else {
+            let dir = config.basket_dir.clone();
+            let owner = token.sub.clone();
+            let individuals = tokio::task::spawn_blocking(move || {
+                crate::genoupload::individuals(std::path::Path::new(&dir), &owner, &upload_for_values)
             })
             .await
             .map_err(|error| {
@@ -199,7 +214,7 @@ pub async fn compute_gemma(
                     "internal_error",
                     "Internal error",
                     error.to_string(),
-                    "compute_gemma",
+                    endpoint,
                 )
                 .with_request_id(rid.clone())
             })?
@@ -209,7 +224,7 @@ pub async fn compute_gemma(
                     "invalid_genotype_upload",
                     "Invalid genotype upload",
                     error.to_string(),
-                    "compute_gemma",
+                    endpoint,
                 )
                 .with_request_id(rid.clone())
             })?;
@@ -217,32 +232,42 @@ pub async fn compute_gemma(
                 .iter()
                 .map(|(name, value)| (name.as_str(), *value))
                 .collect();
-            request.trait_values = Some(
-                individuals
-                    .iter()
-                    .map(|name| by_name.get(name.as_str()).copied().flatten())
-                    .collect(),
-            );
-        }
-        request.genotype_file = Some(geno);
-        request.snps_file = snps;
+            individuals
+                .iter()
+                .map(|name| by_name.get(name.as_str()).copied().flatten())
+                .collect()
+        };
+        notes.push(format!(
+            "Genotype: uploaded pick '{}' written out as a BIMBAM pair; {} values used.",
+            upload_for_note,
+            trait_values.iter().filter(|value| value.is_some()).count()
+        ));
+        return Ok(ResolvedInputs {
+            genotype_file: geno,
+            snps_file: snps.unwrap_or_default(),
+            individuals: trait_values.len(),
+            trait_values,
+            names: None,
+            group: String::new(),
+            notes,
+        });
     }
+
     // A basket is another source for the caller's values, resolved before
     // anything below looks at them (see crate::routes::baskets).
-    let mut basket_note: Option<String> = None;
     if let Some(name) = request.basket.clone() {
         if request.samples.is_some() {
-            return Err(crate::routes::baskets::ambiguous("compute_gemma", rid));
+            return Err(crate::routes::baskets::ambiguous(endpoint, rid));
         }
         let (resolved, note) = crate::routes::baskets::resolve_for_mapping(
             token.sub.clone(),
-            Config::load().basket_dir,
+            config.basket_dir.clone(),
             name,
-            "compute_gemma",
+            endpoint,
             rid.clone(),
         )
         .await?;
-        basket_note = Some(note);
+        notes.push(note);
         request.samples = Some(
             resolved
                 .values
@@ -255,6 +280,254 @@ pub async fn compute_gemma(
         );
     }
 
+    let group = request.group.clone();
+    let version = request.genotype_version.clone();
+    let include_parents_f1 = request.include_parents_f1.unwrap_or(false);
+    let named: Vec<(String, Option<f64>)> = request
+        .samples
+        .as_ref()
+        .map(|samples| {
+            samples
+                .iter()
+                .map(|sample| (sample.name.clone(), sample.value))
+                .collect()
+        })
+        .unwrap_or_default();
+    let supplied_values = request.trait_values.clone();
+
+    match (request.genotype_file.clone(), request.snps_file.clone(), group) {
+        (Some(genotype_file), Some(snps_file), None) => {
+            let trait_values = if let Some(values) = supplied_values {
+                values
+            } else if named.is_empty() {
+                return Err(ApiError::new(
+                    StatusCode::UNPROCESSABLE_ENTITY,
+                    "missing_trait_values",
+                    "No trait values",
+                    "give trait_values (one per individual, genotype-file order) or \
+                     samples (named)."
+                        .to_string(),
+                    endpoint,
+                )
+                .with_request_id(rid));
+            } else {
+                let path = std::path::PathBuf::from(&genotype_file);
+                let aligned = tokio::task::spawn_blocking(move || {
+                    genotypes::align_to_file(&path, &named)
+                })
+                .await
+                .map_err(|error| {
+                    ApiError::new(
+                        StatusCode::INTERNAL_SERVER_ERROR,
+                        "internal_error",
+                        "Internal error",
+                        error.to_string(),
+                        endpoint,
+                    )
+                    .with_request_id(rid.clone())
+                })?
+                .map_err(|error| genotype_error_to_api_error(error, endpoint, rid.clone()))?;
+                aligned
+            };
+            notes.push(format!(
+                "Genotype: given file and SNP map; {} values used.",
+                trait_values.iter().filter(|value| value.is_some()).count()
+            ));
+            Ok(ResolvedInputs {
+                individuals: trait_values.len(),
+                trait_values,
+                genotype_file,
+                snps_file,
+                names: None,
+                group: String::new(),
+                notes,
+            })
+        }
+        (None, None, Some(group)) => {
+            let directory = std::path::PathBuf::from(&config.genotype_files_dir);
+            let cache_dir = std::path::PathBuf::from(&config.gemma_cache_dir);
+            let wanted = group.clone();
+            let had_samples = !named.is_empty();
+            let supplied_count = named.len();
+            let (prepared, aligned, matched, resolved, kept_names, dropped_empty, parents_f1s) =
+                tokio::task::spawn_blocking(move || {
+                    let resolved = genotypes::resolve(&directory, &wanted, version.as_deref())?;
+                    let excluded = if include_parents_f1 {
+                        std::collections::BTreeSet::new()
+                    } else {
+                        genotypes::non_strains(&directory, &wanted, &resolved.panel)
+                    };
+                    let keep: Vec<usize> = resolved
+                        .panel
+                        .iter()
+                        .enumerate()
+                        .filter(|(_, name)| !excluded.contains(*name))
+                        .map(|(index, _)| index)
+                        .collect();
+                    // An individual with no genotypes at all makes the
+                    // kinship singular, so leave those out before anything
+                    // else is aligned: they contribute nothing to the fit.
+                    let empty = resolved
+                        .bimbam_geno
+                        .as_deref()
+                        .and_then(genotypes::individuals_with_genotypes);
+                    let parents_f1s = resolved.panel.len() - keep.len();
+                    let keep: Vec<usize> = match empty {
+                        Some(mask) => keep
+                            .into_iter()
+                            .filter(|index| mask.get(*index).copied().unwrap_or(true))
+                            .collect(),
+                        None => keep,
+                    };
+                    let dropped_empty = (resolved.panel.len() - parents_f1s) - keep.len();
+                    let (aligned, matched) = genotypes::align(&resolved.panel, &keep, &named);
+                    let kept_names: Vec<String> = keep
+                        .iter()
+                        .filter_map(|index| resolved.panel.get(*index).cloned())
+                        .collect();
+                    let prepared = genotypes::prepare(
+                        &directory,
+                        &resolved,
+                        genotypes::Engine::Gemma,
+                        &keep,
+                        &cache_dir,
+                    )?;
+                    Ok::<_, genotypes::GenotypeError>((
+                        prepared,
+                        aligned,
+                        matched,
+                        resolved,
+                        kept_names,
+                        dropped_empty,
+                        parents_f1s,
+                    ))
+                })
+                .await
+                .map_err(|e| {
+                    ApiError::new(
+                        StatusCode::INTERNAL_SERVER_ERROR,
+                        "internal_error",
+                        "Internal error",
+                        e.to_string(),
+                        endpoint,
+                    )
+                    .with_request_id(rid.clone())
+                })?
+                .map_err(|e| genotype_error_to_api_error(e, endpoint, rid.clone()))?;
+            let individuals = prepared.individuals;
+            let trait_values = if had_samples {
+                if matched == 0 {
+                    return Err(ApiError::new(
+                        StatusCode::UNPROCESSABLE_ENTITY,
+                        "no_samples_aligned",
+                        "No samples aligned",
+                        format!(
+                            "none of the {supplied_count} named samples appear in genotype \
+                             version '{}'.",
+                            resolved.version
+                        ),
+                        endpoint,
+                    )
+                    .with_request_id(rid));
+                }
+                aligned
+            } else {
+                let Some(supplied) = supplied_values else {
+                    return Err(ApiError::new(
+                        StatusCode::UNPROCESSABLE_ENTITY,
+                        "missing_trait_values",
+                        "No trait values",
+                        "give samples (named) or trait_values (one per individual).".to_string(),
+                        endpoint,
+                    )
+                    .with_request_id(rid));
+                };
+                if supplied.len() != individuals {
+                    return Err(ApiError::new(
+                        StatusCode::UNPROCESSABLE_ENTITY,
+                        "trait_values_length",
+                        "Trait values do not match the panel",
+                        format!(
+                            "genotype version '{}' has {} individuals after the parent/F1 rule; \
+                             got {} trait_values.",
+                            resolved.version,
+                            individuals,
+                            supplied.len()
+                        ),
+                        endpoint,
+                    )
+                    .with_request_id(rid));
+                }
+                supplied
+            };
+            let empty_clause = if dropped_empty > 0 {
+                format!(
+                    ", {dropped_empty} left out with no genotypes at all (an empty kinship row \
+                     makes the matrix singular)"
+                )
+            } else {
+                String::new()
+            };
+            notes.push(format!(
+                "Genotype: {} (version {}, {} individuals, {} parents/F1s dropped{empty_clause}); \
+                 {} values used.",
+                prepared.note,
+                resolved.version,
+                individuals,
+                parents_f1s,
+                trait_values.iter().filter(|value| value.is_some()).count()
+            ));
+            aligned_names = Some(kept_names);
+            aligned_group = group.clone();
+            Ok(ResolvedInputs {
+                genotype_file: prepared.genotype_file.to_string_lossy().into_owned(),
+                snps_file: prepared
+                    .snps_file
+                    .map(|p| p.to_string_lossy().into_owned())
+                    .unwrap_or_default(),
+                individuals,
+                trait_values,
+                names: aligned_names,
+                group: aligned_group,
+                notes,
+            })
+        }
+        _ => Err(ApiError::new(
+            StatusCode::UNPROCESSABLE_ENTITY,
+            "ambiguous_genotype",
+            "Ambiguous genotype input",
+            "give genotype_file + snps_file, or group (see /groups/{group}/genotypes).".to_string(),
+            endpoint,
+        )
+        .with_request_id(rid)),
+    }
+}
+
+#[utoipa::path(post, path = "/compute/gemma",
+    summary = "Map a QTL from a genotype file and trait values using GEMMA",
+    description = "Runs gemma-wrapper's K-matrix step, then its LMM \
+association step, over the given genotype and SNP annotation files and \
+trait values, and returns the resulting rows of GEMMA's own \
+.assoc.txt output. Pass ?id= to log progress for GET \
+/compute/gemma/status/{id} to poll concurrently.",
+    params(ComputeGemmaParams),
+    request_body = GemmaRequest,
+    responses(
+        (status = 200, description = "Mapped QTL rows from GEMMA's .assoc.txt output, as positional arrays (column names in meta.columns)", body = Envelope<serde_json::Value>),
+        Unauthorized,
+        (status = 409, description = "id is already in use by another run", body = ApiError),
+        (status = 422, description = "lmm not one of the known-working values (1, 2, 3, 4, 9), or id not alnum/-/_ (max 64 chars)", body = ApiError),
+        (status = 502, description = "gemma-wrapper or GEMMA failed", body = ApiError)
+    ))]
+#[gnauth(token_only)]
+#[compute_gate(gemma, run_id = params.id.as_deref())]
+pub async fn compute_gemma(
+    ctx: Ctx,
+    token: AuthToken,
+    Query(params): Query<ComputeGemmaParams>,
+    Json(mut request): Json<GemmaRequest>,
+) -> Result<Json<Envelope<serde_json::Value>>, ApiError> {
+    let rid = ctx.request_info();
     let lmm = request.lmm.unwrap_or(9);
     // Only the values actually run against this GEMMA build (see the
     // `lmm` field doc above) are allowed; 5-8 are stock-invalid and
@@ -363,252 +636,17 @@ pub async fn compute_gemma(
     let mut covariate_notes: Vec<String> = Vec::new();
     let mut aligned_names: Option<Vec<String>> = None;
     let mut aligned_group = String::new();
-    let (genotype_file, snps_file, trait_values): (String, String, Vec<Option<f64>>) =
-        match (
-            request.genotype_file.clone(),
-            request.snps_file.clone(),
-            request.group.clone(),
-        ) {
-            (Some(genotype_file), Some(snps_file), None) => {
-                // GEMMA needs one phenotype row per genotype column, so values
-                // given by name are aligned onto the file's own individuals
-                // (and the rest become NA, which GEMMA drops) -- the same rule
-                // the group path follows. Positional `trait_values` are taken
-                // as they come.
-                let named: Vec<(String, Option<f64>)> = request
-                    .samples
-                    .as_ref()
-                    .map(|samples| {
-                        samples
-                            .iter()
-                            .map(|sample| (sample.name.clone(), sample.value))
-                            .collect()
-                    })
-                    .unwrap_or_default();
-                let trait_values = if let Some(values) = request.trait_values.clone() {
-                    Some(values)
-                } else if named.is_empty() {
-                    None
-                } else {
-                    let path = std::path::PathBuf::from(&genotype_file);
-                    let aligned = tokio::task::spawn_blocking(move || {
-                        genotypes::align_to_file(&path, &named)
-                    })
-                    .await
-                    .map_err(|error| {
-                        ApiError::new(
-                            StatusCode::INTERNAL_SERVER_ERROR,
-                            "internal_error",
-                            "Internal error",
-                            error.to_string(),
-                            "compute_gemma",
-                        )
-                        .with_request_id(rid.clone())
-                    })?
-                    .map_err(|error| {
-                        genotype_error_to_api_error(error, "compute_gemma", rid.clone())
-                    })?;
-                    Some(aligned)
-                };
-                let Some(trait_values) = trait_values else {
-                    return Err(ApiError::new(
-                        StatusCode::UNPROCESSABLE_ENTITY,
-                        "missing_trait_values",
-                        "No trait values",
-                        "give trait_values (one per individual, genotype-file order) or \
-                         samples (named)."
-                            .to_string(),
-                        "compute_gemma",
-                    )
-                    .with_request_id(rid));
-                };
-                (genotype_file, snps_file, trait_values)
-            }
-            (None, None, Some(group)) => {
-                let directory = std::path::PathBuf::from(&config.genotype_files_dir);
-                let cache_dir = std::path::PathBuf::from(&config.gemma_cache_dir);
-                let version = request.genotype_version.clone();
-                let include_parents_f1 = request.include_parents_f1.unwrap_or(false);
-                let supplied_count = request.samples.as_ref().map(Vec::len).unwrap_or(0);
-                let values: Vec<(String, Option<f64>)> = request
-                    .samples
-                    .as_ref()
-                    .map(|samples| {
-                        samples
-                            .iter()
-                            .map(|sample| (sample.name.clone(), sample.value))
-                            .collect()
-                    })
-                    .unwrap_or_default();
-                let wanted = group.clone();
-                let had_samples = request.samples.is_some();
-                let supplied_values = request.trait_values.clone();
-                let (
-                    prepared,
-                    aligned,
-                    matched,
-                    resolved,
-                    kept_names,
-                    dropped_empty,
-                    parents_f1s,
-                ) =
-                    tokio::task::spawn_blocking(move || {
-                        let resolved = genotypes::resolve(&directory, &wanted, version.as_deref())?;
-                        let excluded = if include_parents_f1 {
-                            std::collections::BTreeSet::new()
-                        } else {
-                            genotypes::non_strains(&directory, &wanted, &resolved.panel)
-                        };
-                        let keep: Vec<usize> = resolved
-                            .panel
-                            .iter()
-                            .enumerate()
-                            .filter(|(_, name)| !excluded.contains(*name))
-                            .map(|(index, _)| index)
-                            .collect();
-                        // An individual with no genotypes at all makes the
-                        // kinship singular (see genotypes::individuals_with_genotypes),
-                        // so leave those out before anything else is aligned:
-                        // they contribute nothing to the fit either.
-                        let empty = resolved
-                            .bimbam_geno
-                            .as_deref()
-                            .and_then(genotypes::individuals_with_genotypes);
-                        // Count what was dropped from the panel itself, not
-                        // from the exclusion *set*: `non_strains` can name
-                        // parents/F1s that are not in this panel at all, and
-                        // subtracting that length underflowed (a 500 with
-                        // "attempt to subtract with overflow").
-                        let parents_f1s = resolved.panel.len() - keep.len();
-                        let keep: Vec<usize> = match empty {
-                            Some(mask) => keep
-                                .into_iter()
-                                .filter(|index| mask.get(*index).copied().unwrap_or(true))
-                                .collect(),
-                            None => keep,
-                        };
-                        let dropped_empty = (resolved.panel.len() - parents_f1s) - keep.len();
-                        let (aligned, matched) = genotypes::align(&resolved.panel, &keep, &values);
-                        let kept_names: Vec<String> = keep
-                            .iter()
-                            .filter_map(|index| resolved.panel.get(*index).cloned())
-                            .collect();
-                        let prepared = genotypes::prepare(
-                            &directory,
-                            &resolved,
-                            genotypes::Engine::Gemma,
-                            &keep,
-                            &cache_dir,
-                        )?;
-                        Ok::<_, genotypes::GenotypeError>((
-                            prepared,
-                            aligned,
-                            matched,
-                            resolved,
-                            kept_names,
-                            dropped_empty,
-                            parents_f1s,
-                        ))
-                    })
-                    .await
-                    .map_err(|e| {
-                        ApiError::new(
-                            StatusCode::INTERNAL_SERVER_ERROR,
-                            "internal_error",
-                            "Internal error",
-                            e.to_string(),
-                            "compute_gemma",
-                        )
-                        .with_request_id(rid.clone())
-                    })?
-                    .map_err(|e| {
-                        genotype_error_to_api_error(e, "compute_gemma", rid.clone())
-                    })?;
-                let individuals = prepared.individuals;
-                // Kept for the covariate resolve below: it has to run after
-                // the trait values exist (see there).
-                aligned_names = Some(kept_names);
-                aligned_group = group.clone();
-                let trait_values = if had_samples {
-                    if matched == 0 {
-                        return Err(ApiError::new(
-                            StatusCode::UNPROCESSABLE_ENTITY,
-                            "no_samples_aligned",
-                            "No samples aligned",
-                            format!(
-                                "none of the {} named samples appear in genotype version '{}'.",
-                                supplied_count,
-                                resolved.version
-                            ),
-                            "compute_gemma",
-                        )
-                        .with_request_id(rid));
-                    }
-                    aligned
-                } else {
-                    let Some(supplied) = supplied_values else {
-                        return Err(ApiError::new(
-                            StatusCode::UNPROCESSABLE_ENTITY,
-                            "missing_trait_values",
-                            "No trait values",
-                            "give samples (named) or trait_values (one per individual)."
-                                .to_string(),
-                            "compute_gemma",
-                        )
-                        .with_request_id(rid));
-                    };
-                    if supplied.len() != individuals {
-                        return Err(ApiError::new(
-                            StatusCode::UNPROCESSABLE_ENTITY,
-                            "trait_values_length",
-                            "Trait values do not match the panel",
-                            format!(
-                                "genotype version '{}' has {} individuals after the parent/F1 \
-                                 rule; got {} trait_values.",
-                                resolved.version,
-                                individuals,
-                                supplied.len()
-                            ),
-                            "compute_gemma",
-                        )
-                        .with_request_id(rid));
-                    }
-                    supplied
-                };
-                // `prepared.excluded` is "panel minus kept", which now also
-                // counts the genotype-less individuals; keep the two apart so
-                // the note never blames parents/F1s for a missing-genotype
-                // panel.
-                let empty_clause = if dropped_empty > 0 {
-                    format!(
-                        ", {dropped_empty} left out with no genotypes at all (an empty kinship                          row makes the matrix singular)"
-                    )
-                } else {
-                    String::new()
-                };
-                extra_notes.push(format!(
-                    "Genotype: {} (version {}, {} individuals, {} parents/F1s dropped{empty_clause}); {} values used.",
-                    prepared.note, resolved.version, individuals, parents_f1s,
-                    trait_values.iter().filter(|value| value.is_some()).count()
-                ));
-                (
-                    prepared.genotype_file.to_string_lossy().into_owned(),
-                    prepared.snps_file.map(|p| p.to_string_lossy().into_owned()).unwrap_or_default(),
-                    trait_values,
-                )
-            }
-            _ => {
-                return Err(ApiError::new(
-                    StatusCode::UNPROCESSABLE_ENTITY,
-                    "ambiguous_genotype",
-                    "Ambiguous genotype input",
-                    "give genotype_file + snps_file, or group (see /groups/{group}/genotypes)."
-                        .to_string(),
-                    "compute_gemma",
-                )
-                .with_request_id(rid));
-            }
-        };
+    let ResolvedInputs {
+        genotype_file,
+        snps_file,
+        trait_values,
+        individuals: _,
+        names: aligned_names,
+        group: aligned_group,
+        notes: input_notes,
+    } = resolve_inputs(&config, &mut request, &token, "compute_gemma", rid.clone()).await?;
+    extra_notes.extend(input_notes);
+
     // Covariates are aligned by sample name, so only a group-scoped request
     // can have them: with explicit files there is nothing to align against.
     if request_covariates_present && request_group.is_none() {
@@ -729,9 +767,6 @@ pub async fn compute_gemma(
         for note in &extra_notes {
             envelope = envelope.with_note(note);
         }
-        if let Some(note) = &basket_note {
-            envelope = envelope.with_note(note);
-        }
         // The peak is the row with the smallest p_lrt (the last column of
         // GEMMA's own .assoc output); a PheWAS there is the next question.
         if let Some(group) = request_group.as_deref() {
@@ -843,7 +878,7 @@ pub async fn compute_gemma_ravanan(
     ctx: Ctx,
     token: AuthToken,
     Query(params): Query<ComputeGemmaParams>,
-    Json(request): Json<GemmaRequest>,
+    Json(mut request): Json<GemmaRequest>,
 ) -> Result<Json<Envelope<serde_json::Value>>, ApiError> {
     let rid = ctx.request_info();
     let lmm = request.lmm.unwrap_or(9);
@@ -872,17 +907,72 @@ pub async fn compute_gemma_ravanan(
         }
     }
 
-    // ravanan is gated like the direct GEMMA run, and by the same size
-    // rule: an explicit genotype_file request carries no panel, so it is
-    // sized by the trait values it was given.
-    let trait_values = request.trait_values.clone().unwrap_or_default();
+    let config = Config::load();
+
+    // This endpoint takes the same request shape as /compute/gemma --
+    // group or file, samples or trait_values, basket or upload -- because
+    // both runners are handed exactly the same three things. Resolving it
+    // here (rather than passing "/compute/gemma"'s fields through) is what
+    // makes a `group` + `samples` request work at all; before, those fields
+    // were silently dropped and the run died reading an empty path.
+    let ResolvedInputs {
+        genotype_file,
+        snps_file,
+        trait_values,
+        individuals: panel_individuals,
+        names: _,
+        group: _,
+        notes: input_notes,
+    } = resolve_inputs(&config, &mut request, &token, "compute_gemma_ravanan", rid.clone()).await?;
+    if genotype_file.is_empty() || snps_file.is_empty() || trait_values.is_empty() {
+        return Err(ApiError::new(
+            StatusCode::UNPROCESSABLE_ENTITY,
+            "missing_inputs",
+            "No mapping inputs",
+            "ravanan needs a genotype file and a SNP map (a group whose version has a BIMBAM \
+             pair, an upload, or genotype_file + snps_file) and at least one trait value."
+                .to_string(),
+            "compute_gemma_ravanan",
+        )
+        .with_request_id(rid));
+    }
+    // Covariates and normalization are the direct runner's: the CWL workflow
+    // has no covariate step, and normalization is applied to the values
+    // before they are written out there. Refused rather than ignored --
+    // a caller who sent them would otherwise get a fit they did not ask for.
+    if !request.covariates.is_empty() {
+        return Err(ApiError::new(
+            StatusCode::UNPROCESSABLE_ENTITY,
+            "covariates_not_supported",
+            "Covariates are not supported here",
+            "the ravanan workflow runs gemma-wrapper per chromosome and has no covariate \
+             step, so `covariates` cannot be fitted on this path. Use POST /compute/gemma \
+             for a covariate fit, or drop the covariates."
+                .to_string(),
+            "compute_gemma_ravanan",
+        )
+        .with_request_id(rid));
+    }
+    if request.normalize.as_deref().map(|n| !n.trim().is_empty()) == Some(true) {
+        return Err(ApiError::new(
+            StatusCode::UNPROCESSABLE_ENTITY,
+            "normalization_not_supported",
+            "Normalization is not supported here",
+            "send the values already normalized, or use POST /compute/gemma, which applies \
+             its normalization pipeline before the run."
+                .to_string(),
+            "compute_gemma_ravanan",
+        )
+        .with_request_id(rid));
+    }
+
+    // Gated like the direct GEMMA run and by the same size rule, now with the
+    // real panel size: a samples-only request used to be sized 0 and took no
+    // slot at all.
     __gn4_claim
-        .claim_slot_or_busy(trait_values.len(), rid.clone())
+        .claim_slot_or_busy(panel_individuals, rid.clone())
         .await?;
 
-    let config = Config::load();
-    let genotype_file = request.genotype_file.clone().unwrap_or_default();
-    let snps_file = request.snps_file.clone().unwrap_or_default();
     let run_id = params.id.clone();
     let job_rid = rid.clone();
     compute_gate::ravanan()
@@ -923,6 +1013,11 @@ pub async fn compute_gemma_ravanan(
             .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.",
             );
+        // What the request resolved to first (which genotype version, how many
+        // values aligned, what was dropped), then the run's own notes.
+        for note in &input_notes {
+            envelope = envelope.with_note(note);
+        }
         for note in &output.notes {
             envelope = envelope.with_note(note);
         }