feat(ms): preserve mzML precursor and scan metadata

crates/analysis/src/mass_spec.rs

@@ -115,7 +115,10 @@ pub fn extract_spectrum(
 #[cfg(test)]
 mod tests {
     use super::*;
-    use plotx_io::{MassSpectrum, Polarity, SpectrumId, SpectrumRepresentation};
+    use plotx_io::{
+        MassSpectrum, Polarity, SpectrumAcquisition, SpectrumId, SpectrumRepresentation,
+        SpectrumSummaryProvenance,
+    };
 
     fn scan(id: u64, time: f64, mz: &[f64], intensity: &[f64]) -> MassSpectrum {
         MassSpectrum {
@@ -125,11 +128,14 @@ mod tests {
             ms_level: 1,
             polarity: Polarity::Positive,
             representation: SpectrumRepresentation::Profile,
+            acquisition: SpectrumAcquisition::default(),
             mz: mz.to_vec(),
             intensity: intensity.to_vec(),
             tic: 0.0,
+            tic_provenance: SpectrumSummaryProvenance::Derived,
             base_peak_mz: None,
             base_peak_intensity: None,
+            base_peak_provenance: SpectrumSummaryProvenance::Derived,
             precursor: None,
         }
     }

crates/app/src/ui/batch_workflow_tests.rs

@@ -26,11 +26,14 @@ fn selecting_a_canvas_resolves_its_mass_spec_dataset() {
                 ms_level: 1,
                 polarity: Polarity::Unknown,
                 representation: SpectrumRepresentation::Centroid,
+                acquisition: plotx_io::SpectrumAcquisition::default(),
                 mz: vec![100.0],
                 intensity: vec![1.0],
                 tic: 1.0,
+                tic_provenance: plotx_io::SpectrumSummaryProvenance::Derived,
                 base_peak_mz: Some(100.0),
                 base_peak_intensity: Some(1.0),
+                base_peak_provenance: plotx_io::SpectrumSummaryProvenance::Derived,
                 precursor: None,
             }],
         }],

crates/app/src/ui/commands_mass_spec_tests.rs

@@ -25,11 +25,14 @@ fn app_with_mass_spec() -> PlotxApp {
                 ms_level: 1,
                 polarity: Polarity::Positive,
                 representation: SpectrumRepresentation::Profile,
+                acquisition: plotx_io::SpectrumAcquisition::default(),
                 mz: vec![20.0, 40.0],
                 intensity: vec![2.0, 5.0],
                 tic: 7.0,
+                tic_provenance: plotx_io::SpectrumSummaryProvenance::Derived,
                 base_peak_mz: Some(40.0),
                 base_peak_intensity: Some(5.0),
+                base_peak_provenance: plotx_io::SpectrumSummaryProvenance::Derived,
                 precursor: None,
             }],
         }],

crates/app/src/ui/scientific_script.rs

@@ -137,8 +137,31 @@ pub(crate) fn prepare_run(
             stream.spectra.iter().map(move |scan| {
                 serde_json::json!({
                     "stream_id": stream.id.get(),
+                    "spectrum_id": scan.id.get(),
+                    "source_native_id": scan.source_native_id,
                     "time_min": scan.retention_time_min,
+                    "ms_level": scan.ms_level,
                     "tic": scan.tic,
+                    "tic_provenance": summary_provenance_label(scan.tic_provenance),
+                    "base_peak_mz": scan.base_peak_mz,
+                    "base_peak_intensity": scan.base_peak_intensity,
+                    "base_peak_provenance": summary_provenance_label(scan.base_peak_provenance),
+                    "acquisition": {
+                        "instrument_configuration_id": scan.acquisition.instrument_configuration_id,
+                        "source_event_id": scan.acquisition.source_event_id,
+                        "filter_string": scan.acquisition.filter_string,
+                    },
+                    "precursor": scan.precursor.as_ref().map(|precursor| serde_json::json!({
+                        "source_spectrum_native_id": precursor.source_spectrum_native_id,
+                        "selected_mz": precursor.selected_mz,
+                        "selected_intensity": precursor.selected_intensity,
+                        "charge": precursor.charge,
+                        "isolation_window_target_mz": precursor.isolation_window_target_mz,
+                        "isolation_window_lower_offset": precursor.isolation_window_lower_offset,
+                        "isolation_window_upper_offset": precursor.isolation_window_upper_offset,
+                        "collision_energy": precursor.collision_energy,
+                        "activation_method": precursor.activation_method,
+                    })),
                 })
             })
         })
