temporal transformations

Author: convergentist

atelier-data/Cargo.toml

@@ -112,6 +112,10 @@ path = "tests/types/synchronizers/test_market_sync.rs"
 name = "test_market_aggregate"
 path = "tests/types/snapshots/test_market_aggregate.rs"
 
+[[test]]
+name = "test_temporal_resolutions"
+path = "tests/types/temporal/test_resolutions.rs"
+
 # ── parquet round-trip tests ──
 
 [[test]]

atelier-data/src/lib.rs

@@ -46,6 +46,9 @@ pub mod templates;
 /// Public Trades
 pub mod trades;
 
+/// Temporal data treatments
+pub mod temporal;
+
 /// Mappings for data sources
 pub mod sources;
 

atelier-data/src/temporal/mod.rs

@@ -0,0 +1,2 @@
+pub mod resolutions;
+pub use resolutions::*;

atelier-data/src/temporal/resolutions.rs

@@ -0,0 +1,71 @@
+//! Unified temporal resolution layer.
+//!
+//! Orderbook timestamps are in nanoseconds, trade timestamps in milliseconds,
+//! and other datasets might be in microseconds or seconds.
+//! This module provides a canonical representation (nanoseconds) and conversion
+//! utilities to normalize heterogeneous timestamp sources.
+
+use serde::{Deserialize, Serialize};
+
+/// Nanoseconds per microsecond.
+pub const NS_PER_US: u64 = 1_000;
+
+/// Nanoseconds per millisecond.
+pub const NS_PER_MS: u64 = 1_000_000;
+
+/// Nanoseconds per second.
+pub const NS_PER_S: u64 = 1_000_000_000;
+
+/// Supported temporal resolutions for timestamp data.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum TimeResolution {
+    Nanoseconds,
+    Microseconds,
+    Milliseconds,
+    Seconds,
+}
+
+impl TimeResolution {
+    /// Returns the number of nanoseconds per unit of this resolution.
+    pub fn nanos_per_unit(self) -> u64 {
+        match self {
+            Self::Nanoseconds => 1,
+            Self::Microseconds => NS_PER_US,
+            Self::Milliseconds => NS_PER_MS,
+            Self::Seconds => NS_PER_S,
+        }
+    }
+}
+
+/// Convert a timestamp from the given resolution to nanoseconds.
+///
+/// # Examples
+///
+/// ```
+/// use atelier_data::temporal::{TimeResolution, to_nanos};
+///
+/// let ts_ms: u64 = 1_672_304_484_932;
+/// let ts_ns = to_nanos(ts_ms, TimeResolution::Milliseconds);
+/// assert_eq!(ts_ns, ts_ms * 1_000_000);
+/// ```
+pub fn to_nanos(ts: u64, resolution: TimeResolution) -> u64 {
+    ts.saturating_mul(resolution.nanos_per_unit())
+}
+
+/// Convert a nanosecond timestamp to the target resolution as `f64`.
+///
+/// Returns a floating-point value to preserve sub-unit precision
+/// (e.g. fractional microsecond or milliseconds).
+///
+/// # Examples
+///
+/// ```
+/// use atelier_quant::temporal::{TimeResolution, from_nanos};
+///
+/// let ts_ns: u64 = 1_500_000; // 1.5 ms
+/// let ts_ms = from_nanos(ts_ns, TimeResolution::Milliseconds);
+/// assert!((ts_ms - 1.5).abs() < 1e-10);
+/// ```
+pub fn from_nanos(ts_ns: u64, resolution: TimeResolution) -> f64 {
+    ts_ns as f64 / resolution.nanos_per_unit() as f64
+}

atelier-data/tests/types/temporal/test_resolutions.rs

@@ -0,0 +1,47 @@
+#[cfg(test)]
+mod tests {
+
+    use atelier_data::temporal;
+
+    #[test]
+    fn test_from_nanos_to_seconds() {
+        let ts_ns: u64 = 1_500_000_000; // 1.5 seconds
+        let ts_us = temporal::from_nanos(ts_ns, temporal::TimeResolution::Seconds);
+        assert!((ts_us - 1.5).abs() < 1e-13);
+    }
+
+    #[test]
+    fn test_from_nanos_to_millis() {
+        let ts_ns: u64 = 1_500_000; // 1.5 milliseconds
+        let ts_ms = temporal::from_nanos(ts_ns, temporal::TimeResolution::Milliseconds);
+        assert!((ts_ms - 1.5).abs() < 1e-10);
+    }
+
+    #[test]
+    fn test_from_nanos_to_micros() {
+        let ts_ns: u64 = 1_500; // 1.5 microseconds
+        let ts_us = temporal::from_nanos(ts_ns, temporal::TimeResolution::Microseconds);
+        assert!((ts_us - 1.5).abs() < 1e-7);
+    }
+
+    #[test]
+    fn test_from_seconds_to_nanos() {
+        let ts_s: u64 = 1_672;
+        let ts_ns = temporal::to_nanos(ts_s, temporal::TimeResolution::Seconds);
+        assert_eq!(ts_ns, ts_s * temporal::NS_PER_S);
+    }
+
+    #[test]
+    fn test_from_millis_to_nanos() {
+        let ts_ms: u64 = 1_672_304;
+        let ts_ns = temporal::to_nanos(ts_ms, temporal::TimeResolution::Milliseconds);
+        assert_eq!(ts_ns, ts_ms * temporal::NS_PER_MS);
+    }
+
+    #[test]
+    fn test_from_micros_to_nanos() {
+        let ts_us: u64 = 1_672_304_484;
+        let ts_ns = temporal::to_nanos(ts_us, temporal::TimeResolution::Microseconds);
+        assert_eq!(ts_ns, ts_us * temporal::NS_PER_US);
+    }
+}