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
|
//! `GET /groups/{group}/phewas` -- every published trait whose QTL peaks
//! within a window of one chromosomal position.
//!
//! `PublishXRef.Locus` is the marker each published trait's QTL peaks at,
//! so "traits peaking at these markers" is a PheWAS around a position
//! once the marker table says which markers fall in the window. Both
//! halves are already here: the marker table from the group's genotype
//! file (`src/genotypes.rs`) and the traits from the database
//! (`db::get_phewas_traits`).
//!
//! The window is in **base pairs** and centred on the position, so
//! `window=10000` means 10 kb up- and downstream. Marker spacing in a
//! panel is what decides whether anything is in it -- on BXD's WGS panel
//! the median gap is well under a kilobase in dense regions but sparse
//! elsewhere, so an empty answer is information, not an error, and the
//! response says how many markers were in the window.
use axum::Json;
use axum::extract::{Path, Query};
use gnauth_macros::gnauth;
use serde::{Deserialize, Serialize};
use utoipa::ToSchema;
use crate::auth::AuthToken;
use crate::config::Config;
use crate::db;
use crate::error::{ApiError, Unauthorized};
use crate::genotypes;
use crate::response::{Ctx, Envelope, path_segment};
/// The window and its centre.
#[derive(Deserialize, utoipa::IntoParams)]
pub struct PhewasParams {
/// Centre the window on this marker, e.g. a QTL peak from a mapping.
/// Takes precedence over `chr`/`mb`.
pub locus: Option<String>,
/// Chromosome, e.g. "9". Required unless `locus` is given.
pub chr: Option<String>,
/// Position on `chr`, in megabases -- the unit mappings report.
/// Required unless `locus` is given.
pub mb: Option<f64>,
/// Half-width of the window in base pairs: 10000 means 10 kb either
/// side. Default 10000.
pub window: Option<f64>,
/// Genotype version whose marker table defines the window; defaults
/// to the group's current one (see /groups/{group}/genotypes).
pub genotype_version: Option<String>,
}
/// A trait whose QTL peak is in the window.
#[derive(Serialize, ToSchema)]
pub struct PhewasHit {
/// `PublishXRef.Id` -- the trait's id within its group.
pub trait_id: u32,
pub phenotype_id: u16,
/// The PublishFreeze the trait belongs to, e.g. "BXDPublish".
#[serde(skip_serializing_if = "Option::is_none")]
pub dataset: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub abbreviation: Option<String>,
/// Post-publication description, else pre-publication, else original.
#[serde(skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
/// The marker this trait peaks at -- the one that put it in the window.
pub locus: String,
pub chr: String,
pub mb: f64,
pub lrs: f64,
pub lod: f64,
#[serde(skip_serializing_if = "Option::is_none")]
pub mean: Option<f64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub additive: Option<f64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub nsamples: Option<i32>,
#[serde(skip_serializing_if = "Option::is_none")]
pub pubmed_id: Option<u32>,
#[serde(skip_serializing_if = "Option::is_none")]
pub url: Option<String>,
}
/// A marker the window covers.
#[derive(Serialize, ToSchema)]
pub struct WindowMarker {
pub name: String,
pub mb: f64,
}
/// The PheWAS result.
#[derive(Serialize, ToSchema)]
pub struct Phewas {
pub group: String,
/// The genotype version whose marker table was used.
pub genotype_version: String,
/// The window's centre.
pub centre: Centre,
/// Half-width, in base pairs.
pub window_bp: f64,
/// Markers in the window; the traits below peak at one of them.
pub markers: Vec<WindowMarker>,
/// Traits peaking in the window, strongest first.
pub traits: Vec<PhewasHit>,
}
/// Where the window is centred.
#[derive(Serialize, ToSchema)]
pub struct Centre {
#[serde(skip_serializing_if = "Option::is_none")]
pub locus: Option<String>,
pub chr: String,
pub mb: f64,
}
#[utoipa::path(get, path = "/groups/{group}/phewas",
summary = "PheWAS: every published trait peaking within a window of one position",
description = "Finds the markers within `window` base pairs of a chromosomal position -- \
given either as `locus` (a marker name, e.g. a QTL peak) or as `chr` + `mb` -- and returns \
every published trait of the group whose `PublishXRef.Locus` is one of them, strongest first. \
The window is centred on the position: `window=10000` is 10 kb up- and downstream. An empty \
`traits` list is a real answer (no trait peaks that close), and `markers` says how many \
markers were in the window.",
params(("group" = String, Path, description = "InbredSet name, e.g. BXD"), PhewasParams),
responses(
(status = 200, description = "The traits peaking in the window, with the markers found", body = Envelope<Phewas>),
Unauthorized,
(status = 404, description = "No such group, genotype version, or locus", body = ApiError),
(status = 422, description = "Neither locus nor chr+mb given, or a negative window", body = ApiError),
(status = 503, description = "Database unavailable", body = ApiError),
(status = 500, description = "Database or genotype-file error", body = ApiError)
)
)]
#[gnauth(token_only)]
pub async fn group_phewas(
ctx: Ctx,
Path(group): Path<String>,
Query(params): Query<PhewasParams>,
_token: AuthToken,
) -> Result<Json<Envelope<Phewas>>, ApiError> {
let rid = ctx.request_info();
let window_bp = params.window.unwrap_or(10_000.0);
if !(window_bp.is_finite() && window_bp >= 0.0) {
return Err(ApiError::new(
axum::http::StatusCode::UNPROCESSABLE_ENTITY,
"invalid_window",
"Invalid window",
format!("window must be a non-negative number of base pairs (got {window_bp})."),
"group_phewas",
)
.with_request_id(rid));
}
let directory = Config::load().genotype_files_dir;
let group_for_lookup = group.clone();
let version = params.genotype_version.clone();
let locus = params.locus.clone();
let given_chr = params.chr.clone();
let given_mb = params.mb;
let resolved_window = tokio::task::spawn_blocking(move || {
let dir = std::path::Path::new(&directory);
let resolved = genotypes::resolve(dir, &group_for_lookup, version.as_deref())?;
let meta = genotypes::file_meta(&resolved.geno)?;
let centre = match (&locus, &given_chr, given_mb) {
(Some(locus), _, _) => {
let marker = meta.markers.iter().find(|marker| &marker.name == locus);
match marker.and_then(|marker| marker.mb.map(|mb| (marker, mb))) {
Some((marker, mb)) => (Some(marker.name.clone()), marker.chr.clone(), mb),
None => {
return Err(genotypes::GenotypeError::NotFound(format!(
"no marker '{locus}' with a position in this genotype version; \
pass chr and mb instead, or check the name with \
/groups/{}/genotypes/{}/markers",
resolved_geno_group(&resolved.version),
resolved.version
)));
}
}
}
(None, Some(chr), Some(mb)) => (None, chr.clone(), mb),
_ => {
return Err(genotypes::GenotypeError::NotFound(
"give either locus, or chr and mb".to_string(),
));
}
};
let (centre_locus, centre_chr, centre_mb) = centre;
let half = window_bp / 1_000_000.0;
let mut markers: Vec<genotypes::Marker> = meta
.markers
.into_iter()
.filter(|marker| {
marker.chr == centre_chr
&& marker
.mb
.is_some_and(|mb| (mb - centre_mb).abs() <= half)
})
.collect();
markers.sort_by(|a, b| {
a.mb
.unwrap_or(0.0)
.partial_cmp(&b.mb.unwrap_or(0.0))
.unwrap_or(std::cmp::Ordering::Equal)
});
Ok::<_, genotypes::GenotypeError>((
resolved.version,
centre_locus,
centre_chr,
centre_mb,
markers,
))
})
.await
.map_err(|e| {
ApiError::new(
axum::http::StatusCode::INTERNAL_SERVER_ERROR,
"internal_error",
"Internal error",
e.to_string(),
"group_phewas",
)
.with_request_id(rid.clone())
})?
.map_err(|e| match e {
genotypes::GenotypeError::Invalid(message) => ApiError::new(
axum::http::StatusCode::UNPROCESSABLE_ENTITY,
"invalid_individuals",
"Unusable individual selection",
message,
"group_phewas",
)
.with_request_id(rid.clone()),
genotypes::GenotypeError::Io(message) => ApiError::new(
axum::http::StatusCode::INTERNAL_SERVER_ERROR,
"genotypes_unreadable",
"Genotype files could not be read",
message,
"group_phewas",
)
.with_request_id(rid.clone()),
genotypes::GenotypeError::NotFound(message) if message.starts_with("give either") => {
ApiError::new(
axum::http::StatusCode::UNPROCESSABLE_ENTITY,
"missing_position",
"No position given",
message,
"group_phewas",
)
.with_request_id(rid.clone())
}
genotypes::GenotypeError::NotFound(message) => ApiError::new(
axum::http::StatusCode::NOT_FOUND,
"not_found",
"Not found",
message,
"group_phewas",
)
.with_request_id(rid.clone()),
})?;
let (version, centre_locus, centre_chr, centre_mb, markers) = resolved_window;
let loci: Vec<String> = markers.iter().map(|marker| marker.name.clone()).collect();
let group_for_db = group.clone();
let traits_found = tokio::task::spawn_blocking(move || {
let group_row = db::get_group_by_name(&group_for_db)?;
match group_row {
Some(group_row) => db::get_phewas_traits(group_row.id, &loci),
None => Ok(Vec::new()),
}
})
.await
.map_err(|e| {
ApiError::new(
axum::http::StatusCode::INTERNAL_SERVER_ERROR,
"internal_error",
"Internal error",
e.to_string(),
"group_phewas",
)
.with_request_id(rid.clone())
})?
.map_err(|e| ApiError::from_db(e, "group_phewas").with_request_id(rid.clone()))?;
// Marker name -> position, so each hit carries where it peaks.
let positions: std::collections::HashMap<&str, (String, f64)> = markers
.iter()
.filter_map(|marker| {
marker
.mb
.map(|mb| (marker.name.as_str(), (marker.chr.clone(), mb)))
})
.collect();
let hits: Vec<PhewasHit> = traits_found
.into_iter()
.filter_map(|trait_info| {
let locus = trait_info.locus.clone()?;
let (chr, mb) = positions.get(locus.as_str())?.clone();
Some(PhewasHit {
description: trait_info
.post_publication_description
.clone()
.or_else(|| trait_info.pre_publication_description.clone())
.or_else(|| trait_info.original_description.clone()),
trait_id: trait_info.id,
phenotype_id: trait_info.phenotype_id,
dataset: trait_info.dataset.clone(),
abbreviation: trait_info.abbreviation.clone(),
locus,
chr,
mb,
lrs: trait_info.lrs.unwrap_or(0.0),
lod: trait_info.lod.unwrap_or(0.0),
mean: trait_info.mean,
additive: trait_info.additive,
nsamples: trait_info.nsamples,
pubmed_id: trait_info.pubmed_id,
url: trait_info.url.clone(),
})
})
.collect();
let mut envelope = ctx
.envelope(Phewas {
group: group.clone(),
genotype_version: version.clone(),
centre: Centre {
locus: centre_locus,
chr: centre_chr.clone(),
mb: centre_mb,
},
window_bp,
markers: markers
.iter()
.filter_map(|marker| {
marker.mb.map(|mb| WindowMarker {
name: marker.name.clone(),
mb,
})
})
.collect(),
traits: hits,
})
.with_note(
"lod = lrs / 4.604. The window is centred on the position, so window=10000 covers \
10 kb either side; a trait is in it when its PublishXRef peak marker is one of the \
markers listed.",
);
if markers.is_empty() {
envelope = envelope.with_note(
"No marker of this genotype version falls in the window, so no trait can be \
reported: widen `window`, or check the position against \
/groups/{group}/genotypes/{version}/markers.",
);
}
envelope = envelope
.with_next(
&format!("/groups/{}", path_segment(&group)),
"The group's record",
)
.with_next(
&format!(
"/groups/{}/phewas?{}&window={}",
path_segment(&group),
match params.locus.as_deref() {
Some(locus) => format!("locus={}", path_segment(locus)),
None => format!(
"chr={}&mb={}",
path_segment(¢re_chr),
centre_mb
),
},
window_bp * 10.0
),
"The same PheWAS with a ten-times wider window",
);
Ok(Json(envelope.with_links(crate::suggest::root_links())))
}
/// The group name a version stem belongs to, for error messages: `BXD.8`
/// belongs to `BXD`.
fn resolved_geno_group(version: &str) -> &str {
version.split('.').next().unwrap_or(version)
}
#[cfg(test)]
mod tests {
use super::resolved_geno_group;
#[test]
fn the_group_name_is_the_stem_before_the_first_dot() {
assert_eq!(resolved_geno_group("BXD.8"), "BXD");
assert_eq!(resolved_geno_group("HET3-ITP.12"), "HET3-ITP");
assert_eq!(resolved_geno_group("BXD"), "BXD");
}
}
|