use std::collections::BTreeMap;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use crate::reader::{Dataset, SpectrumView};
use crate::{Error, Result, Spectrum};
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct ScanHeader {
pub index: u64,
pub scan_number: u64,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub native_id: Option<String>,
pub ms_level: u32,
#[serde(default)]
pub rt_s: Option<f64>,
pub polarity: String,
pub centroided: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub precursor_mz: Option<f64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub precursor_charge: Option<i32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub precursor_intensity: Option<f64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub isolation_window_mz: Option<[f64; 2]>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub activation: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub collision_energy: Option<f64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub inverse_reduced_mobility: Option<f64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub scan_filter: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub scan_window_mz: Option<[f64; 2]>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub total_ion_current: Option<f64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub base_peak_mz: Option<f64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub base_peak_intensity: Option<f64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub point_count: Option<u64>,
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub extra: BTreeMap<String, serde_json::Value>,
}
impl From<Spectrum> for ScanHeader {
fn from(s: Spectrum) -> Self {
let point_count = if s.mz.is_empty() {
None
} else {
Some(s.mz.len() as u64)
};
ScanHeader {
index: s.index,
scan_number: s.scan_number,
native_id: s.native_id,
ms_level: s.ms_level,
rt_s: s.rt_s,
polarity: s.polarity,
centroided: s.centroided,
precursor_mz: s.precursor_mz,
precursor_charge: s.precursor_charge,
precursor_intensity: s.precursor_intensity,
isolation_window_mz: s.isolation_window_mz,
activation: s.activation,
collision_energy: s.collision_energy,
inverse_reduced_mobility: s.inverse_reduced_mobility,
scan_filter: s.scan_filter,
scan_window_mz: s.scan_window_mz,
total_ion_current: s.total_ion_current,
base_peak_mz: s.base_peak_mz,
base_peak_intensity: s.base_peak_intensity,
point_count,
extra: s.extra,
}
}
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct ScanFilter {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub ms_level: Option<u32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub polarity: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub rt_min_s: Option<f64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub rt_max_s: Option<f64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub precursor_mz: Option<f64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub precursor_tol_mz: Option<f64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub precursor_tol_ppm: Option<f64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub charge: Option<i32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub activation: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub filter_contains: Option<String>,
}
pub const DEFAULT_PRECURSOR_TOL_MZ: f64 = 0.01;
impl ScanFilter {
pub fn is_empty(&self) -> bool {
*self == ScanFilter::default()
}
pub fn validate(&self) -> Result<()> {
if let Some(p) = &self.polarity
&& !matches!(p.as_str(), "positive" | "negative" | "unknown")
{
return Err(Error::Usage(format!(
"polarity `{p}`: use positive, negative or unknown"
)));
}
if let (Some(a), Some(b)) = (self.rt_min_s, self.rt_max_s)
&& a > b
{
return Err(Error::Usage(format!(
"retention-time window {a}–{b} s is empty (minimum above maximum)"
)));
}
if self.precursor_tol_mz.is_some() && self.precursor_tol_ppm.is_some() {
return Err(Error::Usage(
"give the precursor tolerance in m/z or in ppm, not both".into(),
));
}
for (name, v) in [
("precursor tolerance", self.precursor_tol_mz),
("precursor ppm tolerance", self.precursor_tol_ppm),
] {
if v.is_some_and(|v| !(v.is_finite() && v >= 0.0)) {
return Err(Error::Usage(format!(
"{name} must be a non-negative number"
)));
}
}
Ok(())
}
pub fn matches(&self, h: &ScanHeader) -> bool {
if self.ms_level.is_some_and(|l| l != h.ms_level) {
return false;
}
if self.polarity.as_ref().is_some_and(|p| *p != h.polarity) {
return false;
}
if (self.rt_min_s.is_some() || self.rt_max_s.is_some())
&& !h.rt_s.is_some_and(|rt| {
self.rt_min_s.is_none_or(|t| rt >= t) && self.rt_max_s.is_none_or(|t| rt <= t)
})
{
return false;
}
if let Some(target) = self.precursor_mz {
let tol = match (self.precursor_tol_ppm, self.precursor_tol_mz) {
(Some(ppm), _) => target.abs() * ppm * 1e-6,
(None, Some(t)) => t,
(None, None) => DEFAULT_PRECURSOR_TOL_MZ,
};
if !h.precursor_mz.is_some_and(|p| (p - target).abs() <= tol) {
return false;
}
}
if self.charge.is_some_and(|z| h.precursor_charge != Some(z)) {
return false;
}
if let Some(a) = &self.activation
&& !h
.activation
.as_ref()
.is_some_and(|x| x.eq_ignore_ascii_case(a))
{
return false;
}
if let Some(t) = &self.filter_contains {
let t = t.to_ascii_lowercase();
if !h
.scan_filter
.as_ref()
.is_some_and(|f| f.to_ascii_lowercase().contains(&t))
{
return false;
}
}
true
}
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ScanList {
pub path: String,
pub format: String,
pub run: u32,
pub scan_count: u64,
pub source: String,
#[serde(default, skip_serializing_if = "ScanFilter::is_empty")]
pub filter: ScanFilter,
pub matched: u64,
pub offset: u64,
pub returned: u64,
pub truncated: bool,
pub ms_level_counts: BTreeMap<String, u64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub rt_range_s: Option<[f64; 2]>,
pub scans: Vec<ScanHeader>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HeaderSource {
Headers,
Spectra,
}
impl HeaderSource {
pub fn name(self) -> &'static str {
match self {
HeaderSource::Headers => "headers",
HeaderSource::Spectra => "spectra",
}
}
}
pub fn visit_scans(
ds: &mut dyn Dataset,
run: u32,
visit: &mut dyn FnMut(ScanHeader) -> bool,
) -> Result<HeaderSource> {
if ds.visit_scan_headers(run, 0, visit)? {
return Ok(HeaderSource::Headers);
}
let scan_count = run_scan_count(ds, run)?;
for i in 0..scan_count {
let mut s = ds.read_spectrum_view(run, i, SpectrumView::Primary)?;
let n = s.mz.len() as u64;
s.mz = Vec::new();
s.intensity = Vec::new();
let mut h = ScanHeader::from(s);
h.point_count = Some(n);
if !visit(h) {
break;
}
}
Ok(HeaderSource::Spectra)
}
pub(crate) fn run_scan_count(ds: &mut dyn Dataset, run: u32) -> Result<u64> {
let info = ds.info()?;
info.spectra
.iter()
.find(|s| s.index == run)
.map(|s| s.scan_count)
.ok_or_else(|| {
if info.spectra.is_empty() {
Error::Usage(format!(
"{} holds no mass spectra (`info` lists what it holds)",
info.path
))
} else {
Error::Usage(format!(
"run {run} out of range ({} run{})",
info.spectra.len(),
if info.spectra.len() == 1 { "" } else { "s" }
))
}
})
}
pub fn list_scans(
ds: &mut dyn Dataset,
run: u32,
filter: &ScanFilter,
offset: u64,
limit: u64,
) -> Result<(HeaderSource, ScanPage)> {
filter.validate()?;
let mut page = ScanPage::default();
let src = visit_scans(ds, run, &mut |h| {
page.scanned += 1;
if !filter.matches(&h) {
return true;
}
page.add(h, offset, limit);
true
})?;
Ok((src, page))
}
pub fn scan_list(
ds: &mut dyn Dataset,
path: &str,
format: &str,
run: u32,
filter: &ScanFilter,
offset: u64,
limit: u64,
) -> Result<ScanList> {
let (src, page) = list_scans(ds, run, filter, offset, limit)?;
let returned = page.scans.len() as u64;
Ok(ScanList {
path: path.to_string(),
format: format.to_string(),
run,
scan_count: page.scanned,
source: src.name().into(),
filter: filter.clone(),
matched: page.matched,
offset,
returned,
truncated: offset.saturating_add(returned) < page.matched,
ms_level_counts: page.ms_level_counts,
rt_range_s: page.rt_range_s,
scans: page.scans,
})
}
#[derive(Debug, Clone, Default)]
pub struct ScanPage {
pub scanned: u64,
pub matched: u64,
pub ms_level_counts: BTreeMap<String, u64>,
pub rt_range_s: Option<[f64; 2]>,
pub scans: Vec<ScanHeader>,
}
impl ScanPage {
pub fn add(&mut self, h: ScanHeader, offset: u64, limit: u64) {
*self
.ms_level_counts
.entry(h.ms_level.to_string())
.or_insert(0) += 1;
if let Some(rt) = h.rt_s.filter(|t| t.is_finite()) {
self.rt_range_s = Some(match self.rt_range_s {
Some([a, b]) => [a.min(rt), b.max(rt)],
None => [rt, rt],
});
}
if self.matched >= offset && self.matched - offset < limit {
self.scans.push(h);
}
self.matched += 1;
}
}
#[cfg(test)]
mod tests {
use super::*;
fn h(index: u64, ms_level: u32, rt_s: f64, mz: Option<f64>, z: Option<i32>) -> ScanHeader {
ScanHeader {
index,
scan_number: index + 1,
ms_level,
rt_s: Some(rt_s),
polarity: "positive".into(),
precursor_mz: mz,
precursor_charge: z,
activation: mz.map(|_| "HCD".into()),
scan_filter: Some(if ms_level == 1 {
"FTMS + p ESI Full ms [100-1000]".into()
} else {
"FTMS + c ESI d Full ms2 500.25@hcd30.00".into()
}),
..ScanHeader::default()
}
}
#[test]
fn filters_combine() {
let scans = [
h(0, 1, 10.0, None, None),
h(1, 2, 10.5, Some(500.25), Some(2)),
h(2, 2, 11.0, Some(500.2551), Some(3)),
h(3, 2, 30.0, Some(612.3), Some(3)),
];
let f = ScanFilter {
ms_level: Some(2),
charge: Some(3),
..ScanFilter::default()
};
assert_eq!(scans.iter().filter(|s| f.matches(s)).count(), 2);
let f = ScanFilter {
precursor_mz: Some(500.25),
..ScanFilter::default()
};
assert_eq!(scans.iter().filter(|s| f.matches(s)).count(), 2);
let f = ScanFilter {
precursor_mz: Some(500.25),
precursor_tol_ppm: Some(5.0),
..ScanFilter::default()
};
assert_eq!(scans.iter().filter(|s| f.matches(s)).count(), 1);
let f = ScanFilter {
rt_min_s: Some(10.2),
rt_max_s: Some(20.0),
activation: Some("hcd".into()),
filter_contains: Some("MS2".into()),
..ScanFilter::default()
};
assert_eq!(scans.iter().filter(|s| f.matches(s)).count(), 2);
assert!(
ScanFilter {
rt_min_s: Some(5.0),
rt_max_s: Some(1.0),
..ScanFilter::default()
}
.validate()
.is_err()
);
assert!(
ScanFilter {
polarity: Some("pos".into()),
..ScanFilter::default()
}
.validate()
.is_err()
);
}
#[test]
fn pages_count_every_match() {
let mut p = ScanPage::default();
for i in 0..10 {
p.add(h(i, 1 + (i % 2) as u32, i as f64, None, None), 3, 4);
}
assert_eq!(p.matched, 10);
assert_eq!(
p.scans.iter().map(|s| s.index).collect::<Vec<_>>(),
[3, 4, 5, 6]
);
assert_eq!(p.ms_level_counts["1"], 5);
assert_eq!(p.rt_range_s, Some([0.0, 9.0]));
}
#[test]
fn absent_retention_time() {
let mut none = h(5, 1, 0.0, None, None);
none.rt_s = None;
let f = ScanFilter {
rt_min_s: Some(-1.0),
..ScanFilter::default()
};
assert!(!f.matches(&none));
assert!(ScanFilter::default().matches(&none));
let mut p = ScanPage::default();
p.add(h(0, 1, 12.0, None, None), 0, 10);
p.add(none.clone(), 0, 10);
assert_eq!(p.rt_range_s, Some([12.0, 12.0]));
assert_eq!(p.matched, 2);
let json = serde_json::to_value(&none).unwrap();
assert!(json["rt_s"].is_null(), "{json}");
}
}