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}");
}
}
pub fn nearest_scan(
ds: &mut dyn Dataset,
run: u32,
rt_s: f64,
ms_level: u32,
) -> Result<Option<(u64, u64, f64)>> {
let mut best: Option<(u64, u64, f64)> = None;
visit_scans(ds, run, &mut |h| {
if h.ms_level == ms_level
&& let Some(t) = h.rt_s
&& best.is_none_or(|b| (t - rt_s).abs() < (b.2 - rt_s).abs())
{
best = Some((h.index, h.scan_number, t));
}
true
})?;
Ok(best)
}
pub const ISOTOPE_SPACING_DA: f64 = 1.003_355;
pub const PROTON_DA: f64 = 1.007_276;
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct MsPeak {
pub mz: f64,
pub intensity: f64,
#[serde(skip_serializing_if = "Option::is_none")]
pub charge: Option<u32>,
#[serde(skip_serializing_if = "Option::is_none")]
pub isotopes: Option<u32>,
#[serde(skip_serializing_if = "Option::is_none")]
pub monoisotopic_mz: Option<f64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub neutral_mass_da: Option<f64>,
}
fn centroids(sp: &Spectrum) -> Vec<(f64, f64)> {
let n = sp.mz.len().min(sp.intensity.len());
if sp.centroided {
return (0..n)
.filter(|&i| sp.intensity[i] > 0.0)
.map(|i| (sp.mz[i], f64::from(sp.intensity[i])))
.collect();
}
(0..n)
.filter(|&i| {
let y = sp.intensity[i];
y > 0.0
&& (i == 0 || sp.intensity[i - 1] < y)
&& (i + 1 == n || sp.intensity[i + 1] <= y)
})
.map(|i| (sp.mz[i], f64::from(sp.intensity[i])))
.collect()
}
pub fn top_peaks(sp: &Spectrum, n: usize) -> Vec<MsPeak> {
let c = centroids(sp);
if c.is_empty() || n == 0 {
return Vec::new();
}
let mut by_mz = c.clone();
by_mz.sort_by(|a, b| a.0.total_cmp(&b.0));
let tol = |mz: f64| (mz * 15e-6).max(0.003);
let find = |mz: f64, min_i: f64| -> bool {
let t = tol(mz);
let lo = by_mz.partition_point(|p| p.0 < mz - t);
by_mz[lo..]
.iter()
.take_while(|p| p.0 <= mz + t)
.any(|p| p.1 >= min_i)
};
let mut order = c;
order.sort_by(|a, b| b.1.total_cmp(&a.1));
let mut out: Vec<MsPeak> = Vec::new();
for (mz, intensity) in order {
if out.len() >= n {
break;
}
let inside = out.iter().any(|p| {
let z = f64::from(p.charge.unwrap_or(1));
let base = p.monoisotopic_mz.unwrap_or(p.mz);
(0..=8).any(|k| (mz - (base + f64::from(k) * ISOTOPE_SPACING_DA / z)).abs() <= tol(mz))
});
if inside {
continue;
}
let mut best: Option<(u32, u32)> = None;
for z in 1..=8u32 {
let mut k = 0;
while k < 6
&& find(
mz + f64::from(k + 1) * ISOTOPE_SPACING_DA / f64::from(z),
intensity * 0.02,
)
{
k += 1;
}
if k > 0 && best.is_none_or(|b| k > b.1) {
best = Some((z, k));
}
}
let charge = best.map(|b| b.0);
let mut mono = mz;
if let Some(z) = charge {
let step = ISOTOPE_SPACING_DA / f64::from(z);
for _ in 0..6 {
if find(mono - step, intensity * 0.05) {
mono -= step;
} else {
break;
}
}
}
let neutral_mass_da = charge.and_then(|z| {
let z = f64::from(z);
match sp.polarity.as_str() {
"positive" => Some(z * (mono - PROTON_DA)),
"negative" => Some(z * (mono + PROTON_DA)),
_ => None,
}
});
out.push(MsPeak {
mz,
intensity,
charge,
isotopes: best.map(|b| b.1),
monoisotopic_mz: (mono < mz).then_some(mono),
neutral_mass_da,
});
}
out
}
pub fn keep_most_intense(sp: &mut Spectrum, cap: usize) {
let n = sp.mz.len().min(sp.intensity.len());
if n <= cap {
return;
}
let mut idx: Vec<usize> = (0..n).collect();
idx.sort_by(|&a, &b| sp.intensity[b].total_cmp(&sp.intensity[a]));
idx.truncate(cap);
idx.sort_unstable();
sp.mz = idx.iter().map(|&i| sp.mz[i]).collect();
sp.intensity = idx.iter().map(|&i| sp.intensity[i]).collect();
}
#[cfg(test)]
mod peak_tests {
use super::*;
#[test]
fn charges_from_isotope_spacing() {
let mut sp = Spectrum {
centroided: true,
polarity: "positive".into(),
..Spectrum::default()
};
let pts = [
(500.0, 1000.0),
(500.0 + ISOTOPE_SPACING_DA / 2.0, 800.0),
(500.0 + ISOTOPE_SPACING_DA, 400.0),
(700.0, 600.0),
(700.0 + ISOTOPE_SPACING_DA, 300.0),
(800.0, 50.0),
];
sp.mz = pts.iter().map(|p| p.0).collect();
sp.intensity = pts.iter().map(|p| p.1 as f32).collect();
let p = top_peaks(&sp, 3);
assert_eq!(p[0].charge, Some(2));
assert_eq!(p[0].isotopes, Some(2));
assert!((p[0].neutral_mass_da.unwrap() - 2.0 * (500.0 - PROTON_DA)).abs() < 1e-9);
assert_eq!(p[1].mz, 700.0);
assert_eq!(p[1].charge, Some(1));
assert_eq!(p[2].mz, 800.0);
assert_eq!(p[2].charge, None);
keep_most_intense(&mut sp, 2);
assert_eq!(sp.mz, vec![500.0, 500.0 + ISOTOPE_SPACING_DA / 2.0]);
}
}