@@ -152,6 +175,13 @@ pub(crate) fn prepare_run(
     })
 }
 
+fn summary_provenance_label(provenance: plotx_io::SpectrumSummaryProvenance) -> &'static str {
+    match provenance {
+        plotx_io::SpectrumSummaryProvenance::Source => "source",
+        plotx_io::SpectrumSummaryProvenance::Derived => "derived",
+    }
+}
+
 fn floats(values: Array, name: &str) -> Result<Vec<f64>, Box<EvalAltResult>> {
     values
         .into_iter()
@@ -251,6 +281,68 @@ fn rolling_percentile(values: &[f64], width: usize, quantile: f64) -> Vec<f64> {
 mod tests {
     use super::*;
 
+    #[test]
+    fn prepared_mass_spec_scans_expose_precursor_metadata() {
+        let run = MassSpecRun {
+            source: "fixture.mzML".to_owned(),
+            metadata: std::collections::BTreeMap::new(),
+            instrument: None,
+            streams: vec![plotx_io::AcquisitionStream {
+                id: plotx_io::AcquisitionStreamId::new(1),
+                source_native_id: None,
+                source_label: None,
+                role: plotx_io::StreamRole::Primary,
+                acquisition_range: None,
+                spectra: vec![plotx_io::MassSpectrum {
+                    id: plotx_io::SpectrumId::new(2),
+                    source_native_id: Some("scan=2".to_owned()),
+                    retention_time_min: 1.5,
+                    ms_level: 2,
+                    polarity: plotx_io::Polarity::Positive,
+                    representation: plotx_io::SpectrumRepresentation::Centroid,
+                    acquisition: plotx_io::SpectrumAcquisition {
+                        instrument_configuration_id: Some("IC2".to_owned()),
+                        source_event_id: Some(3),
+                        filter_string: Some("ITMS MS2".to_owned()),
+                    },
+                    mz: vec![100.0],
+                    intensity: vec![5.0],
+                    tic: 5.0,
+                    tic_provenance: plotx_io::SpectrumSummaryProvenance::Source,
+                    base_peak_mz: Some(100.0),
+                    base_peak_intensity: Some(5.0),
+                    base_peak_provenance: plotx_io::SpectrumSummaryProvenance::Source,
+                    precursor: Some(plotx_io::Precursor {
+                        source_spectrum_native_id: Some("scan=1".to_owned()),
+                        selected_mz: Some(445.2),
+                        selected_intensity: Some(1_200.0),
+                        charge: Some(2),
+                        isolation_window_target_mz: Some(445.0),
+                        isolation_window_lower_offset: Some(0.5),
+                        isolation_window_upper_offset: Some(0.5),
+                        collision_energy: Some(25.0),
+                        activation_method: Some("CID".to_owned()),
+                    }),
+                }],
+            }],
+            chromatograms: Vec::new(),
+            import_warnings: Vec::new(),
+        };
+
+        let prepared = prepare_run(&run, None);
+        let scan = &prepared["scans"][0];
+        assert_eq!(scan["spectrum_id"], 2);
+        assert_eq!(scan["tic_provenance"], "source");
+        assert_eq!(scan["base_peak_provenance"], "source");
+        assert_eq!(scan["acquisition"]["instrument_configuration_id"], "IC2");
+        assert_eq!(scan["acquisition"]["source_event_id"], 3);
+        assert_eq!(scan["acquisition"]["filter_string"], "ITMS MS2");
+        assert_eq!(scan["precursor"]["source_spectrum_native_id"], "scan=1");
+        assert_eq!(scan["precursor"]["selected_mz"], 445.2);
+        assert_eq!(scan["precursor"]["isolation_window_target_mz"], 445.0);
+        assert_eq!(scan["precursor"]["activation_method"], "CID");
+    }
+
     #[test]
     fn script_cannot_read_an_unselected_path() {
         let error = run("load_input()", Path::new("missing.raw")).unwrap_err();

crates/core/src/project/mass_spec_convert.rs

@@ -5,8 +5,8 @@ use crate::state::{
 };
 use plotx_io::{
     AcquisitionStream, AcquisitionStreamId, ChromatogramChannel, ChromatogramChannelId,
-    ChromatogramKind, MassSpecRun, MassSpectrum, Polarity, Precursor, SpectrumId,
-    SpectrumRepresentation, StreamRole,
+    ChromatogramKind, MassSpecRun, MassSpectrum, Polarity, Precursor, SpectrumAcquisition,
+    SpectrumId, SpectrumRepresentation, SpectrumSummaryProvenance, StreamRole,
 };
 use std::collections::BTreeMap;
 use std::io::{Read, Write};
@@ -133,21 +133,45 @@ fn write_spectrum(output: &mut impl Write, spectrum: &MassSpectrum) -> Result<()
             SpectrumRepresentation::Unknown => 2,
         },
     )?;
+    write_optional_string(
+        output,
+        spectrum.acquisition.instrument_configuration_id.as_deref(),
+    )?;
+    write_optional_u64(output, spectrum.acquisition.source_event_id.map(u64::from))?;
+    write_optional_string(output, spectrum.acquisition.filter_string.as_deref())?;
     write_f64(output, spectrum.tic)?;
+    write_summary_provenance(output, spectrum.tic_provenance)?;
     write_optional_f64(output, spectrum.base_peak_mz)?;
     write_optional_f64(output, spectrum.base_peak_intensity)?;
+    write_summary_provenance(output, spectrum.base_peak_provenance)?;
     write_optional_precursor(output, spectrum.precursor.as_ref())?;
     write_f64s(output, &spectrum.mz)?;
     write_f64s(output, &spectrum.intensity)
 }
 
+fn write_summary_provenance(
+    output: &mut impl Write,
+    provenance: SpectrumSummaryProvenance,
+) -> Result<()> {
+    write_u8(
+        output,
+        match provenance {
+            SpectrumSummaryProvenance::Source => 0,
+            SpectrumSummaryProvenance::Derived => 1,
+        },
+    )
+}
+
 fn write_optional_precursor(output: &mut impl Write, precursor: Option<&Precursor>) -> Result<()> {
     let Some(precursor) = precursor else {
         return write_u8(output, 0);
     };
     write_u8(output, 1)?;
-    write_f64(output, precursor.selected_mz)?;
+    write_optional_string(output, precursor.source_spectrum_native_id.as_deref())?;
+    write_optional_f64(output, precursor.selected_mz)?;
+    write_optional_f64(output, precursor.selected_intensity)?;
     write_optional_i32(output, precursor.charge)?;
+    write_optional_f64(output, precursor.isolation_window_target_mz)?;
     write_optional_f64(output, precursor.isolation_window_lower_offset)?;
     write_optional_f64(output, precursor.isolation_window_upper_offset)?;
     write_optional_f64(output, precursor.collision_energy)?;
@@ -533,9 +557,25 @@ impl<'a, 'p, R: Read> Reader<'a, 'p, R> {
             2 => SpectrumRepresentation::Unknown,
             tag => return Err(invalid_tag("spectrum representation", tag)),
         };
+        let acquisition = SpectrumAcquisition {
+            instrument_configuration_id: self.read_optional_string()?,
+            source_event_id: self
+                .read_optional_u64()?
+                .map(|value| {
+                    u32::try_from(value).map_err(|_| {
+                        ProjectError::Invalid(
+                            "LC–MS payload source event ID exceeds u32".to_owned(),
+                        )
+                    })
+                })
+                .transpose()?,
+            filter_string: self.read_optional_string()?,
+        };
         let tic = self.read_f64()?;
+        let tic_provenance = self.read_summary_provenance()?;
         let base_peak_mz = self.read_optional_f64()?;
         let base_peak_intensity = self.read_optional_f64()?;
+        let base_peak_provenance = self.read_summary_provenance()?;
         let precursor = self.read_precursor()?;
         let mz = self.read_f64s()?;
         let intensity = self.read_f64s()?;
@@ -546,22 +586,36 @@ impl<'a, 'p, R: Read> Reader<'a, 'p, R> {
             ms_level,
             polarity,
             representation,
+            acquisition,
             mz,
             intensity,
             tic,
+            tic_provenance,
             base_peak_mz,
             base_peak_intensity,
+            base_peak_provenance,
             precursor,
         })
     }
 
