Skip to main content

ionic/ion/decoder/decode/
windows.rs

1use super::*;
2use crate::{
3    accessions::MZ_ARRAY,
4    ion::{ArrayKind, decoder::utilities::window_directory::WindowEntry, windowing::window_index},
5};
6
7fn window_span(width: f64, from: f64, to: f64, window_count: usize) -> Option<(usize, usize)> {
8    if window_count == 0 {
9        return None;
10    }
11    let low = window_index(width, from) as usize;
12    if low >= window_count {
13        return None;
14    }
15    Some((
16        low,
17        (window_index(width, to) as usize).min(window_count - 1),
18    ))
19}
20
21#[non_exhaustive]
22#[derive(Debug, Clone, PartialEq)]
23pub struct DataXY {
24    pub x: NumericArray,
25    pub y: NumericArray,
26}
27
28impl NumericArray {
29    pub fn to_f64(&self) -> Vec<f64> {
30        match self {
31            NumericArray::F64(values) => values.clone(),
32            NumericArray::F32(values) => values.iter().map(|&value| value as f64).collect(),
33            NumericArray::F16(values) => values.iter().copied().map(f16_bits_to_f64).collect(),
34            NumericArray::I16(values) => values.iter().map(|&value| value as f64).collect(),
35            NumericArray::I32(values) => values.iter().map(|&value| value as f64).collect(),
36            NumericArray::I64(values) => values.iter().map(|&value| value as f64).collect(),
37        }
38    }
39
40    pub(crate) fn extend_f64(&self, out: &mut Vec<f64>) {
41        match self {
42            NumericArray::F64(values) => out.extend_from_slice(values),
43            NumericArray::F32(values) => out.extend(values.iter().map(|&value| value as f64)),
44            NumericArray::F16(values) => out.extend(values.iter().copied().map(f16_bits_to_f64)),
45            NumericArray::I16(values) => out.extend(values.iter().map(|&value| value as f64)),
46            NumericArray::I32(values) => out.extend(values.iter().map(|&value| value as f64)),
47            NumericArray::I64(values) => out.extend(values.iter().map(|&value| value as f64)),
48        }
49    }
50}
51
52#[non_exhaustive]
53#[derive(Debug, Clone, Copy, PartialEq, Default)]
54pub enum Select {
55    #[default]
56    All,
57    Rt(Range),
58}
59
60#[derive(Debug, Clone, Copy, PartialEq, Default)]
61pub struct ScanQuery {
62    pub mz: Range,
63    pub select: Select,
64    pub ms_level: Option<u8>,
65}
66
67#[non_exhaustive]
68pub struct Window<'a> {
69    pub index: usize,
70    pub summary: &'a ScanSummary,
71    pub mz: &'a [f64],
72    pub intensity: &'a [f64],
73}
74
75fn scan_is_selected(select: &Select, summary: &ScanSummary) -> bool {
76    match select {
77        Select::All => true,
78        Select::Rt(range) => summary.rt >= range.from && summary.rt <= range.to,
79    }
80}
81
82fn scan_summary_from_record(record: &SpectrumSummary) -> ScanSummary {
83    ScanSummary {
84        rt: record.rt,
85        rt_unit: TimeUnit::from_code(record.rt_unit),
86        ms_level: record.ms_level,
87        polarity: record.polarity,
88        selected_ion_mz: record.selected_ion_mz,
89        base_peak_mz: record.base_peak_mz,
90        base_peak_int: record.base_peak_int,
91        total_ion_current: record.total_ion_current,
92        position_x: record.position_x,
93        position_y: record.position_y,
94        position_z: record.position_z,
95    }
96}
97
98#[cfg(test)]
99#[derive(Debug, Clone, Copy, PartialEq, Eq)]
100pub(crate) enum ItemKind {
101    Spectrum,
102    Chromatogram,
103}
104
105#[cfg(test)]
106#[derive(Debug, Clone, Copy)]
107pub(crate) struct ItemSlice {
108    pub(crate) item_index: u64,
109    pub(crate) array_address_index: u64,
110    pub(crate) intensity_address_index: u64,
111}
112
113#[derive(Debug, Clone, Copy)]
114pub(crate) struct WindowRead {
115    pub(crate) mz_address: ArrayAddress,
116    pub(crate) y_address: ArrayAddress,
117}
118
119fn empty_array(dtype: u8) -> NumericArray {
120    match dtype {
121        FILE_DTYPE_F32 => NumericArray::F32(Vec::new()),
122        FILE_DTYPE_F16 => NumericArray::F16(Vec::new()),
123        FILE_DTYPE_I16 => NumericArray::I16(Vec::new()),
124        FILE_DTYPE_I32 => NumericArray::I32(Vec::new()),
125        FILE_DTYPE_I64 => NumericArray::I64(Vec::new()),
126        _ => NumericArray::F64(Vec::new()),
127    }
128}
129
130fn value_at(array: &NumericArray, index: usize) -> f64 {
131    match array {
132        NumericArray::F64(values) => values[index],
133        NumericArray::F32(values) => values[index] as f64,
134        NumericArray::F16(values) => f16_bits_to_f64(values[index]),
135        NumericArray::I16(values) => values[index] as f64,
136        NumericArray::I32(values) => values[index] as f64,
137        NumericArray::I64(values) => values[index] as f64,
138    }
139}
140
141fn append_range(dst: &mut NumericArray, src: &NumericArray, start: usize, end: usize) {
142    match (dst, src) {
143        (NumericArray::F64(d), NumericArray::F64(s)) => d.extend_from_slice(&s[start..end]),
144        (NumericArray::F32(d), NumericArray::F32(s)) => d.extend_from_slice(&s[start..end]),
145        (NumericArray::F16(d), NumericArray::F16(s)) => d.extend_from_slice(&s[start..end]),
146        (NumericArray::I16(d), NumericArray::I16(s)) => d.extend_from_slice(&s[start..end]),
147        (NumericArray::I32(d), NumericArray::I32(s)) => d.extend_from_slice(&s[start..end]),
148        (NumericArray::I64(d), NumericArray::I64(s)) => d.extend_from_slice(&s[start..end]),
149        _ => {}
150    }
151}
152
153fn first_index_at_or_after(
154    x: &NumericArray,
155    positions: std::ops::Range<usize>,
156    target: f64,
157) -> usize {
158    let (mut low, mut high) = (positions.start, positions.end);
159    while low < high {
160        let middle = low + (high - low) / 2;
161        if value_at(x, middle) < target {
162            low = middle + 1;
163        } else {
164            high = middle;
165        }
166    }
167    low
168}
169
170fn first_index_after(x: &NumericArray, positions: std::ops::Range<usize>, target: f64) -> usize {
171    let (mut low, mut high) = (positions.start, positions.end);
172    while low < high {
173        let middle = low + (high - low) / 2;
174        if value_at(x, middle) <= target {
175            low = middle + 1;
176        } else {
177            high = middle;
178        }
179    }
180    low
181}
182
183fn range_in_sorted(x: &NumericArray, low: f64, high: f64, paired: usize) -> (usize, usize) {
184    (
185        first_index_at_or_after(x, 0..paired, low),
186        first_index_after(x, 0..paired, high),
187    )
188}
189
190fn array_run(addresses: &[ArrayAddress], kind: u32) -> Option<(usize, &[ArrayAddress])> {
191    let start = addresses.iter().position(|address| {
192        address.array_type == kind && address.continues_previous_segment == 0
193    })?;
194    let length = addresses[start + 1..]
195        .iter()
196        .take_while(|address| address.continues_previous_segment == 1)
197        .count();
198    Some((start, &addresses[start..=start + length]))
199}
200
201pub(crate) fn keep_pairs_sorted(
202    x: &NumericArray,
203    y: &NumericArray,
204    low: f64,
205    high: f64,
206    x_out: &mut NumericArray,
207    y_out: &mut NumericArray,
208) {
209    let paired = x.len().min(y.len());
210    let (start, end) = range_in_sorted(x, low, high, paired);
211    append_range(x_out, x, start, end);
212    append_range(y_out, y, start, end);
213}
214
215impl IonReader {
216    pub fn require_bounds(&mut self) -> IonResult<()> {
217        self.ensure_spec_window_directory()
218    }
219
220    fn check_window(&self, index: usize, range: Range) -> IonResult<()> {
221        if !range.from.is_finite() || !range.to.is_finite() {
222            return Err("window bounds must be finite".into());
223        }
224        if range.from > range.to {
225            return Err("window: from is greater than to".into());
226        }
227        if index >= self.header.spectrum_count as usize {
228            return Err("spectrum index out of range".into());
229        }
230        Ok(())
231    }
232
233    fn window_rows(&mut self, index: usize, mz: Range) -> IonResult<Vec<WindowEntry>> {
234        self.require_bounds()?;
235
236        let width = self.header.target_mz_window as f64;
237        let window_directory = match &self.spec_window_directory {
238            WindowDirectoryCache::Loaded(index) => index,
239            _ => return Err(IonError::MissingSpectrumBounds),
240        };
241        let Some((window_low, window_high)) =
242            window_span(width, mz.from, mz.to, window_directory.window_count())
243        else {
244            return Ok(Vec::new());
245        };
246        let mut rows = Vec::new();
247        for window in window_low..=window_high {
248            if let Some(row) = window_directory.find_in_window(window, index as u32) {
249                rows.push(row);
250            }
251        }
252        Ok(rows)
253    }
254
255    pub(crate) fn get_spectrum_mz_windows(
256        &mut self,
257        scan_index: usize,
258        mz_from: f64,
259        mz_to: f64,
260    ) -> IonResult<Vec<WindowRead>> {
261        let mz = Range {
262            from: mz_from,
263            to: mz_to,
264        };
265        self.check_window(scan_index, mz)?;
266        let rows = self.window_rows(scan_index, mz)?;
267        self.window_reads(&rows, |row| row.intensity_address)
268    }
269
270    fn window_reads(
271        &self,
272        rows: &[WindowEntry],
273        y_address: impl Fn(&WindowEntry) -> u32,
274    ) -> IonResult<Vec<WindowRead>> {
275        let mut windows = Vec::with_capacity(rows.len());
276        for row in rows {
277            windows.push(WindowRead {
278                mz_address: self.array_address_at(row.mz_address)?,
279                y_address: self.array_address_at(y_address(row))?,
280            });
281        }
282        Ok(windows)
283    }
284
285    fn array_address_at(&self, ref_index: u32) -> IonResult<ArrayAddress> {
286        let start = ref_index as usize * ARRAY_ADDRESS_BYTES;
287        let bytes = self
288            .spec_array_addresses
289            .get(start..start + ARRAY_ADDRESS_BYTES)
290            .ok_or_else(|| IonError::from("window directory: array ref index out of range"))?;
291        Ok(parse_array_address(bytes))
292    }
293
294    pub(crate) fn spec_block_byte_range(&self, block_id: u32) -> IonResult<ByteRange> {
295        self.spec_container
296            .block_byte_range(block_id)
297            .ok_or_else(|| IonError::from("spectrum block id out of range"))
298    }
299
300    pub fn eic_byte_ranges(
301        &mut self,
302        mz: Range,
303        rt: Option<Range>,
304        gap: u64,
305    ) -> IonResult<Vec<ByteRange>> {
306        if !mz.from.is_finite() || !mz.to.is_finite() {
307            return Err("eic byte ranges: mz bounds must be finite".into());
308        }
309        if mz.from > mz.to {
310            return Err("eic byte ranges: mz from is greater than to".into());
311        }
312        self.ensure_spec_window_directory()?;
313
314        let width = self.header.target_mz_window as f64;
315        let rt_is_searchable = self.spec_rt_is_finite_ascending();
316
317        let address_indices = {
318            let WindowDirectoryCache::Loaded(window_directory) = &self.spec_window_directory else {
319                return Err(IonError::MissingSpectrumBounds);
320            };
321            let Some((window_low, window_high)) =
322                window_span(width, mz.from, mz.to, window_directory.window_count())
323            else {
324                return Ok(Vec::new());
325            };
326            let mut address_indices = Vec::new();
327            for window in window_low..=window_high {
328                for position in window_directory.window_range(window) {
329                    let row = window_directory.row(position);
330                    if let Some(wanted) = rt {
331                        let found = self.spectrum_rt(row.spectrum_index as usize);
332                        if found < wanted.from || found > wanted.to {
333                            if rt_is_searchable && found > wanted.to {
334                                break;
335                            }
336                            continue;
337                        }
338                    }
339                    address_indices.push(row.mz_address);
340                    address_indices.push(row.intensity_address);
341                }
342            }
343            address_indices
344        };
345
346        let mut block_ids = Vec::with_capacity(address_indices.len());
347        for index in address_indices {
348            block_ids.push(self.array_address_at(index)?.block_id);
349        }
350        block_ids.sort_unstable();
351        block_ids.dedup();
352
353        let mut ranges = Vec::with_capacity(block_ids.len());
354        for block_id in block_ids {
355            ranges.push(self.spec_block_byte_range(block_id)?);
356        }
357        merge_ranges(&mut ranges, gap);
358        Ok(ranges)
359    }
360
361    pub fn byte_ranges(&mut self, scan_index: usize, mz: Range) -> IonResult<Vec<ByteRange>> {
362        let windows = self.get_spectrum_mz_windows(scan_index, mz.from, mz.to)?;
363
364        let mut block_ids = Vec::with_capacity(windows.len() * 2);
365        for window in &windows {
366            block_ids.push(window.mz_address.block_id);
367            block_ids.push(window.y_address.block_id);
368        }
369        block_ids.sort_unstable();
370        block_ids.dedup();
371
372        let mut ranges = Vec::with_capacity(block_ids.len());
373        for block_id in block_ids {
374            ranges.push(self.spec_block_byte_range(block_id)?);
375        }
376        ranges.sort_unstable_by_key(|range| (range.offset, range.length));
377        Ok(ranges)
378    }
379
380    pub fn spectrum_window(
381        &mut self,
382        index: usize,
383        x_kind: impl Into<u32>,
384        y_kind: impl Into<u32>,
385        range: Range,
386    ) -> IonResult<DataXY> {
387        let (x_kind, y_kind) = (x_kind.into(), y_kind.into());
388        self.check_window(index, range)?;
389        if x_kind != MZ_ARRAY {
390            return self.filtered_window(index, x_kind, y_kind, range);
391        }
392        if y_kind == ACC_INT {
393            return self.mz_window(index, range, |row| row.intensity_address);
394        }
395        match self.y_shift(index, y_kind) {
396            Some(shift) => self.mz_window(index, range, |row| {
397                row.mz_address.wrapping_add_signed(shift)
398            }),
399            None => self.filtered_window(index, x_kind, y_kind, range),
400        }
401    }
402
403    fn mz_window(
404        &mut self,
405        index: usize,
406        mz: Range,
407        y_address: impl Fn(&WindowEntry) -> u32,
408    ) -> IonResult<DataXY> {
409        let rows = self.window_rows(index, mz)?;
410        let windows = self.window_reads(&rows, y_address)?;
411        let (mz_dtype, y_dtype) = windows
412            .first()
413            .map(|window| (window.mz_address.dtype, window.y_address.dtype))
414            .unwrap_or((FILE_DTYPE_F64, FILE_DTYPE_F64));
415        let mut mz_out = empty_array(mz_dtype);
416        let mut y_out = empty_array(y_dtype);
417        for window in windows {
418            let mz_segment = self.read_spectrum_array(&window.mz_address)?;
419            let y_segment = self.read_spectrum_array(&window.y_address)?;
420            keep_pairs_sorted(
421                &mz_segment,
422                &y_segment,
423                mz.from,
424                mz.to,
425                &mut mz_out,
426                &mut y_out,
427            );
428        }
429
430        Ok(DataXY {
431            x: mz_out,
432            y: y_out,
433        })
434    }
435
436    fn y_shift(&self, index: usize, y_kind: u32) -> Option<i32> {
437        let addresses = read_array_addresses_from_buffers(
438            &self.spec_entries_buf,
439            &self.spec_array_addresses,
440            index,
441        )?;
442        let addresses = addresses.as_slice();
443        let (mz_start, mz_run) = array_run(addresses, MZ_ARRAY)?;
444        array_run(addresses, ACC_INT)?;
445        let (y_start, y_run) = array_run(addresses, y_kind)?;
446        let same_split = mz_run
447            .iter()
448            .map(|address| address.element_count)
449            .eq(y_run.iter().map(|address| address.element_count));
450        same_split.then(|| y_start as i32 - mz_start as i32)
451    }
452
453    fn filtered_window(
454        &mut self,
455        index: usize,
456        x_kind: u32,
457        y_kind: u32,
458        range: Range,
459    ) -> IonResult<DataXY> {
460        let groups = match read_array_addresses_from_buffers(
461            &self.spec_entries_buf,
462            &self.spec_array_addresses,
463            index,
464        ) {
465            Some(addresses) => group_arrays(addresses.as_slice())?,
466            None => Vec::new(),
467        };
468        let x_group = groups.iter().find(|group| group.array_type == x_kind);
469        let y_group = groups.iter().find(|group| group.array_type == y_kind);
470        let (Some(x_group), Some(y_group)) = (x_group, y_group) else {
471            return Ok(DataXY {
472                x: empty_array(FILE_DTYPE_F64),
473                y: empty_array(FILE_DTYPE_F64),
474            });
475        };
476        let x = self.read_spectrum_group(x_group)?;
477        let y = self.read_spectrum_group(y_group)?;
478        let mut x_out = empty_array(x_group.dtype);
479        let mut y_out = empty_array(y_group.dtype);
480        for position in 0..x.len().min(y.len()) {
481            let value = value_at(&x, position);
482            if value >= range.from && value <= range.to {
483                append_range(&mut x_out, &x, position, position + 1);
484                append_range(&mut y_out, &y, position, position + 1);
485            }
486        }
487        Ok(DataXY { x: x_out, y: y_out })
488    }
489
490    fn read_spectrum_group(&mut self, group: &ArrayGroup) -> IonResult<NumericArray> {
491        let mut values = empty_array(group.dtype);
492        for address in &group.refs {
493            let segment = self.read_spectrum_array(address)?;
494            append_range(&mut values, &segment, 0, segment.len());
495        }
496        Ok(values)
497    }
498
499    pub fn scans_in(
500        &mut self,
501        query: &ScanQuery,
502        mut visit: impl FnMut(&Window),
503    ) -> IonResult<()> {
504        self.require_bounds()?;
505        let count = self.header.spectrum_count as usize;
506        let mut mz_out: Vec<f64> = Vec::new();
507        let mut intensity_out: Vec<f64> = Vec::new();
508        for index in 0..count {
509            let Some(record) = self.spectrum_summary(index) else {
510                continue;
511            };
512            if let Some(level) = query.ms_level
513                && record.ms_level != level
514            {
515                continue;
516            }
517            let summary = scan_summary_from_record(&record);
518            if !scan_is_selected(&query.select, &summary) {
519                continue;
520            }
521            let Some(refs) = self.spectrum_array_addresses(index) else {
522                continue;
523            };
524            let has_mz = refs
525                .iter()
526                .any(|r| r.array_type == crate::accessions::MZ_ARRAY);
527            let has_intensity = refs.iter().any(|r| r.array_type == ACC_INT);
528            if !has_mz || !has_intensity {
529                continue;
530            }
531            let data =
532                self.spectrum_window(index, ArrayKind::Mz, ArrayKind::Intensity, query.mz)?;
533            mz_out.clear();
534            data.x.extend_f64(&mut mz_out);
535            intensity_out.clear();
536            data.y.extend_f64(&mut intensity_out);
537            let window = Window {
538                index,
539                summary: &summary,
540                mz: &mz_out,
541                intensity: &intensity_out,
542            };
543            visit(&window);
544        }
545        Ok(())
546    }
547
548    #[cfg(test)]
549    pub(crate) fn candidate_items(
550        &mut self,
551        target: ItemKind,
552        axis_accession: u32,
553        lo: f64,
554        hi: f64,
555    ) -> IonResult<Vec<ItemSlice>> {
556        let is_axis = match target {
557            ItemKind::Spectrum => axis_accession == ACC_MZ,
558            ItemKind::Chromatogram => axis_accession == crate::accessions::TIME_ARRAY,
559        };
560        if !is_axis {
561            return Ok(Vec::new());
562        }
563
564        if !lo.is_finite() || !hi.is_finite() {
565            return Err("candidate_items: m/z range must be finite".into());
566        }
567        if lo > hi {
568            return Err("candidate_items: m/z range must be ordered".into());
569        }
570
571        match target {
572            ItemKind::Spectrum => {
573                let _ = self.ensure_spec_window_directory();
574            }
575            ItemKind::Chromatogram => self.ensure_chrom_window_directory(),
576        }
577
578        let width = self.header.target_mz_window as f64;
579        let window_directory = match target {
580            ItemKind::Spectrum => &self.spec_window_directory,
581            ItemKind::Chromatogram => &self.chrom_window_directory,
582        };
583        let WindowDirectoryCache::Loaded(window_directory) = window_directory else {
584            return Ok(Vec::new());
585        };
586
587        let Some((window_low, window_high)) =
588            window_span(width, lo, hi, window_directory.window_count())
589        else {
590            return Ok(Vec::new());
591        };
592
593        let mut result = Vec::new();
594        for window in window_low..=window_high {
595            for position in window_directory.window_range(window) {
596                let row = window_directory.row(position);
597                result.push(ItemSlice {
598                    item_index: row.spectrum_index as u64,
599                    array_address_index: row.mz_address as u64,
600                    intensity_address_index: row.intensity_address as u64,
601                });
602            }
603        }
604        Ok(result)
605    }
606}
607
608#[cfg(test)]
609mod tests {
610    use super::window_span;
611
612    #[test]
613    fn window_span_clamps_to_available_windows() {
614        assert_eq!(window_span(250.0, 260.0, 600.0, 4), Some((1, 2)));
615        assert_eq!(window_span(250.0, 0.0, 100000.0, 4), Some((0, 3)));
616        assert_eq!(window_span(250.0, 100000.0, 100000.0, 4), None);
617        assert_eq!(window_span(250.0, 0.0, 100.0, 0), None);
618    }
619}