docs

src/io.rs

@@ -27,7 +27,8 @@ pub use crate::io::mzmlb::{MzMLbError, MzMLbReader};
 pub use crate::io::offset_index::OffsetIndex;
 pub use crate::io::traits::{
     MZFileReader, RandomAccessSpectrumIterator, SpectrumSource, SpectrumWriter, SpectrumAccessError,
-    SpectrumGrouping, SpectrumIterator, StreamingSpectrumIterator,
+    SpectrumGrouping, SpectrumIterator, StreamingSpectrumIterator, SpectrumReceiver, RandomAccessSpectrumSource,
+    SpectrumSourceWithMetadata, MemorySpectrumSource, RandomAccessSpectrumGroupingIterator,
 };
 pub use crate::io::utils::{DetailLevel, PreBufferedStream, checksum_file};
 pub use compression::RestartableGzDecoder;

src/io/mgf.rs

@@ -200,12 +200,12 @@ pub struct MGFReaderType<
     pub state: MGFParserState,
     pub offset: usize,
     pub error: Option<MGFError>,
-    pub index: OffsetIndex,
+    index: OffsetIndex,
     file_description: FileDescription,
     instrument_configurations: HashMap<u32, InstrumentConfiguration>,
     softwares: Vec<Software>,
     data_processings: Vec<DataProcessing>,
-    pub run: MassSpectrometryRun,
+    run: MassSpectrometryRun,
     pub detail_level: DetailLevel,
     centroid_type: PhantomData<C>,
     deconvoluted_type: PhantomData<D>,
@@ -672,6 +672,9 @@ impl<
     }
 }
 
+
+/// The MGF format does not contain any consistent metadata, but additional
+/// information can be included after creation.
 impl<
         R: io::Read,
         C: CentroidPeakAdapting + From<CentroidPeak>,
@@ -712,7 +715,7 @@ const TITLE_CV: CURIE = ControlledVocabulary::MS.curie(1000796);
 const MS_LEVEL_CV: CURIE = ControlledVocabulary::MS.curie(1000511);
 const MSN_SPECTRUM_CV: CURIE = ControlledVocabulary::MS.curie(1000580);
 
-/// An MGF writer type
+/// An MGF writer type that only writes centroided MSn spectra
 pub struct MGFWriterType<
     W: io::Write,
     C: CentroidPeakAdapting + From<CentroidPeak> = CentroidPeak,
@@ -957,7 +960,6 @@ impl<
 }
 
 impl<
-        'a,
         W: io::Write,
         C: CentroidPeakAdapting + From<CentroidPeak> + 'static,
         D: DeconvolutedPeakAdapting + From<DeconvolutedPeak> + 'static,

src/lib.rs

@@ -23,10 +23,11 @@
 //! ```rust
 //! use std::fs;
 //! use mzdata::prelude::*;
-//! use mzpeaks::{Tolerance, prelude::*};
+//! use mzpeaks::Tolerance;
 //! use mzdata::io::MzMLReader;
-//! use mzdata::spectrum::{SignalContinuity};
-//! let reader = MzMLReader::new(fs::File::open("./test/data/small.mzML").unwrap());
+//! use mzdata::spectrum::SignalContinuity;
+//!
+//! let reader = MzMLReader::open_path("./test/data/small.mzML").unwrap();
 //! for spectrum in reader {
 //!     println!("Scan {} => BP {}", spectrum.id(), spectrum.peaks().base_peak().mz);
 //!

src/meta.rs

@@ -10,8 +10,11 @@ mod run;
 mod traits;
 
 pub use data_processing::{DataProcessing, ProcessingMethod};
+pub use software::Software;
+
 pub use file_description::{FileDescription, SourceFile};
+
 pub use instrument::{Component, ComponentType, InstrumentConfiguration};
-pub use software::Software;
+
 pub use traits::MSDataFileMetadata;
 pub use run::MassSpectrometryRun;

src/meta/data_processing.rs

@@ -4,13 +4,22 @@ use std::fmt::Display;
 use crate::impl_param_described;
 use crate::params::{ControlledVocabulary, Param, ParamCow, ParamList};
 
+use super::Software;
+
+/// Describe a data processing method stage tied to a specific piece of [`Software`]
+///
+/// See <https://peptideatlas.org/tmp/mzML1.1.0.html#processingMethod>
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct ProcessingMethod {
     pub order: i8,
     pub software_reference: String,
     pub params: ParamList,
 }
 
