Skip to main content

ionic/ion/decoder/decode/
windows.rs

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