doc: add more documentation and tutorial

docs/reader_tutorial.md

@@ -16,6 +16,9 @@
     - [By index](#by-index)
     - [By scan start time](#by-scan-start-time)
   - [What can you do with a spectrum?](#what-can-you-do-with-a-spectrum)
+  - [Fancy iterators](#fancy-iterators)
+    - [Random access iterators](#random-access-iterators)
+    - [Grouping iterators](#grouping-iterators)
 
 ## Open a `SpectrumSource`:
 
@@ -173,9 +176,8 @@ fn mz_read_path() -> io::Result<()> {
 
 Again, the drawback is that the reader itself cannot leave the scope created inside the macro, so you cannot hold onto the
 instance, nor do you know what kind of reader you have so you cannot customize what to do in each case.
-[`MassSpectrometryReadWriteProcess`](crate::io::MassSpectrometryReadWriteProcess) can help work around this limitation, but
-it carries its own restrictions. For an example of that, see [mzconvert](https://github.com/mobiusklein/mzdata/blob/main/examples/mzconvert.rs)
-example program.
+[`MassSpectrometryReadWriteProcess`] can help work around this limitation, but it carries its own restrictions. For an example
+of that, see [mzconvert](https://github.com/mobiusklein/mzdata/blob/main/examples/mzconvert.rs) example program.
 
 ## Getting a spectrum
 
@@ -276,4 +278,30 @@ Because a single mass spectrometry data file may contain spectra in different st
 but it is possible to convert between these four types. With the [`mzsignal`](https://crates.io/crates/mzsignal) library `mzdata` can also
 perform peak picking to centroid profile spectra when dealing with raw signal [`MultiLayerSpectrum::pick_peaks`] and [`RawSpectrum::pick_peaks_into`].
 
-For more details, see the [spectrum tutorial](crate::tutorial::spectrum).
+For more details, see the [spectrum tutorial](crate::tutorial::spectrum).
+
+## Fancy iterators
+
+### Random access iterators
+
+The [`SpectrumSource`] trait requires that the type already be an [`Iterator`], which can be convenient for reading
+all the spectra in a data source sequentially. Sometimes we might want to iterate over a subset of spectra which appear
+part-way through an MS run. The natural solution would be to use [`Iterator::skip`] or [`Iterator::filter`], but these
+would *require* that the [`SpectrumSource`] consume all the intervening spectra until it reached some you were interested
+in. The [`RandomAccessSpectrumIterator`] trait extends [`SpectrumSource`] iterators with methods to immediately jump to
+the requested location without needing to do the intermediate parsing that mirror the `get_spectrum_by_` methods described
+earlier:
+
+1. [`RandomAccessSpectrumIterator::start_from_id`]
+2. [`RandomAccessSpectrumIterator::start_from_index`]
+3. [`RandomAccessSpectrumIterator::start_from_time`]
+
+These alter the [`Iterator`] state, potentially encountering an error if the requested coordinate couldn't be located.
+
+### Grouping iterators
+
+Spectra naturally form units of hierarchy with MS levels and precursor-product relationships connecting them. A complete unit of
+that hierarchy is described as a [`SpectrumGroup`], a simple implementation of the [`SpectrumingGrouping`](crate::spectrum::SpectrumGrouping)
+trait. The [`SpectrumSource::groups`] or [`SpectrumSource::into_groups`] methods produce [`SpectrumGroupingIterator`], iterators
+over [`SpectrumGroup`]. These work by buffering to build trees of spectra before producing them and provide many of the same
+metadata and fancy iterator methods that their underlying [`SpectrumSource`] do.

docs/spectrum_tutorial.md

@@ -15,7 +15,7 @@
 As mentioned at the end of the [reading tutorial](crate::tutorial::reading) `mzdata` uses the [`SpectrumLike`] trait to
 define a set of operations that all data structures representing spectra need to provide. These are mostly implemented by
 returning a [`SpectrumDescription`] instances. The [`SpectrumLike`] also provides a few compatibility methods to provide
-limit interaction with the signal data, independent of the state it is in with the [`RefPeakDataLevel`](crate::spectrum::RefPeakDataLevel)
+limit interaction with the signal data, independent of the state it is in with the [`RefPeakDataLevel`]
 returned by [`SpectrumLike::peaks`].
 
 ### Identifying a spectrum

src/spectrum/group.rs

@@ -37,7 +37,7 @@ all MSn spectra with their associated MS1 spectrum, producing [`SpectrumGroup`]
 instances.
 
 This type emulates the same interface that [`Iterator`] exposes, save that instead
-of yield individual [`Spectrum`](crate::spectrum::Spectrum), it yields [`SpectrumGroup`] instead.
+of yield individual [`SpectrumLike`](crate::spectrum::SpectrumLike), it yields [`SpectrumGroup`] instead.
 */
 #[derive(Debug)]
 pub struct SpectrumGroupingIterator<