feat: add 'augurs' convenience crate, re-exporting other crates

.github/workflows/rust.yml

@@ -33,12 +33,12 @@ jobs:
  - name: Install Rust toolchain
  uses: moonrepo/setup-rust@v1
  with:
- bins: cargo-nextest
+ bins: cargo-nextest,just
 
  - name: Run cargo nextest
- run: cargo nextest run
+ run: just test
  - name: Run doc tests
- run: cargo test --doc
+ run: just doctest
 
  fmt:
  name: Rustfmt

README.md

@@ -1,14 +1,15 @@
-# augurs - a time series framework for Rust
+# augurs - a time series toolkit for Rust
 
 [![Python](https:/grafana/augurs/actions/workflows/python.yml/badge.svg)](https:/grafana/augurs/actions/workflows/python.yml)
 [![Rust](https:/grafana/augurs/actions/workflows/rust.yml/badge.svg)](https:/grafana/augurs/actions/workflows/rust.yml)
 [![docs.rs](https://docs.rs/augurs-core/badge.svg)](https://docs.rs/augurs-core)
 [![crates.io](https://img.shields.io/crates/v/augurs-core.svg)](https://crates.io/crates/augurs-core)
 
-This repository contains `augurs`, a time series framework built in Rust.
+This repository contains `augurs`, a time series toolkit built in Rust.
 It aims to provide some useful primitives for working with time series,
-as well as the main functionality: heavily optimized forecasting models
-based on existing R or Python implementations.
+as well as the main functionality: heavily optimized models for forecasting,
+outlier detection, clustering, seasonality detection, changepoint detection
+and more. Most algorithms are based on existing R or Python implementations.
 
 As well as the core Rust library, augurs will provide bindings to other
 languages such as Python and Javascript (via WASM).
@@ -18,19 +19,20 @@ APIs are subject to change, and functionality may not be fully implemented.
 
 ## Crate descriptions
 
-| Name | Purpose | Status |
-| ------------------------ | -------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| [`augurs-changepoint`][] | Changepoint detection for time series | alpha - API is flexible right now |
-| [`augurs-clustering`][] | Time series clustering algorithms | alpha - API is flexible right now |
-| [`augurs-core`][] | Common structs and traits | alpha - API is flexible right now |
-| [`augurs-dtw`][] | Dynamic Time Warping (DTW) | alpha - API is flexible right now |
-| [`augurs-ets`][] | Automatic exponential smoothing models | alpha - non-seasonal models working and tested against statsforecast |
-| [`augurs-mstl`][] | Multiple Seasonal Trend Decomposition using LOESS (MSTL) | beta - working and tested against R |
-| [`augurs-outlier`][] | Outlier detection for time series | alpha - API is flexible right now |
-| [`augurs-seasons`][] | Seasonality detection using periodograms | alpha - working and tested against Python in limited scenarios |
-| [`augurs-testing`][] | Testing data and, eventually, evaluation harness for implementations | alpha - just data right now |
-| [`augurs-js`][] | WASM bindings to augurs | alpha - untested, should work though |
-| [`pyaugurs`][] | Python bindings to augurs | alpha - untested, should work though |
+| Name | Purpose | Status |
+| ------------------------ | ---------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| [`augurs`] | Wrapper crate exposing functionality of all main crates behind feature flags | alpha |
+| [`augurs-changepoint`][] | Changepoint detection for time series | alpha |
+| [`augurs-clustering`][] | Time series clustering algorithms | beta |
+| [`augurs-core`][] | Common structs and traits | alpha - API is flexible right now |
+| [`augurs-dtw`][] | Dynamic Time Warping (DTW) | beta |
+| [`augurs-ets`][] | Automatic exponential smoothing models | alpha - non-seasonal models working and tested against statsforecast |
+| [`augurs-mstl`][] | Multiple Seasonal Trend Decomposition using LOESS (MSTL) | beta - working and tested against R |
+| [`augurs-outlier`][] | Outlier detection for time series | alpha |
+| [`augurs-seasons`][] | Seasonality detection using periodograms | alpha - working and tested against Python in limited scenarios |
+| [`augurs-testing`][] | Testing data and, eventually, evaluation harness for implementations | alpha - just data right now |
+| [`augurs-js`][] | WASM bindings to augurs | alpha |
+| [`pyaugurs`][] | Python bindings to augurs | alpha |
 
 ## Releasing
 
@@ -62,6 +64,7 @@ just publish-npm
 Dual-licensed to be compatible with the Rust project.
 Licensed under the Apache License, Version 2.0 `<http://www.apache.org/licenses/LICENSE-2.0>` or the MIT license `<http://opensource.org/licenses/MIT>`, at your option.
 
+[`augurs`]: https://crates.io/crates/augurs
 [`augurs-changepoint`]: https://crates.io/crates/augurs-changepoint
 [`augurs-clustering`]: https://crates.io/crates/augurs-clustering
 [`augurs-core`]: https://crates.io/crates/augurs-core

crates/augurs-changepoint/README.md

@@ -1,12 +1,10 @@
 # Changepoint detection models.
 
-This crate provides algorithms for performing changepoint detection.
+Changepoint detection of time series.
 
 For now it is mostly just a wrapper around the [`changepoint`] crate, with
 a common `Detector` trait to allow for more implementations in future.
 
-This crate is alpha quality - APIs will almost certainly change!
-
 ## Example
 
 ```rust

crates/augurs-clustering/README.md

@@ -1,14 +1,14 @@
 # Time series clustering algorithms
 
-This crate contains algorithms for clustering time series.
+Time series clustering algorithms.
 
 So far, only DBSCAN is implemented, and the distance matrix must be passed directly.
 A crate such as [`augurs-dtw`] must be used to calculate the distance matrix for now.
 
 ## Usage
 
 ```rust
-use augurs_clustering::{Dbscan, DistanceMatrix};
+use augurs_clustering::{DbscanClusterer, DistanceMatrix};
 
 # fn main() -> Result<(), Box<dyn std::error::Error>> {
 let distance_matrix = DistanceMatrix::try_from_square(
@@ -19,7 +19,7 @@ let distance_matrix = DistanceMatrix::try_from_square(
  vec![3.0, 3.0, 4.0, 0.0],
  ],
 )?;
-let clusters = Dbscan::new(0.5, 2).fit(&distance_matrix);
+let clusters = DbscanClusterer::new(0.5, 2).fit(&distance_matrix);
 assert_eq!(clusters, vec![-1, -1, -1, -1]);
 # Ok(())
 # }

crates/augurs-clustering/benches/dbscan.rs

@@ -1,6 +1,6 @@
 use criterion::{criterion_group, criterion_main, Criterion};
 
-use augurs_clustering::Dbscan;
+use augurs_clustering::DbscanClusterer;
 use augurs_core::DistanceMatrix;
 
 fn dbscan(c: &mut Criterion) {
@@ -15,7 +15,7 @@ fn dbscan(c: &mut Criterion) {
  let distance_matrix = DistanceMatrix::try_from_square(distance_matrix).unwrap();
  c.bench_function("dbscan", |b| {
  b.iter(|| {
- Dbscan::new(10.0, 3).fit(&distance_matrix);
+ DbscanClusterer::new(10.0, 3).fit(&distance_matrix);
  });
  });
 }

crates/augurs-clustering/src/lib.rs

@@ -12,12 +12,12 @@ pub use augurs_core::DistanceMatrix;
 
 /// DBSCAN clustering algorithm.
 #[derive(Debug)]
-pub struct Dbscan {
+pub struct DbscanClusterer {
  epsilon: f64,
  min_cluster_size: usize,
 }
 
-impl Dbscan {
+impl DbscanClusterer {
  /// Create a new DBSCAN instance clustering instance.
  ///
  /// # Arguments
@@ -125,22 +125,22 @@ mod test {
  ];
  let distance_matrix = DistanceMatrix::try_from_square(distance_matrix).unwrap();
 
- let clusters = Dbscan::new(0.5, 2).fit(&distance_matrix);
+ let clusters = DbscanClusterer::new(0.5, 2).fit(&distance_matrix);
  assert_eq!(clusters, vec![-1, -1, -1, -1]);
 
- let clusters = Dbscan::new(1.0, 2).fit(&distance_matrix);
+ let clusters = DbscanClusterer::new(1.0, 2).fit(&distance_matrix);
  assert_eq!(clusters, vec![0, 0, -1, -1]);
 
- let clusters = Dbscan::new(1.0, 3).fit(&distance_matrix);
+ let clusters = DbscanClusterer::new(1.0, 3).fit(&distance_matrix);
  assert_eq!(clusters, vec![-1, -1, -1, -1]);
 
- let clusters = Dbscan::new(2.0, 2).fit(&distance_matrix);
+ let clusters = DbscanClusterer::new(2.0, 2).fit(&distance_matrix);
  assert_eq!(clusters, vec![0, 0, 0, -1]);
 
- let clusters = Dbscan::new(2.0, 3).fit(&distance_matrix);
+ let clusters = DbscanClusterer::new(2.0, 3).fit(&distance_matrix);
  assert_eq!(clusters, vec![0, 0, 0, -1]);
 
- let clusters = Dbscan::new(3.0, 3).fit(&distance_matrix);
+ let clusters = DbscanClusterer::new(3.0, 3).fit(&distance_matrix);
  assert_eq!(clusters, vec![0, 0, 0, 0]);
  }
 
@@ -155,7 +155,7 @@ mod test {
  })
  .collect::<Vec<Vec<f64>>>();
  let distance_matrix = DistanceMatrix::try_from_square(distance_matrix).unwrap();
- let clusters = Dbscan::new(10.0, 3).fit(&distance_matrix);
+ let clusters = DbscanClusterer::new(10.0, 3).fit(&distance_matrix);
  let expected = vec![
  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
  0, 0, 0, 0, 0, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,

crates/augurs-dtw/src/lib.rs

@@ -10,6 +10,7 @@ use augurs_core::DistanceMatrix;
 
 #[cfg(feature = "parallel")]
 use rayon::prelude::*;
+#[cfg(feature = "parallel")]
 use tracing::debug;
 
 /// A trait for defining a distance function.

crates/augurs-ets/Cargo.toml

@@ -28,7 +28,6 @@ mstl = ["dep:augurs-mstl"]
 serde = ["dep:serde"]
 
 [dev-dependencies]
-assert_approx_eq.workspace = true
 augurs-testing.workspace = true
 criterion.workspace = true
 iai.workspace = true

crates/augurs-ets/src/auto.rs

@@ -581,11 +581,10 @@ impl Predict for FittedAutoETS {
 #[cfg(test)]
 mod test {
  use augurs_core::Fit;
+ use augurs_testing::{assert_within_pct, data::AIR_PASSENGERS};
 
  use super::{AutoETS, AutoSpec};
  use crate::{
- assert_closeish,
- data::AIR_PASSENGERS,
  model::{ErrorComponent, SeasonalComponent, TrendComponent},
  Error,
  };
@@ -628,11 +627,11 @@ mod test {
  #[test]
  fn air_passengers_fit() {
  let auto = AutoETS::new(1, "ZZN").unwrap();
- let fit = auto.fit(&AIR_PASSENGERS).expect("fit failed");
+ let fit = auto.fit(AIR_PASSENGERS).expect("fit failed");
  assert_eq!(fit.model.model_type().error, ErrorComponent::Multiplicative);
  assert_eq!(fit.model.model_type().trend, TrendComponent::Additive);
  assert_eq!(fit.model.model_type().season, SeasonalComponent::None);
- assert_closeish!(fit.model.log_likelihood(), -831.4883541595792, 0.01);
- assert_closeish!(fit.model.aic(), 1672.9767083191584, 0.01);
+ assert_within_pct!(fit.model.log_likelihood(), -831.4883541595792, 0.01);
+ assert_within_pct!(fit.model.aic(), 1672.9767083191584, 0.01);
  }
 }

crates/augurs-ets/src/ets.rs

@@ -527,13 +527,11 @@ impl Ets {
 
 #[cfg(test)]
 mod tests {
+ use augurs_testing::{assert_approx_eq, data::AIR_PASSENGERS as AP};
 
- use crate::{
- data::AIR_PASSENGERS as AP,
- model::{
- ErrorComponent, ModelType, OptimizationCriteria, OptimizeParams, Params,
- SeasonalComponent, TrendComponent,
- },
+ use crate::model::{
+ ErrorComponent, ModelType, OptimizationCriteria, OptimizeParams, Params, SeasonalComponent,
+ TrendComponent,
  };
 
  use super::Ets;
@@ -568,7 +566,7 @@ mod tests {
  let mut amse = vec![0.0; 3];
  let mut denom = vec![0.0; 3];
  let fit = ets.etscalc_in(
- &AP,
+ AP,
  &mut init_states,
  params,
  &mut residuals,
@@ -577,9 +575,9 @@ mod tests {
  &mut denom,
  true,
  );
- assert_approx_eq::assert_approx_eq!(fit.lik, 2070.2270304137766);
- assert_approx_eq::assert_approx_eq!(amse[0], 12170.41518101);
- assert_approx_eq::assert_approx_eq!(amse[1], 12649.04373164);
- assert_approx_eq::assert_approx_eq!(amse[2], 13109.83417796);
+ assert_approx_eq!(fit.lik, 2070.2270304137766);
+ assert_approx_eq!(amse[0], 12170.41518101);
+ assert_approx_eq!(amse[1], 12649.04373164);
+ assert_approx_eq!(amse[2], 13109.83417796);
  }
 }

crates/augurs-ets/src/lib.rs

@@ -25,7 +25,6 @@
 #![warn(missing_docs)]
 
 mod auto;
-pub mod data;
 mod ets;
 pub mod model;
 mod stat;
@@ -35,21 +34,6 @@ pub mod trend;
 use augurs_core::ModelError;
 pub use auto::{AutoETS, AutoSpec, FittedAutoETS};
 
-#[cfg(test)]
-// Assert that a is within (tol * 100)% of b.
-#[macro_export]
-macro_rules! assert_closeish {
- ($a:expr, $b:expr, $tol:expr) => {
- assert!(
- (($a - $b) / $a).abs() < $tol,
- "{} is not within {}% of {}",
- $a,
- $tol * 100.0,
- $b
- );
- };
-}
-
 /// Errors returned by this crate.
 #[derive(Debug, thiserror::Error)]
 pub enum Error {