about summary refs log tree commit diff
path: root/src/suggest.rs
blob: 55128e5bdebd81bb25eb78f0d8a51f6c2543dac3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
//! QTL-mapping suggestions for the per-trait values endpoints.
//!
//! Fetching one trait's value per strain is usually the step before
//! mapping that trait, and the API can do the mapping itself
//! (`/compute/rqtl`, `/compute/gemma`). Those are `POST`s with a body, so
//! they cannot go in `next` -- following a `next` link is a `GET` that
//! returns 200, which is what makes `next` safe to follow blindly -- hence
//! [`SuggestedCall`] in the envelope's `actions`.
//!
//! What the server can fill in, it does: the values themselves, in the
//! sample order of the response they came from. What it cannot know is
//! where the genotype files live on its own filesystem, so those stay
//! bracketed placeholders: a caller that posts the body unchanged gets a
//! clear "no such file" error rather than a wrong answer.

use crate::response::SuggestedCall;

/// The two per-strain value types (`db::TraitValue`, `db::ProbeSetValue`)
/// are both `{name, value}`; this is what lets one suggestion builder
/// serve both.
pub trait NamedValue {
    fn name(&self) -> &str;
    fn value(&self) -> Option<f64>;
}

impl NamedValue for crate::db::TraitValue {
    fn name(&self) -> &str {
        &self.name
    }
    fn value(&self) -> Option<f64> {
        self.value
    }
}

impl NamedValue for crate::db::ProbeSetValue {
    fn name(&self) -> &str {
        &self.name
    }
    fn value(&self) -> Option<f64> {
        self.value
    }
}

/// [`mapping_actions_for_group`] for one of the two value types.
pub fn mapping_actions_for_group_of<T: NamedValue>(
    values: &[T],
    trait_name: &str,
    group: Option<&str>,
    normalization: Option<&crate::normalize::Pipeline>,
) -> Vec<SuggestedCall> {
    let samples: Vec<(String, Option<f64>)> = values
        .iter()
        .map(|value| (value.name().to_string(), value.value()))
        .collect();
    mapping_actions_for_group_with(&samples, trait_name, group, normalization)
}

/// [`mapping_actions`] for one of the two value types.
pub fn mapping_actions_for<T: NamedValue>(values: &[T], trait_name: &str) -> Vec<SuggestedCall> {
    let samples: Vec<(String, Option<f64>)> = values
        .iter()
        .map(|value| (value.name().to_string(), value.value()))
        .collect();
    mapping_actions(&samples, trait_name)
}

/// Placeholder for a path that must already exist on the server.
const SERVER_PATH: &str = "<path on the server, e.g. a genotype file it already holds>";

/// `POST /compute/rqtl` and `POST /compute/gemma` for one trait's
/// values, in the response's own sample order.
///
/// `samples` is `(strain name, value)`; `trait_name` labels the trait in
/// the R/qtl request (R/qtl has no other use for it, but a run should be
/// identifiable).
pub fn mapping_actions(samples: &[(String, Option<f64>)], trait_name: &str) -> Vec<SuggestedCall> {
    mapping_actions_for_group(samples, trait_name, None)
}

/// [`mapping_actions`], naming the group when the caller knows it: with a
/// group the server resolves the genotype file itself
/// (`/groups/{group}/genotypes`), so the suggested body needs no paths at
/// all.
pub fn mapping_actions_for_group(
    samples: &[(String, Option<f64>)],
    trait_name: &str,
    group: Option<&str>,
) -> Vec<SuggestedCall> {
    mapping_actions_for_group_with(samples, trait_name, group, None)
}

