one-indexed-vec 0.2.0

A one-based (1-indexed) wrapper around Vec<T>: element at position N is accessed via vec[N].
Documentation
//! Descriptive statistics: mean, variance, skewness, kurtosis, histogram.

use crate::Vec1;

#[cfg(not(feature = "std"))]
use alloc::vec::Vec;

impl Vec1<f64> {
    /// Sample variance (divisor `n-1`).
    ///
    /// ```rust
    /// use one_indexed_vec::vec1;
    /// let v = vec1![1.0, 2.0, 3.0, 4.0, 5.0];
    /// assert!((v.sample_variance() - 2.5).abs() < 1e-10);
    /// ```
    pub fn sample_variance(&self) -> f64 {
        if self.len() < 2 {
            return 0.0;
        }
        let m = self.mean();
        let mut acc = 0.0;
        for i in 1..=self.len() {
            let d = self[i] - m;
            acc += d * d;
        }
        acc / (self.len() - 1) as f64
    }

    /// Sample standard deviation.
    pub fn sample_std_dev(&self) -> f64 {
        libm::sqrt(self.sample_variance())
    }

    /// Standard error of the mean.
    pub fn standard_error(&self) -> f64 {
        self.sample_std_dev() / libm::sqrt(self.len() as f64)
    }

    /// Skewness (Fisher-Pearson, adjusted).
    ///
    /// ```rust
    /// use one_indexed_vec::vec1;
    /// let v = vec1![1.0, 2.0, 3.0, 4.0, 5.0];
    /// assert!(v.skewness().abs() < 1e-10); // symmetric
    /// ```
    pub fn skewness(&self) -> f64 {
        let n = self.len();
        if n < 3 {
            return 0.0;
        }
        let m = self.mean();
        let s = self.std_dev();
        if s == 0.0 {
            return 0.0;
        }
        let mut acc = 0.0;
        for i in 1..=n {
            let z = (self[i] - m) / s;
            acc += z * z * z;
        }
        acc / n as f64
    }

    /// Excess kurtosis (Fisher).
    pub fn kurtosis(&self) -> f64 {
        let n = self.len();
        if n < 4 {
            return 0.0;
        }
        let m = self.mean();
        let s = self.std_dev();
        if s == 0.0 {
            return 0.0;
        }
        let mut acc = 0.0;
        for i in 1..=n {
            let z = (self[i] - m) / s;
            acc += z * z * z * z;
        }
        acc / n as f64 - 3.0
    }

    /// Sum of squared deviations from the mean.
    pub fn sum_squared_deviations(&self) -> f64 {
        if self.is_empty() {
            return 0.0;
        }
        let m = self.mean();
        let mut acc = 0.0;
        for i in 1..=self.len() {
            let d = self[i] - m;
            acc += d * d;
        }
        acc
    }

    /// A simple histogram with `bins` equal-width bins over `[min, max]`.
    ///
    /// Returns `(edges, counts)` where `edges` has length `bins + 1`.
    pub fn histogram(&self, bins: usize) -> (Vec1<f64>, Vec1<usize>) {
        assert!(bins > 0, "histogram: bins must be > 0");
        if self.is_empty() {
            return (Vec1::new(), Vec1::new());
        }
        let lo = self.min_element().unwrap();
        let hi = self.max_element().unwrap();
        let range = hi - lo;

        let mut edges = Vec1::with_capacity(bins + 1);
        for i in 0..=bins {
            edges.push(lo + range * i as f64 / bins as f64);
        }

        let mut counts = Vec1::with_capacity(bins);
        for _ in 0..bins {
            counts.push(0);
        }

        for i in 1..=self.len() {
            let x = self[i];
            let mut idx =
                if range > 0.0 { ((x - lo) / range * bins as f64).floor() as usize } else { 0 };
            if idx >= bins {
                idx = bins - 1;
            }
            counts[idx + 1] += 1;
        }

        (edges, counts)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::vec1;

    #[test]
    fn sample_variance_basic() {
        let v = vec1![1.0, 2.0, 3.0, 4.0, 5.0];
        assert!((v.sample_variance() - 2.5).abs() < 1e-10);
    }

    #[test]
    fn sample_std_dev_basic() {
        let v = vec1![1.0, 2.0, 3.0, 4.0, 5.0];
        assert!((v.sample_std_dev() - libm::sqrt(2.5)).abs() < 1e-10);
    }

    #[test]
    fn standard_error_basic() {
        let v = vec1![1.0, 2.0, 3.0, 4.0, 5.0];
        let se = v.standard_error();
        assert!(se > 0.0);
    }

    #[test]
    fn skewness_symmetric() {
        let v = vec1![1.0, 2.0, 3.0, 4.0, 5.0];
        assert!(v.skewness().abs() < 1e-10);
    }

    #[test]
    fn skewness_positive() {
        // Right-skewed data
        let v = vec1![1.0, 1.0, 1.0, 1.0, 10.0];
        assert!(v.skewness() > 0.0);
    }

    #[test]
    fn kurtosis_symmetric_uniform() {
        let v = vec1![1.0, 2.0, 3.0, 4.0, 5.0];
        // Uniform-like: negative excess kurtosis
        assert!(v.kurtosis() < 0.0);
    }

    #[test]
    fn ssd_basic() {
        let v = vec1![1.0, 2.0, 3.0, 4.0, 5.0];
        // sum of squared deviations = (4+1+0+1+4) = 10
        assert!((v.sum_squared_deviations() - 10.0).abs() < 1e-10);
    }

    #[test]
    fn histogram_basic() {
        let v = vec1![1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0];
        let (edges, counts) = v.histogram(5);
        assert_eq!(edges.len(), 6);
        assert_eq!(counts.len(), 5);
        let total: usize = counts.iter().sum();
        assert_eq!(total, 10);
    }

    #[test]
    fn histogram_empty() {
        let v: Vec1<f64> = Vec1::new();
        let (edges, counts) = v.histogram(5);
        assert!(edges.is_empty());
        assert!(counts.is_empty());
    }
}