+    fn read_summary_provenance(&mut self) -> Result<SpectrumSummaryProvenance> {
+        match self.read_u8()? {
+            0 => Ok(SpectrumSummaryProvenance::Source),
+            1 => Ok(SpectrumSummaryProvenance::Derived),
+            tag => Err(invalid_tag("spectrum summary provenance", tag)),
+        }
+    }
+
     fn read_precursor(&mut self) -> Result<Option<Precursor>> {
         if !self.read_option_tag()? {
             return Ok(None);
         }
         Ok(Some(Precursor {
-            selected_mz: self.read_f64()?,
+            source_spectrum_native_id: self.read_optional_string()?,
+            selected_mz: self.read_optional_f64()?,
+            selected_intensity: self.read_optional_f64()?,
             charge: self.read_optional_i32()?,
+            isolation_window_target_mz: self.read_optional_f64()?,
             isolation_window_lower_offset: self.read_optional_f64()?,
             isolation_window_upper_offset: self.read_optional_f64()?,
             collision_energy: self.read_optional_f64()?,

crates/core/src/project/mass_spec_convert_tests.rs

@@ -80,9 +80,19 @@ fn rejects_large_structural_counts_without_reserving_the_claimed_collection() {
 fn payload_round_trips_spectra_channels_precursors_and_transitions() {
     let mut run = crate::state::sample_mass_spec_run();
     run.instrument = Some("QTOF".to_owned());
+    run.streams[0].spectra[1].acquisition = SpectrumAcquisition {
+        instrument_configuration_id: Some("IC2".to_owned()),
+        source_event_id: Some(7),
+        filter_string: Some("ITMS MS2".to_owned()),
+    };
+    run.streams[0].spectra[1].tic_provenance = SpectrumSummaryProvenance::Source;
+    run.streams[0].spectra[1].base_peak_provenance = SpectrumSummaryProvenance::Source;
     run.streams[0].spectra[1].precursor = Some(Precursor {
-        selected_mz: 445.2,
+        source_spectrum_native_id: Some("scan=10".to_owned()),
+        selected_mz: Some(445.2),
+        selected_intensity: Some(1_200.0),
         charge: Some(2),
+        isolation_window_target_mz: Some(445.0),
         isolation_window_lower_offset: Some(0.5),
         isolation_window_upper_offset: Some(0.75),
         collision_energy: Some(20.0),
@@ -105,9 +115,34 @@ fn payload_round_trips_spectra_channels_precursors_and_transitions() {
     assert_eq!(decoded.streams[0].role, StreamRole::Primary);
     assert_eq!(decoded.streams[0].spectra[1].id, SpectrumId::new(12));
     assert_eq!(decoded.streams[0].spectra[1].mz, [20.0, 30.0]);
+    assert_eq!(
+        decoded.streams[0].spectra[1]
+            .acquisition
+            .instrument_configuration_id
+            .as_deref(),
+        Some("IC2")
+    );
+    assert_eq!(
+        decoded.streams[0].spectra[1].acquisition.source_event_id,
+        Some(7)
+    );
+    assert_eq!(
+        decoded.streams[0].spectra[1].tic_provenance,
+        SpectrumSummaryProvenance::Source
+    );
+    assert_eq!(
+        decoded.streams[0].spectra[1].base_peak_provenance,
+        SpectrumSummaryProvenance::Source
+    );
     let precursor = decoded.streams[0].spectra[1].precursor.as_ref().unwrap();
-    assert_eq!(precursor.selected_mz, 445.2);
+    assert_eq!(
+        precursor.source_spectrum_native_id.as_deref(),
+        Some("scan=10")
+    );
+    assert_eq!(precursor.selected_mz, Some(445.2));
+    assert_eq!(precursor.selected_intensity, Some(1_200.0));
     assert_eq!(precursor.charge, Some(2));
+    assert_eq!(precursor.isolation_window_target_mz, Some(445.0));
     assert_eq!(precursor.activation_method.as_deref(), Some("CID"));
     let channel = &decoded.chromatograms[0];
     assert_eq!(channel.kind, ChromatogramKind::SelectedReactionMonitoring);

crates/core/src/state/mass_spec_fixture.rs

@@ -1,6 +1,7 @@
 use super::*;
 use plotx_io::{
-    AcquisitionStream, ChromatogramChannel, ChromatogramChannelId, Polarity, SpectrumRepresentation,
+    AcquisitionStream, ChromatogramChannel, ChromatogramChannelId, Polarity, SpectrumAcquisition,
+    SpectrumRepresentation, SpectrumSummaryProvenance,
 };
 
 pub(crate) fn sample_mass_spec_run() -> MassSpecRun {
@@ -11,11 +12,14 @@ pub(crate) fn sample_mass_spec_run() -> MassSpecRun {
         ms_level: 1,
         polarity,
         representation: SpectrumRepresentation::Profile,
+        acquisition: SpectrumAcquisition::default(),
         mz: mz.to_vec(),
         intensity: intensity.to_vec(),
         tic,
+        tic_provenance: SpectrumSummaryProvenance::Derived,
         base_peak_mz: mz.first().copied(),
         base_peak_intensity: intensity.first().copied(),
+        base_peak_provenance: SpectrumSummaryProvenance::Derived,
         precursor: None,
     };
     MassSpecRun {