nmr 0.1.3

NMR data tools for Rust
Documentation
//! Read-only effective calibration and filter evidence for a processed axis.
use crate::acquisition::{ChemicalShiftReference, NormalizationEvidence, PendingGroupDelay};
use crate::processing::contracts::state::{AxisState, ProcessingDelayState};

/// A spectrum's ppm-to-Hz interval scale, independent of its acquisition carrier.
#[derive(Clone, Debug, PartialEq)]
pub struct SpectrumReference {
    pub(crate) frequency_mhz: f64,
    pub(crate) evidence: NormalizationEvidence,
}
impl SpectrumReference {
    /// Reference frequency in MHz; multiply a ppm interval by this value for Hz.
    pub fn reference_frequency_mhz(&self) -> f64 {
        self.frequency_mhz
    }
    /// Authority and versioned rule establishing this scale.
    pub fn evidence(&self) -> &NormalizationEvidence {
        &self.evidence
    }
}

/// Current digital-filter state; imported spectra without evidence remain unknown.
#[non_exhaustive]
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum ProcessedGroupDelay<'a> {
    /// This axis has no applicable filter.
    NotApplicable,
    /// No evidence establishes whether correction is needed or already applied.
    Unknown,
    /// A known delay still requires correction.
    Pending(&'a PendingGroupDelay),
    /// The library applied a correction with the recorded delay and evidence.
    Corrected {
        /// Applied delay in original sample points.
        delay_points: f64,
        /// Supporting acquisition evidence, when established.
        evidence: Option<&'a NormalizationEvidence>,
    },
}

/// Borrowed effective evidence at the current descriptor axis position.
#[derive(Clone, Copy, Debug)]
pub struct ProcessedAxisEvidence<'a>(pub(crate) &'a AxisState);
impl<'a> ProcessedAxisEvidence<'a> {
    /// Acquisition observe frequency; never inferred from a processing reference.
    pub fn observe_frequency_mhz(self) -> Option<f64> {
        self.0
            .axis
            .frequency_evidence()
            .and_then(|f| f.observe_frequency_mhz())
    }
    /// Effective ppm-to-Hz interval scale, retained through binning and derivation.
    pub fn reference_frequency_mhz(self) -> Option<f64> {
        self.chemical_shift_reference()
            .map(ChemicalShiftReference::reference_frequency_mhz)
            .or_else(|| {
                self.0
                    .axis
                    .spectrum_reference()
                    .map(SpectrumReference::reference_frequency_mhz)
            })
    }
    /// Authority establishing the effective reference scale.
    pub fn reference_evidence(self) -> Option<&'a NormalizationEvidence> {
        self.chemical_shift_reference()
            .map(ChemicalShiftReference::evidence)
            .or_else(|| {
                self.0
                    .axis
                    .spectrum_reference()
                    .map(SpectrumReference::evidence)
            })
    }
    /// Full carrier-relative calibration, only when the carrier is established.
    /// An imported SF alone supplies a scale, not a carrier chemical shift.
    pub fn chemical_shift_reference(self) -> Option<&'a ChemicalShiftReference> {
        self.0.chemical_shift_reference.as_ref()
    }
    /// Effective filter state after all completed operations.
    pub fn group_delay(self) -> ProcessedGroupDelay<'a> {
        match &self.0.group_delay {
            ProcessingDelayState::NotApplicable => ProcessedGroupDelay::NotApplicable,
            ProcessingDelayState::Unknown => ProcessedGroupDelay::Unknown,
            ProcessingDelayState::Pending(value) => ProcessedGroupDelay::Pending(value),
            ProcessingDelayState::Corrected { delay, evidence } => ProcessedGroupDelay::Corrected {
                delay_points: *delay,
                evidence: evidence.as_ref(),
            },
        }
    }
}

// Crate-private model decomposition; no wire tags or encoding policy.
impl SpectrumReference {
    #[allow(clippy::type_complexity)]
    pub(crate) fn model_parts(&self) -> (&f64, &NormalizationEvidence) {
        (&self.frequency_mhz, &self.evidence)
    }
    #[allow(clippy::type_complexity)]
    pub(crate) fn from_model_parts(
        parts: (f64, NormalizationEvidence),
    ) -> Result<Self, crate::internal::ModelError> {
        let (frequency_mhz, evidence) = parts;
        let value = Self {
            frequency_mhz,
            evidence,
        };

        if !value.frequency_mhz.is_finite() || value.frequency_mhz <= 0.0 {
            return Err(crate::internal::ModelError::Structure);
        }

        Ok(value)
    }
}

impl super::ProcessedDataset {
    /// Whether retained applied history contains a modulus operation, including
    /// processed ancestors. This is conservative evidence against the Gaussian
    /// phase-sensitive model, not proof of the current sample signs. False means
    /// no such operation was found, not that phase-sensitive representation is known.
    pub fn has_magnitude_history(&self) -> bool {
        use crate::processing::{Projection, ResolvedOperation, SpectrumOperation};
        use crate::{derivation::DerivationInput, processed::ProcessedOrigin};
        let mut pending = vec![self.provenance()];
        while let Some(provenance) = pending.pop() {
            if provenance.history().is_some_and(|history| {
                history.records().iter().any(|record| {
                    matches!(
                        record.resolved(),
                        Some(ResolvedOperation::Spectrum(SpectrumOperation::Magnitude))
                            | Some(ResolvedOperation::Projection {
                                projection: Projection::Magnitude,
                                ..
                            })
                    )
                })
            }) {
                return true;
            }
            match provenance.origin() {
                ProcessedOrigin::Library(boundary) => {
                    for input in boundary.inputs() {
                        if let DerivationInput::Processed(parent) = input {
                            pending.push(parent.provenance());
                        }
                    }
                }
                ProcessedOrigin::External(boundary) => pending.push(boundary.parent().provenance()),
                _ => {}
            }
        }
        false
    }
}