+/// Describe a complete data processing method, a series of [`ProcessingMethod`] transformations
+/// through a pipeline of [`Software`].
+///
+/// See <https://peptideatlas.org/tmp/mzML1.1.0.html#dataProcessing>
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct DataProcessing {
     pub id: String,

src/meta/software.rs

@@ -1,6 +1,8 @@
 use crate::impl_param_described;
 use crate::params::ParamList;
 
+/// A piece of software that was associated with the acquisition, transformation or otherwise
+/// processing of mass spectrometry data. See <https://peptideatlas.org/tmp/mzML1.1.0.html#software>
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct Software {
     /// A unique identifier for the software within processing metadata

src/meta/traits.rs

@@ -75,88 +75,120 @@ pub trait MSDataFileMetadata {
 
 #[macro_export]
 /// Assumes a field for the non-`Option` facets of the [`MSDataFileMetadata`]
-/// implementation are present.
+/// implementation are present. Passing an extra level `extended` token implements
+/// the optional methods.
 macro_rules! impl_metadata_trait {
+    (extended) => {
+        $crate::impl_metadata_trait();
+
+        fn spectrum_count_hint(&self) -> Option<u64> {
+            self.num_spectra
+        }
+
+        fn run_description(&self) -> Option<&$crate::meta::MassSpectrometryRun> {
+            Some(&self.run)
+        }
+
+        fn run_description_mut(&mut self) -> Option<&mut $crate::meta::MassSpectrometryRun> {
+            Some(&mut self.run)
+        }
+    };
     () => {
-        fn data_processings(&self) -> &Vec<DataProcessing> {
+        fn data_processings(&self) -> &Vec<$crate::meta::DataProcessing> {
             &self.data_processings
         }
 
-        fn instrument_configurations(&self) -> &HashMap<u32, InstrumentConfiguration> {
+        fn instrument_configurations(&self) -> &std::collections::HashMap<u32, $crate::meta::InstrumentConfiguration> {
             &self.instrument_configurations
         }
-        fn file_description(&self) -> &FileDescription {
+        fn file_description(&self) -> &$crate::meta::FileDescription {
             &self.file_description
         }
-        fn softwares(&self) -> &Vec<Software> {
+        fn softwares(&self) -> &Vec<$crate::meta::Software> {
             &self.softwares
         }
 
-        fn data_processings_mut(&mut self) -> &mut Vec<DataProcessing> {
+        fn data_processings_mut(&mut self) -> &mut Vec<$crate::meta::DataProcessing> {
             &mut self.data_processings
         }
 
-        fn instrument_configurations_mut(&mut self) -> &mut HashMap<u32, InstrumentConfiguration> {
+        fn instrument_configurations_mut(&mut self) -> &mut std::collections::HashMap<u32, $crate::meta::InstrumentConfiguration> {
             &mut self.instrument_configurations
         }
 
-        fn file_description_mut(&mut self) -> &mut FileDescription {
+        fn file_description_mut(&mut self) -> &mut $crate::meta::FileDescription {
             &mut self.file_description
         }
 
-        fn softwares_mut(&mut self) -> &mut Vec<Software> {
+        fn softwares_mut(&mut self) -> &mut Vec<$crate::meta::Software> {
             &mut self.softwares
         }
     };
 }
 
 
 #[macro_export]
-/// Delegates the implementation of [`MSDataFileMetadata`] to an field
+/// Delegates the implementation of [`MSDataFileMetadata`] to a member. Passing an extra
+/// level `extended` token implements the optional methods.
 macro_rules! delegate_impl_metadata_trait {
+    ($src:tt, extended) => {
+        $crate::delegate_impl_metadata_trait($src);
+
+        fn spectrum_count_hint(&self) -> Option<u64> {
+            self.$src.spectrum_count_hint()
+        }
+
+        fn run_description(&self) -> Option<&$crate::meta::MassSpectrometryRun> {
+            self.$src.run_description()
+        }
+
+        fn run_description_mut(&mut self) -> Option<&mut $crate::meta::MassSpectrometryRun> {
+            self.$src.run_description_mut()
+        }
+    };
     ($src:tt) => {
 
-        fn data_processings(&self) -> &Vec<crate::meta::DataProcessing> {
+        fn data_processings(&self) -> &Vec<$crate::meta::DataProcessing> {
             self.$src.data_processings()
         }
 
-        fn instrument_configurations(&self) -> &std::collections::HashMap<u32, crate::meta::InstrumentConfiguration> {
+        fn instrument_configurations(&self) -> &std::collections::HashMap<u32, $crate::meta::InstrumentConfiguration> {
             self.$src.instrument_configurations()
         }
 
-        fn file_description(&self) -> &crate::meta::FileDescription {
+        fn file_description(&self) -> &$crate::meta::FileDescription {
             self.$src.file_description()
         }
 
-        fn softwares(&self) -> &Vec<crate::meta::Software> {
+        fn softwares(&self) -> &Vec<$crate::meta::Software> {
             self.$src.softwares()
         }
 
-        fn data_processings_mut(&mut self) -> &mut Vec<crate::meta::DataProcessing> {
+        fn data_processings_mut(&mut self) -> &mut Vec<$crate::meta::DataProcessing> {
             self.$src.data_processings_mut()
         }
 
-        fn instrument_configurations_mut(&mut self) -> &mut std::collections::HashMap<u32, crate::meta::InstrumentConfiguration> {
+        fn instrument_configurations_mut(&mut self) -> &mut std::collections::HashMap<u32, $crate::meta::InstrumentConfiguration> {
             self.$src.instrument_configurations_mut()
         }
 
-        fn file_description_mut(&mut self) -> &mut crate::meta::FileDescription {
+        fn file_description_mut(&mut self) -> &mut $crate::meta::FileDescription {
             self.$src.file_description_mut()
         }
 
-        fn softwares_mut(&mut self) -> &mut Vec<crate::meta::Software> {
+        fn softwares_mut(&mut self) -> &mut Vec<$crate::meta::Software> {
             self.$src.softwares_mut()
         }
 
         fn spectrum_count_hint(&self) -> Option<u64> {
             self.$src.spectrum_count_hint()
         }
 
-        fn run_description(&self) -> Option<&crate::meta::MassSpectrometryRun> {
+        fn run_description(&self) -> Option<&$crate::meta::MassSpectrometryRun> {
             self.$src.run_description()
         }
 
-        fn run_description_mut(&mut self) -> Option<&mut crate::meta::MassSpectrometryRun> {
+        fn run_description_mut(&mut self) -> Option<&mut $crate::meta::MassSpectrometryRun> {
             self.$src.run_description_mut()
         }
 

src/params.rs

@@ -668,6 +668,8 @@ impl ParamDescribed for ParamList {
     }
 }
 
+/// Implement the [`ParamDescribed`] trait for type `$t`, referencing a `params` member
+/// of type `Vec<`[`Param`]`>`.
 #[macro_export]
 macro_rules! impl_param_described {
     ($($t:ty), +) => {$(
@@ -687,6 +689,9 @@ macro_rules! impl_param_described {
 #[doc(hidden)]
 pub const _EMPTY_PARAM: &[Param] = &[];
 
+/// Implement the [`ParamDescribed`] trait for type `$t`, referencing a `params` member
+/// that is an `Option<Vec<`[`Param`]`>>` that will lazily be initialized automatically
+/// when it is accessed mutably.
 #[macro_export]
 macro_rules! impl_param_described_deferred {
     ($($t:ty), +) => {$(
@@ -722,6 +727,7 @@ pub enum Unit {
     MZ,
     Mass,
     PartsPerMillion,
+
     Nanometer,
 
     // Time

src/spectrum.rs

@@ -32,15 +32,15 @@ The [`SpectrumDescription`] trait is included in the crate prelude, and gives th
 read-only access to components that describe a spectrum's metadata.
 
 ```rust
-use std::fs::File;
+use mzpeaks::Tolerance;
+use mzdata::MzMLReader;
 use mzdata::prelude::*;
-use mzpeaks::{Tolerance, prelude::*};
-use mzdata::io::MzMLReader;
-use mzdata::spectrum::{SignalContinuity};
+use mzdata::spectrum::SignalContinuity;
 
-let reader = MzMLReader::new(File::open("./test/data/small.mzML").unwrap());
+let reader = MzMLReader::open_path("./test/data/small.mzML").unwrap();
 for spectrum in reader {
     println!("Scan {} => BP {}", spectrum.id(), spectrum.peaks().base_peak().mz);
+
     if spectrum.signal_continuity() < SignalContinuity::Profile {
         let peak_picked = spectrum.into_centroid().unwrap();
         println!("Matches for 579.155: {:?}",