/// [`mapping_actions_for_group`], carrying a normalisation pipeline through
/// into the suggested bodies: a caller normalised the values they fetched,
/// so the mapping that follows must use the same pipeline or it maps
/// different numbers than the response showed.
pub fn mapping_actions_for_group_with(
    samples: &[(String, Option<f64>)],
    trait_name: &str,
    group: Option<&str>,
    normalization: Option<&crate::normalize::Pipeline>,
) -> Vec<SuggestedCall> {
    let values: Vec<Option<f64>> = samples.iter().map(|(_, value)| *value).collect();
    let named: Vec<serde_json::Value> = samples
        .iter()
        .map(|(name, value)| serde_json::json!({"name": name, "value": value}))
        .collect();

    vec![
        SuggestedCall {
            method: "POST".to_string(),
            href: "/compute/rqtl".to_string(),
            description: match group {
                Some(group) => format!(
                    "Map '{trait_name}' with R/qtl (scanone) over {group}'s current genotype \
                     file: this body carries the {n} values above as `samples`, matched onto \
                     the panel by name. Synchronous: seconds to minutes.",
                    n = samples.len()
                ),
                None => format!(
                    "Map '{trait_name}' with R/qtl (scanone): this body carries the {n} values \
                     above as `samples`. Add the `group` it belongs to (see \
                     /groups/{{group}}/genotypes) so the server resolves the genotype file, \
                     or replace `genotype_file` with a path the server can read. Synchronous: \
                     seconds to minutes.",
                    n = samples.len()
                ),
            },
            body: Some(with_normalization(
                match group {
                    Some(group) => serde_json::json!({
                        "group": group,
                        "trait_name": trait_name,
                        "samples": named,
                    }),
                    None => serde_json::json!({
                        "genotype_file": SERVER_PATH,
                        "trait_name": trait_name,
                        "samples": named,
                    }),
                },
                normalization,
            )),
        },
        SuggestedCall {
            method: "POST".to_string(),
            href: "/compute/gemma".to_string(),
            description: match group {
                Some(group) => format!(
                    "Run GEMMA's LOCO GWAS on '{trait_name}' over {group}'s current genotype \
                     file: this body carries the {n} values above as named `samples`, matched \
                     onto the panel. Synchronous: tens of seconds to minutes, so pass `?id=` \
                     and poll its status endpoint.",
                    n = samples.len()
                ),
                None => format!(
                    "Run GEMMA's LOCO GWAS on '{trait_name}': this body carries the {n} values \
                     above. Add the `group` it belongs to (see /groups/{{group}}/genotypes) so \
                     the server resolves the genotype and SNP files, or replace the \
                     `genotype_file`/`snps_file` placeholders with paths the server can read. \
                     Synchronous: tens of seconds to minutes, so pass `?id=` and poll its \
                     status endpoint.",
                    n = samples.len()
                ),
            },
            body: Some(with_normalization(
                match group {
                    Some(group) => serde_json::json!({
                        "group": group,
                        "trait_name": trait_name,
                        "samples": named,
                    }),
                    None => serde_json::json!({
                        "genotype_file": SERVER_PATH,
                        "snps_file": SERVER_PATH,
                        "trait_values": values,
                    }),
                },
                normalization,
            )),
        },
    ]
}

#[cfg(test)]
mod tests {
    use super::*;

    fn samples() -> Vec<(String, Option<f64>)> {
        vec![
            ("BXD1".to_string(), Some(9.5)),
            ("BXD2".to_string(), None),
        ]
    }

    #[test]
    fn both_mapping_endpoints_are_suggested_with_the_values_in_order() {
        let actions = mapping_actions(&samples(), "mytrait");
        assert_eq!(actions.len(), 2);
        assert_eq!(actions[0].method, "POST");
        assert_eq!(actions[0].href, "/compute/rqtl");
        assert_eq!(actions[1].href, "/compute/gemma");

        let rqtl = actions[0].body.as_ref().unwrap();
        assert_eq!(rqtl["trait_name"], "mytrait");
        assert_eq!(rqtl["samples"][0]["name"], "BXD1");
        assert_eq!(rqtl["samples"][0]["value"], 9.5);
        assert_eq!(rqtl["samples"][1]["value"], serde_json::Value::Null);

        let gemma = actions[1].body.as_ref().unwrap();
        assert_eq!(gemma["trait_values"], serde_json::json!([9.5, null]));
        // The paths are placeholders, deliberately: the server does not
        // know where a genotype file it may read lives.
        assert!(gemma["genotype_file"].as_str().unwrap().starts_with('<'));
        assert!(rqtl["genotype_file"].as_str().unwrap().starts_with('<'));
    }

    #[test]
    fn a_group_suggestion_needs_no_paths_at_all() {
        let actions = mapping_actions_for_group(&samples(), "BXD::10001", Some("BXD"));
        for action in &actions {
            let body = action.body.as_ref().unwrap().to_string();
            assert!(!body.contains('<'), "no placeholders when the group is known: {body}");
            assert_eq!(action.body.as_ref().unwrap()["group"], "BXD");
        }
        assert_eq!(actions[1].body.as_ref().unwrap()["samples"][0]["name"], "BXD1");
    }

