feat: add theta sketch (part 2) (#59)

* feat: add theta sketch (part 2)

* add binomial_bounds to support calculate lower_bound&&upper_bound
* add get_lower_bound&&get_upper_bound in ThetaSketch

* refine NumStdDev and some interface

* refine code: remove unnecessary pub

* better common layout

Signed-off-by: tison <wander4096@gmail.com>

---------

Signed-off-by: tison <wander4096@gmail.com>
Co-authored-by: tison <wander4096@gmail.com>

Author: ZENOTME

datasketches/src/common/binomial_bounds.rs

@@ -0,0 +1,27 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Data structures and functions that may be used across all the sketch families.
+
+// public common components for datasketches crate
+mod num_std_dev;
+mod resize;
+pub use self::num_std_dev::NumStdDev;
+pub use self::resize::ResizeFactor;
+
+// private to datasketches crate
+pub(crate) mod binomial_bounds;

datasketches/src/common/mod.rs

@@ -0,0 +1,53 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Standard deviation enums for confidence bounds
+//!
+//! This module provides types for specifying confidence levels when computing
+//! upper and lower bounds for sketch estimates.
+
+#[allow(clippy::excessive_precision)]
+const DELTA_OF_NUM_STD_DEVS: [f64; 4] = [
+    0.5000000000000000000, // = 0.5 (1 + erf(0))
+    0.1586553191586026479, // = 0.5 (1 + erf((-1/sqrt(2))))
+    0.0227502618904135701, // = 0.5 (1 + erf((-2/sqrt(2))))
+    0.0013498126861731796, // = 0.5 (1 + erf((-3/sqrt(2))))
+];
+
+/// Number of standard deviations for confidence bounds
+///
+/// This enum specifies the number of standard deviations to use when computing
+/// upper and lower bounds for cardinality estimates. Higher values provide wider
+/// confidence intervals with greater certainty that the true cardinality falls
+/// within the bounds.
+#[repr(u8)]
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum NumStdDev {
+    /// One standard deviation (\~68% confidence interval)
+    One = 1,
+    /// Two standard deviations (\~95% confidence interval)
+    Two = 2,
+    /// Three standard deviations (\~99.7% confidence interval)
+    Three = 3,
+}
+
+impl NumStdDev {
+    /// Returns the tail probability (delta) for this confidence level
+    pub const fn tail_probability(&self) -> f64 {
+        DELTA_OF_NUM_STD_DEVS[*self as usize]
+    }
+}

datasketches/src/common/num_std_dev.rs

@@ -36,7 +36,7 @@
 /// # Examples
 ///
 /// ```
-/// # use datasketches::ResizeFactor;
+/// # use datasketches::common::ResizeFactor;
 /// let factor = ResizeFactor::X4;
 /// assert_eq!(factor.value(), 4);
 /// assert_eq!(factor.lg_value(), 2);

datasketches/src/resize.rs datasketches/src/common/resize.rsdatasketches/src/resize.rs renamed to datasketches/src/common/resize.rs

@@ -91,6 +91,10 @@ impl Error {
 
 // Convenience constructors for deserialization errors
 impl Error {
+    pub(crate) fn invalid_argument(msg: impl Into<String>) -> Self {
+        Self::new(ErrorKind::InvalidArgument, msg)
+    }
+
     pub(crate) fn deserial(msg: impl Into<String>) -> Self {
         Self::new(ErrorKind::InvalidData, msg)
     }

datasketches/src/error.rs

@@ -23,8 +23,8 @@
 use super::aux_map::AuxMap;
 use crate::codec::SketchBytes;
 use crate::codec::SketchSlice;
+use crate::common::NumStdDev;
 use crate::error::Error;
-use crate::hll::NumStdDev;
 use crate::hll::estimator::HipEstimator;
 use crate::hll::get_slot;
 use crate::hll::get_value;

datasketches/src/hll/array4.rs

@@ -23,8 +23,8 @@
 
 use crate::codec::SketchBytes;
 use crate::codec::SketchSlice;
+use crate::common::NumStdDev;
 use crate::error::Error;
-use crate::hll::NumStdDev;
 use crate::hll::estimator::HipEstimator;
 use crate::hll::get_slot;
 use crate::hll::get_value;

datasketches/src/hll/array6.rs

@@ -22,8 +22,8 @@
 
 use crate::codec::SketchBytes;
 use crate::codec::SketchSlice;
+use crate::common::NumStdDev;
 use crate::error::Error;
-use crate::hll::NumStdDev;
 use crate::hll::estimator::HipEstimator;
 use crate::hll::get_slot;
 use crate::hll::get_value;

datasketches/src/hll/array8.rs

@@ -20,8 +20,8 @@
 //! Provides a simple array-based storage for coupons (hash values) with
 //! cubic interpolation-based cardinality estimation and confidence bounds.
 
+use crate::common::NumStdDev;
 use crate::hll::COUPON_RSE;
-use crate::hll::NumStdDev;
 use crate::hll::coupon_mapping::X_ARR;
 use crate::hll::coupon_mapping::Y_ARR;
 use crate::hll::cubic_interpolation::using_x_and_y_tables;

datasketches/src/hll/container.rs

@@ -22,6 +22,7 @@
 //! This is more accurate than the standard HLL estimator, especially for
 //! moderate cardinalities.
 
+use crate::common::NumStdDev;
 use crate::hll::composite_interpolation;
 use crate::hll::cubic_interpolation;
 use crate::hll::harmonic_numbers;
@@ -324,22 +325,6 @@ fn inv_pow2(value: u8) -> f64 {
     }
 }
 
-/// Number of standard deviations for confidence bounds
-///
-/// This enum specifies the number of standard deviations to use when computing
-/// upper and lower bounds for cardinality estimates. Higher values provide wider
-/// confidence intervals with greater certainty that the true cardinality falls
-/// within the bounds.
-#[repr(u8)]
-pub enum NumStdDev {
-    /// One standard deviation (\~68% confidence interval)
-    One = 1,
-    /// Two standard deviations (\~95% confidence interval)
-    Two = 2,
-    /// Three standard deviations (\~99.7% confidence interval)
-    Three = 3,
-}
-
 /// Get relative error for HLL estimates
 ///
 /// This matches the implementation in datasketches-cpp HllUtil.hpp and RelativeErrorTables.hpp