Skip to main content

ionic/ion/decoder/decode/
spectra.rs

1use super::*;
2
3#[inline]
4pub(crate) fn slice_summary(
5    bytes: &[u8],
6    off: u64,
7    index: usize,
8    size: usize,
9    count: u64,
10) -> Option<&[u8]> {
11    if index >= count as usize {
12        return None;
13    }
14    let base = usize::try_from(off)
15        .ok()
16        .and_then(|o| index.checked_mul(size).and_then(|d| o.checked_add(d)))?;
17    bytes.get(base..base.checked_add(size)?)
18}
19
20#[inline]
21pub(crate) fn parse_spec_summary(bytes: &[u8]) -> SpectrumSummary {
22    SpectrumSummary {
23        rt: f64::from_le_bytes(bytes[0..8].try_into().unwrap()),
24        rt_unit: bytes[54],
25        base_peak_mz: f64::from_le_bytes(bytes[8..16].try_into().unwrap()),
26        selected_ion_mz: f64::from_le_bytes(bytes[16..24].try_into().unwrap()),
27        base_peak_int: f64::from_le_bytes(bytes[24..32].try_into().unwrap()),
28        total_ion_current: f64::from_le_bytes(bytes[32..40].try_into().unwrap()),
29        ms_level: bytes[40],
30        polarity: bytes[41],
31        position_x: u32::from_le_bytes(bytes[42..46].try_into().unwrap()),
32        position_y: u32::from_le_bytes(bytes[46..50].try_into().unwrap()),
33        position_z: u32::from_le_bytes(bytes[50..54].try_into().unwrap()),
34    }
35}
36
37pub(crate) fn parse_chrom_summary(bytes: &[u8]) -> ChromatogramSummary {
38    ChromatogramSummary {
39        lowest_mz: f64::from_le_bytes(bytes[0..8].try_into().unwrap()),
40        highest_mz: f64::from_le_bytes(bytes[8..16].try_into().unwrap()),
41        lowest_wavelength: f64::from_le_bytes(bytes[16..24].try_into().unwrap()),
42        highest_wavelength: f64::from_le_bytes(bytes[24..32].try_into().unwrap()),
43        lowest_ion_mobility: f64::from_le_bytes(bytes[32..40].try_into().unwrap()),
44        highest_ion_mobility: f64::from_le_bytes(bytes[40..48].try_into().unwrap()),
45        polarity: bytes[48],
46    }
47}
48
49pub(crate) fn build_one_spectrum(rows: &[Metadatum], fallback_index: usize) -> Option<Spectrum> {
50    let children_lookup = ChildrenLookup::new(rows);
51    let spectrum_id = children_lookup.all_ids(TagId::Spectrum).first().copied()?;
52    let mut owner_rows = OwnerRows::with_capacity(rows.len());
53    for row in rows {
54        owner_rows.insert(row.id, row);
55    }
56    let policy = DefaultMetadataPolicy;
57    let mut param_buffer = Vec::new();
58    Some(parse_spectrum(
59        &owner_rows,
60        &children_lookup,
61        spectrum_id,
62        fallback_index as u32,
63        &policy,
64        &mut param_buffer,
65    ))
66}
67
68pub(crate) fn build_one_chromatogram(
69    rows: &[Metadatum],
70    fallback_index: usize,
71) -> Option<Chromatogram> {
72    let children_lookup = ChildrenLookup::new(rows);
73    let chromatogram_id = children_lookup
74        .all_ids(TagId::Chromatogram)
75        .first()
76        .copied()?;
77    let mut owner_rows = OwnerRows::with_capacity(rows.len());
78    for row in rows {
79        owner_rows.insert(row.id, row);
80    }
81    let policy = DefaultMetadataPolicy;
82    let mut param_buffer = Vec::new();
83    Some(parse_chromatogram(
84        &owner_rows,
85        &children_lookup,
86        chromatogram_id,
87        fallback_index as u32,
88        &policy,
89        &mut param_buffer,
90    ))
91}
92
93pub(crate) struct ScanIterator<'a, 'd> {
94    pub(crate) summary_chunks: std::slice::ChunksExact<'a, u8>,
95    pub(crate) entry_chunks: std::slice::ChunksExact<'a, u8>,
96    pub(crate) address_bytes: &'a [u8],
97    pub(crate) container: &'d mut dyn ContainerAccess,
98    pub(crate) mz_values: &'d mut Vec<f64>,
99    pub(crate) int_values: &'d mut Vec<f64>,
100    pub(crate) rt_min: f64,
101    pub(crate) rt_max: f64,
102    pub(crate) ms_level: u8,
103}
104
105impl<'a, 'd> ScanIterator<'a, 'd> {
106    #[allow(clippy::too_many_arguments)]
107    pub(crate) fn new(
108        summary_bytes: &'a [u8],
109        entry_bytes: &'a [u8],
110        address_bytes: &'a [u8],
111        container: &'d mut dyn ContainerAccess,
112        mz_values: &'d mut Vec<f64>,
113        int_values: &'d mut Vec<f64>,
114        rt_min: f64,
115        rt_max: f64,
116        ms_level: u8,
117    ) -> Self {
118        Self {
119            summary_chunks: summary_bytes.chunks_exact(SPEC_SUMMARY_SIZE),
120            entry_chunks: entry_bytes.chunks_exact(INDEX_ENTRY_BYTES),
121            address_bytes,
122            container,
123            mz_values,
124            int_values,
125            rt_min,
126            rt_max,
127            ms_level,
128        }
129    }
130
131    pub(crate) fn run<F>(&mut self, callback: &mut F)
132    where
133        F: FnMut(&ScanSummary, &[f64], &[f64]),
134    {
135        for (summary_bytes, entry_bytes) in
136            self.summary_chunks.by_ref().zip(self.entry_chunks.by_ref())
137        {
138            let summary = parse_spec_summary(summary_bytes);
139            if !summary.rt.is_finite() || summary.rt < self.rt_min || summary.rt > self.rt_max {
140                continue;
141            }
142            if self.ms_level != 0 && summary.ms_level != self.ms_level {
143                continue;
144            }
145            if !read_scan_arrays(
146                self.container,
147                entry_bytes,
148                self.address_bytes,
149                self.mz_values,
150                self.int_values,
151            ) {
152                continue;
153            }
154            let len = self.mz_values.len().min(self.int_values.len());
155            if len == 0 {
156                continue;
157            }
158            let summary = ScanSummary {
159                rt: summary.rt,
160                rt_unit: TimeUnit::from_code(summary.rt_unit),
161                ms_level: summary.ms_level,
162                polarity: summary.polarity,
163                base_peak_mz: summary.base_peak_mz,
164                selected_ion_mz: summary.selected_ion_mz,
165                base_peak_int: summary.base_peak_int,
166                total_ion_current: summary.total_ion_current,
167                position_x: summary.position_x,
168                position_y: summary.position_y,
169                position_z: summary.position_z,
170            };
171            callback(&summary, &self.mz_values[..len], &self.int_values[..len]);
172        }
173    }
174}
175
176impl IonReader {
177    pub fn spectrum_summary(&self, index: usize) -> Option<SpectrumSummary> {
178        let b = slice_summary(
179            &self.spec_summary_buf,
180            0,
181            index,
182            SPEC_SUMMARY_SIZE,
183            self.header.spectrum_count,
184        )?;
185        Some(parse_spec_summary(b))
186    }
187
188    pub(crate) fn spectrum_rt(&self, index: usize) -> f64 {
189        let start = index * SPEC_SUMMARY_SIZE;
190        let Some(bytes) = self.spec_summary_buf.get(start..start + 8) else {
191            return f64::NAN;
192        };
193        let mut rt = [0u8; 8];
194        rt.copy_from_slice(bytes);
195        f64::from_le_bytes(rt)
196    }
197
198    pub(crate) fn spec_rt_is_finite_ascending(&self) -> bool {
199        if let Some(known) = self.spec_rt_finite_ascending.get() {
200            return known;
201        }
202        let mut previous = f64::NEG_INFINITY;
203        let mut ascending = true;
204        for index in 0..self.header.spectrum_count as usize {
205            let rt = self.spectrum_rt(index);
206            if !rt.is_finite() || rt < previous {
207                ascending = false;
208                break;
209            }
210            previous = rt;
211        }
212        self.spec_rt_finite_ascending.set(Some(ascending));
213        ascending
214    }
215
216    pub fn spectrum_summaries(&self) -> IonResult<Vec<SpectrumSummary>> {
217        let count = usize::try_from(self.header.spectrum_count)
218            .map_err(|_| IonError::from("spec summary: out of bounds"))?;
219        let len = self.spec_summary_buf.len();
220        if len != count * SPEC_SUMMARY_SIZE {
221            return Err(
222                format!("spec summary: len={len} != count={count} × {SPEC_SUMMARY_SIZE}").into(),
223            );
224        }
225        Ok(self
226            .spec_summary_buf
227            .chunks_exact(SPEC_SUMMARY_SIZE)
228            .map(parse_spec_summary)
229            .collect())
230    }
231
232    pub fn chromatogram_summary(&self, index: usize) -> Option<ChromatogramSummary> {
233        let b = slice_summary(
234            &self.chrom_summary_buf,
235            0,
236            index,
237            CHROM_SUMMARY_SIZE,
238            self.header.chrom_count,
239        )?;
240        Some(parse_chrom_summary(b))
241    }
242
243    pub fn chromatogram_summaries(&self) -> IonResult<Vec<ChromatogramSummary>> {
244        let count = usize::try_from(self.header.chrom_count)
245            .map_err(|_| IonError::from("chrom summary: out of bounds"))?;
246        let len = self.chrom_summary_buf.len();
247        if len != count * CHROM_SUMMARY_SIZE {
248            return Err(format!(
249                "chrom summary: len={len} != count={count} × {CHROM_SUMMARY_SIZE}"
250            )
251            .into());
252        }
253        Ok(self
254            .chrom_summary_buf
255            .chunks_exact(CHROM_SUMMARY_SIZE)
256            .map(parse_chrom_summary)
257            .collect())
258    }
259
260    pub(crate) fn global_metadata(&self) -> IonResult<Vec<Metadatum>> {
261        parse_global_metadata(
262            &self.global_meta_buf,
263            0,
264            self.header.global_meta_count,
265            self.header.global_meta_numeric_count,
266            self.header.global_meta_string_count,
267            self.header.compression_codec,
268            self.header.global_meta_uncompressed_bytes,
269            self.decompression_limit,
270            MetaColumnLayout::new().without_ids_reset(),
271        )
272    }
273
274    pub fn spectrum_metadata(&self) -> IonResult<Vec<Metadatum>> {
275        self.spec_meta_reader.read_all()
276    }
277
278    pub fn chromatogram_metadata(&self) -> IonResult<Vec<Metadatum>> {
279        self.chrom_meta_reader.read_all()
280    }
281
282    pub(crate) fn spectrum_metadata_grouped(&self) -> IonResult<Vec<Vec<Metadatum>>> {
283        self.spec_meta_reader.read_all_grouped()
284    }
285
286    pub(crate) fn chromatogram_metadata_grouped(&self) -> IonResult<Vec<Vec<Metadatum>>> {
287        self.chrom_meta_reader.read_all_grouped()
288    }
289
290    pub fn spectrum_metadata_at(&mut self, index: usize) -> IonResult<Vec<Metadatum>> {
291        self.spec_meta_reader.read_item(index as u64)
292    }
293
294    pub fn chromatogram_metadata_at(&mut self, index: usize) -> IonResult<Vec<Metadatum>> {
295        self.chrom_meta_reader.read_item(index as u64)
296    }
297
298    pub fn spectrum(&mut self, index: usize) -> IonResult<Option<Spectrum>> {
299        if index >= self.header.spectrum_count as usize {
300            return Ok(None);
301        }
302        let rows = self.spec_meta_reader.read_item(index as u64)?;
303        let Some(mut spectrum) = build_one_spectrum(&rows, index) else {
304            return Ok(None);
305        };
306
307        if let Some(array_addresses) = read_array_addresses_from_buffers(
308            &self.spec_entries_buf,
309            &self.spec_array_addresses,
310            index,
311        ) {
312            let groups = group_arrays(array_addresses.as_slice())?;
313            let bd_list = spectrum
314                .binary_data_array_list
315                .get_or_insert_with(BinaryDataArrayList::default);
316            for group in groups {
317                let decoded = read_group_decoded_bytes(&group, &mut self.spec_container)?;
318                attach_logical_array(
319                    bd_list,
320                    group.array_type,
321                    group.array_cv_code,
322                    group.dtype,
323                    &decoded,
324                )?;
325            }
326            bd_list.count = Some(bd_list.binary_data_arrays.len());
327        }
328        Ok(Some(spectrum))
329    }
330
331    pub fn chromatogram(&mut self, index: usize) -> IonResult<Option<Chromatogram>> {
332        if index >= self.header.chrom_count as usize {
333            return Ok(None);
334        }
335        let rows = self.chrom_meta_reader.read_item(index as u64)?;
336        let Some(mut chromatogram) = build_one_chromatogram(&rows, index) else {
337            return Ok(None);
338        };
339
340        if let (Some(array_addresses), Some(container)) = (
341            read_array_addresses_from_buffers(
342                &self.chrom_entries_buf,
343                &self.chrom_array_addresses,
344                index,
345            ),
346            self.chrom_container.as_mut(),
347        ) {
348            let groups = group_arrays(array_addresses.as_slice())?;
349            let bd_list = chromatogram
350                .binary_data_array_list
351                .get_or_insert_with(BinaryDataArrayList::default);
352            for group in groups {
353                let decoded = read_group_decoded_bytes(&group, container)?;
354                attach_logical_array(
355                    bd_list,
356                    group.array_type,
357                    group.array_cv_code,
358                    group.dtype,
359                    &decoded,
360                )?;
361            }
362            bd_list.count = Some(bd_list.binary_data_arrays.len());
363        }
364        Ok(Some(chromatogram))
365    }
366}
367
368impl ScanSource for IonReader {
369    fn for_each_summary(&mut self, callback: &mut dyn FnMut(usize, ScanSummary)) {
370        for (index, chunk) in self
371            .spec_summary_buf
372            .chunks_exact(SPEC_SUMMARY_SIZE)
373            .enumerate()
374        {
375            let summary = parse_spec_summary(chunk);
376            callback(
377                index,
378                ScanSummary {
379                    rt: summary.rt,
380                    rt_unit: TimeUnit::from_code(summary.rt_unit),
381                    base_peak_mz: summary.base_peak_mz,
382                    selected_ion_mz: summary.selected_ion_mz,
383                    base_peak_int: summary.base_peak_int,
384                    total_ion_current: summary.total_ion_current,
385                    ms_level: summary.ms_level,
386                    polarity: summary.polarity,
387                    position_x: summary.position_x,
388                    position_y: summary.position_y,
389                    position_z: summary.position_z,
390                },
391            );
392        }
393    }
394
395    fn load_scan(&mut self, index: usize, mz: &mut Vec<f64>, intensity: &mut Vec<f64>) -> bool {
396        let count = match usize::try_from(self.header.spectrum_count) {
397            Ok(c) => c,
398            Err(_) => return false,
399        };
400        if index >= count {
401            return false;
402        }
403        let all_entries = self.spec_entries_buf.as_ref();
404        let array_address_bytes = self.spec_array_addresses.as_ref();
405        let entry_start = index * INDEX_ENTRY_BYTES;
406        let Some(entry) = all_entries.get(entry_start..entry_start + INDEX_ENTRY_BYTES) else {
407            return false;
408        };
409        read_scan_arrays(
410            &mut self.spec_container,
411            entry,
412            array_address_bytes,
413            mz,
414            intensity,
415        )
416    }
417
418    fn for_each_in_range<F>(&mut self, rt_min: f64, rt_max: f64, ms_level: u8, mut callback: F)
419    where
420        Self: Sized,
421        F: FnMut(&ScanSummary, &[f64], &[f64]),
422    {
423        let summary_bytes = self.spec_summary_buf.as_ref();
424        let _count = match usize::try_from(self.header.spectrum_count) {
425            Ok(count) => count,
426            Err(_) => return,
427        };
428        let entry_bytes = self.spec_entries_buf.as_ref();
429        let array_address_bytes = self.spec_array_addresses.as_ref();
430        let (container, mz_values, int_values) = (
431            &mut self.spec_container as &mut dyn ContainerAccess,
432            &mut self.mz_values,
433            &mut self.int_values,
434        );
435        ScanIterator::new(
436            summary_bytes,
437            entry_bytes,
438            array_address_bytes,
439            container,
440            mz_values,
441            int_values,
442            rt_min,
443            rt_max,
444            ms_level,
445        )
446        .run(&mut callback);
447    }
448}