    #[test]
    fn the_description_says_what_must_be_replaced() {
        let actions = mapping_actions(&samples(), "mytrait");
        for action in &actions {
            assert!(
                action.description.to_lowercase().contains("replace"),
                "{}",
                action.description
            );
            assert!(action.description.contains("2 values"), "{}", action.description);
        }
    }
}

/// Add a normalisation pipeline's fields to a suggested body, leaving it
/// byte-identical when there is nothing to add -- a caller who fetched
/// normalized values must map the same numbers, so the suggestion carries
/// the pipeline rather than silently mapping the raw ones.
fn with_normalization(
    body: serde_json::Value,
    normalization: Option<&crate::normalize::Pipeline>,
) -> serde_json::Value {
    let Some(pipeline) = normalization else {
        return body;
    };
    let mut object = match body {
        serde_json::Value::Object(object) => object,
        other => return other,
    };
    for (key, value) in pipeline.to_json() {
        object.insert(key, value);
    }
    serde_json::Value::Object(object)
}

// ---------------------------------------------------------------------------
// `next` links: where a caller can go from what it just got.
//
// `next` is for `GET`s only (following one must return 200), which is why the
// compute endpoints' `POST`s live in `actions`. The rule these builders
// follow is that a link is offered whenever the id it needs is already known
// to the server: a version's frequencies and markers, a marker's location and
// tally, a group's traits and PheWAS, a trait's values, a species' datasets.
// Offering the obvious next call is cheaper than making every client
// re-derive the path vocabulary, and it is the only way an agent discovers
// that `/groups/unlisted/...` exists at all.
// ---------------------------------------------------------------------------

use crate::response::path_segment;

/// `(href, description)`, ready for [`NextAction`].
pub type Link = (String, &'static str);

/// Path-safe identifier.
fn seg(value: &str) -> String {
    path_segment(value)
}

/// The listings every endpoint can reach, so a dead end is never returned.
pub fn root_links() -> Vec<Link> {
    vec![
        ("/groups".to_string(), "Every group, with its species and mapping method"),
        ("/species".to_string(), "Every species"),
        (
            "/mapping-methods".to_string(),
            "The mapping tools GeneNetwork has run (R/qtl, GEMMA, qtlreaper, ...)",
        ),
        ("/openapi.json".to_string(), "This API's OpenAPI document"),
    ]
}

/// Everything one genotype version offers: the tally, the names, the
/// positions, and the scans that run on it.
pub fn genotype_version_links(group: &str, version: &str) -> Vec<Link> {
    let base = format!(
        "/groups/{}/genotypes/{}",
        seg(group),
        seg(version)
    );
    vec![
        (
            format!("{base}/frequencies"),
            "What this panel is actually called as: call -> frequency",
        ),
        (
            format!("{base}/markers"),
            "The marker names this version carries, paged (positions are one call per marker)",
        ),
        (
            format!("{base}/markers/{{marker}}/location"),
            "One marker's position (name, chr, cM, Mb) -- fill in a marker name",
        ),
        (
            format!("{base}/markers/{{marker}}/frequencies"),
            "One marker's calls across the panel -- a flat LOD from a nearly-missing marker \
             looks like real data otherwise",
        ),
        (
            format!("{base}/markers/{{marker}}/classes?trait={{trait_id}}"),
            "One marker's trait values summarised per genotype class -- how a peak that rests \
             on two animals is told apart from one that rests on a hundred",
        ),
        (
            format!("/groups/{}", seg(group)),
            "The group's record (species, mapping method, trait count)",
        ),
    ]
}

/// The same, for a file no group lists.
pub fn unlisted_genotype_links(name: &str) -> Vec<Link> {
    let base = format!("/groups/unlisted/genotypes/{}", seg(name));
    vec![
        (
            format!("{base}/frequencies"),
            "What this panel is actually called as: call -> frequency",
        ),
        (
            format!("{base}/markers"),
            "The marker names it carries, paged",
        ),
        (
            format!("{base}/markers/{{marker}}/location"),
            "One marker's position -- fill in a marker name",
        ),
        (
            format!("{base}/markers/{{marker}}/frequencies"),
            "One marker's calls across the panel -- fill in a marker name",
        ),
    ]
}

/// One marker of one version: its position, its tally, and its PheWAS.
pub fn marker_links(group: &str, version: &str, marker: &str) -> Vec<Link> {
    let base = format!(
        "/groups/{}/genotypes/{}/markers",
        seg(group),
        seg(version)
    );
    vec![
        (
            format!("{base}/{}/location", seg(marker)),
            "This marker's position (name, chr, cM, Mb)",
        ),
        (
            format!("{base}/{}/frequencies", seg(marker)),
            "This marker's calls across the panel, as frequencies",
        ),
        (base, "The names of every marker in this version"),
        (
            format!(
                "/groups/{}/genotypes/{}/frequencies",
                seg(group),
                seg(version)
            ),
            "The whole panel's call frequencies",
        ),
        (
            format!("/groups/{}/phewas?locus={}", seg(group), seg(marker)),
            "PheWAS: every published trait of this group peaking at this marker",
        ),
    ]
}

/// One marker of a file no group lists.
pub fn unlisted_marker_links(name: &str, marker: &str) -> Vec<Link> {
    let base = format!("/groups/unlisted/genotypes/{}/markers", seg(name));
    vec![
        (
            format!("{base}/{}/location", seg(marker)),
            "This marker's position (name, chr, cM, Mb)",
        ),
        (
            format!("{base}/{}/frequencies", seg(marker)),
            "This marker's calls across the panel, as frequencies",
        ),
        (base, "Every marker name in this file"),
        (
            format!("/groups/unlisted/genotypes/{}/frequencies", seg(name)),
            "The whole file's call frequencies",
        ),
    ]
}

/// The forward hint every scan should carry: how many animals sit in each
/// genotype class at the peak. A peak resting on two animals and one resting
/// on a hundred read the same in a LOD column, and only this call tells them
/// apart. `{trait_id}` is the caller's to fill in -- the scan knows the trait's
/// values, not its PublishXRef.Id.
pub fn class_hint(group: &str, version: &str, marker: &str) -> Link {
    (
        format!(
            "/groups/{}/genotypes/{}/markers/{}/classes?trait={{trait_id}}",
            seg(group),
            seg(version),
            seg(marker)
        ),
        "Count the animals in each genotype class at this peak (n, mean, sd, min, max per \
         class): a class of one or two is a different claim from a hundred. Fill in the trait id",
    )
}

/// What a group leads to.
pub fn group_links(group: &str) -> Vec<Link> {
    let base = format!("/groups/{}", seg(group));
    vec![
        (
            format!("{base}/genotypes"),
            "The genotype versions this group can be mapped with, newest first",
        ),
        (
            format!("{base}/traits"),
            "Every published trait of this group",
        ),
        (
            "/species".to_string(),
            "The species of this group, among every species the deployment holds",
        ),
        (
            // A shape rather than an address: the caller substitutes a file
            // name. tests/envelope.rs skips hrefs with braces and insists the
            // description says what to put there, so keep that sentence.
            "/groups/unlisted/genotypes/{name}/frequencies".to_string(),
            "Or tally a genotype file that no group lists; substitute the file name (without \
             its .geno) for {name}",
        ),
    ]
}

/// What one trait leads to.
pub fn trait_links(group: &str, trait_id: i64) -> Vec<Link> {
    let base = format!("/groups/{}/traits/{}", seg(group), trait_id);
    vec![
        (
            format!("{base}/values"),
            "This trait's value per strain (and the mapping suggestions they come with)",
        ),
        (
            format!("/groups/{}/genotypes", seg(group)),
            "The genotype versions this group's traits can be mapped against",
        ),
        (
            format!("/groups/{}/traits", seg(group)),
            "Every published trait of this group",
        ),
    ]
}

/// The marker name of the row with the highest value in `score_column` --
/// what a scan's strongest locus is, for a PheWAS link that can be followed.
pub fn peak_marker_of(rows: &serde_json::Value, name_column: usize, score_column: usize) -> Option<String> {
    rows.as_array()?
        .iter()
        .filter_map(|row| {
            let row = row.as_array()?;
            let score = row.get(score_column)?.as_f64()?;
            let name = row.get(name_column)?.as_str()?.to_string();
            Some((name, score))
        })
        .max_by(|left, right| left.1.partial_cmp(&right.1).unwrap_or(std::cmp::Ordering::Equal))
        .map(|(name, _)| name)
}