Merge pull request #27 from jmalkin/use_properties

API cleanup

Author: jmalkin

include/quantile_conditional.hpp

@@ -84,7 +84,7 @@ template<typename T, typename SK, typename std::enable_if<std::is_trivial<T>::va
 void add_vector_update(nb::class_<SK>& clazz) {
   clazz.def(
     "update",
-    [](SK& sk, nb::ndarray<T, nb::c_contig> items) {
+    [](SK& sk, nb::ndarray<T> items) {
       if (items.ndim() != 1) {
         throw std::invalid_argument("input data must have only one dimension. Found: "
           + std::to_string(items.ndim()));

src/count_wrapper.cpp

@@ -30,8 +30,14 @@ void bind_count_min_sketch(nb::module_ &m, const char* name) {
   using namespace datasketches;
 
   nb::class_<count_min_sketch<W>>(m, name)
-    .def(nb::init<uint8_t, uint32_t, uint64_t>(), nb::arg("num_hashes"), nb::arg("num_buckets"), nb::arg("seed")=DEFAULT_SEED)
-    .def(nb::init<const count_min_sketch<W>&>())
+    .def(nb::init<uint8_t, uint32_t, uint64_t>(), nb::arg("num_hashes"), nb::arg("num_buckets"), nb::arg("seed")=DEFAULT_SEED,
+         "Creates an instance of a CountMin sketch\n\n"
+         ":param num_hashes: Number of rows in the sketch\n:type num_hashes: int\n"
+         ":param num_buckets: Number of columns in the sketch\n:type num_buckets: int\n"
+         ":param seed: Hash seed to use\n:type seed: int, optional"
+         )
+         // using nun_hashes (rows), num_buckets (columns), and hash seed `seed`.)
+    .def("__copy__", [](const count_min_sketch<W>& sk){ return count_min_sketch<W>(sk); })
     .def_static("suggest_num_buckets", &count_min_sketch<W>::suggest_num_buckets, nb::arg("relative_error"),
                 "Suggests the number of buckets needed to achieve an accuracy within the provided "
                 "relative_error. For example, when relative_error = 0.05, the returned frequency estimates "
@@ -50,16 +56,16 @@ void bind_count_min_sketch(nb::module_ &m, const char* name) {
          "Produces a string summary of the sketch")
     .def("is_empty", &count_min_sketch<W>::is_empty,
          "Returns True if the sketch has seen no items, otherwise False")
-    .def("get_num_hashes", &count_min_sketch<W>::get_num_hashes,
-         "Returns the configured number of hashes for the sketch")
-    .def("get_num_buckets", &count_min_sketch<W>::get_num_buckets,
-         "Returns the configured number of buckets for the sketch")
-    .def("get_seed", &count_min_sketch<W>::get_seed,
-         "Returns the base hash seed for the sketch")
+    .def_prop_ro("num_hashes", &count_min_sketch<W>::get_num_hashes,
+         "The configured number of hashes for the sketch")
+    .def_prop_ro("num_buckets", &count_min_sketch<W>::get_num_buckets,
+         "The configured number of buckets for the sketch")
+    .def_prop_ro("seed", &count_min_sketch<W>::get_seed,
+         "The base hash seed for the sketch")
     .def("get_relative_error", &count_min_sketch<W>::get_relative_error,
          "Returns the maximum permissible error for any frequency estimate query")
-    .def("get_total_weight", &count_min_sketch<W>::get_total_weight,
-         "Returns the total weight currently inserted into the stream")
+    .def_prop_ro("total_weight", &count_min_sketch<W>::get_total_weight,
+         "The total weight currently inserted into the stream")
     .def("update", static_cast<void (count_min_sketch<W>::*)(int64_t, W)>(&count_min_sketch<W>::update), nb::arg("item"), nb::arg("weight")=1.0,
          "Updates the sketch with the given 64-bit integer value")
     .def("update", static_cast<void (count_min_sketch<W>::*)(const std::string&, W)>(&count_min_sketch<W>::update), nb::arg("item"), nb::arg("weight")=1.0,
@@ -73,9 +79,9 @@ void bind_count_min_sketch(nb::module_ &m, const char* name) {
     .def("get_upper_bound", static_cast<W (count_min_sketch<W>::*)(const std::string&) const>(&count_min_sketch<W>::get_upper_bound), nb::arg("item"),
          "Returns an upper bound on the estimate for the provided string")
     .def("get_lower_bound", static_cast<W (count_min_sketch<W>::*)(int64_t) const>(&count_min_sketch<W>::get_lower_bound), nb::arg("item"),
-         "Returns an lower bound on the estimate for the given 64-bit integer value")
+         "Returns a lower bound on the estimate for the given 64-bit integer value")
     .def("get_lower_bound", static_cast<W (count_min_sketch<W>::*)(const std::string&) const>(&count_min_sketch<W>::get_lower_bound), nb::arg("item"),
-         "Returns an lower bound on the estimate for the provided string")
+         "Returns a lower bound on the estimate for the provided string")
     .def("merge", &count_min_sketch<W>::merge, nb::arg("other"),
          "Merges the provided other sketch into this one")
     .def("get_serialized_size_bytes", &count_min_sketch<W>::get_serialized_size_bytes,

src/cpc_wrapper.cpp

@@ -31,8 +31,14 @@ void init_cpc(nb::module_ &m) {
   using namespace datasketches;
 
   nb::class_<cpc_sketch>(m, "cpc_sketch")
-    .def(nb::init<uint8_t, uint64_t>(), nb::arg("lg_k")=cpc_constants::DEFAULT_LG_K, nb::arg("seed")=DEFAULT_SEED)
-    .def(nb::init<const cpc_sketch&>())
+    .def(nb::init<uint8_t, uint64_t>(), nb::arg("lg_k")=cpc_constants::DEFAULT_LG_K, nb::arg("seed")=DEFAULT_SEED,
+         "Creates a new CPC sketch\n\n"
+         ":param lg_k: base 2 logarithm of the number of bins in the sketch\n"
+         ":type lg_k: int, optional\n"
+         ":param seed: seed value for the hash function\n"
+         ":type seed: int, optional"
+    )
+    .def("__copy__", [](const cpc_sketch& sk){ return cpc_sketch(sk); })
     .def("__str__", &cpc_sketch::to_string,
          "Produces a string summary of the sketch")
     .def("to_string", &cpc_sketch::to_string,
@@ -43,8 +49,8 @@ void init_cpc(nb::module_ &m) {
          "Updates the sketch with the given 64-bit floating point")
     .def<void (cpc_sketch::*)(const std::string&)>("update", &cpc_sketch::update, nb::arg("datum"),
          "Updates the sketch with the given string")
-    .def("get_lg_k", &cpc_sketch::get_lg_k,
-         "Returns configured lg_k of this sketch")
+    .def_prop_ro("lg_k", &cpc_sketch::get_lg_k,
+         "Configured lg_k of this sketch")
     .def("is_empty", &cpc_sketch::is_empty,
          "Returns True if the sketch is empty, otherwise False")
     .def("get_estimate", &cpc_sketch::get_estimate,
@@ -70,7 +76,6 @@ void init_cpc(nb::module_ &m) {
 
   nb::class_<cpc_union>(m, "cpc_union")
     .def(nb::init<uint8_t, uint64_t>(), nb::arg("lg_k"), nb::arg("seed")=DEFAULT_SEED)
-    .def(nb::init<const cpc_union&>())
     .def("update", (void (cpc_union::*)(const cpc_sketch&)) &cpc_union::update, nb::arg("sketch"),
          "Updates the union with the provided CPC sketch")
     .def("get_result", &cpc_union::get_result,

src/density_wrapper.cpp

@@ -42,21 +42,27 @@ void bind_density_sketch(nb::module_ &m, const char* name) {
         { K holder(kernel);
           new (sk) density_sketch<T, K>(k, dim, holder);
         },
-        nb::arg("k"), nb::arg("dim"), nb::arg("kernel"))
+        nb::arg("k"), nb::arg("dim"), nb::arg("kernel"),
+        "Creates a new density sketch\n\n"
+        ":param k: controls the size and error of the sketch\n:type k: int\n"
+        ":param dim: dimension of the input data\n:type dim: int\n"
+        ":param kernel: instance of a kernel\n:type kernel: KernelFunction\n"
+        )
+    .def("__copy__", [](const density_sketch<T,K>& sk){ return density_sketch<T,K>(sk); })
     .def("update", static_cast<void (density_sketch<T, K>::*)(const std::vector<T>&)>(&density_sketch<T, K>::update), nb::arg("vector"),
         "Updates the sketch with the given vector")
     .def("merge", static_cast<void (density_sketch<T, K>::*)(const density_sketch<T, K>&)>(&density_sketch<T, K>::merge), nb::arg("sketch"),
         "Merges the provided sketch into this one")
     .def("is_empty", &density_sketch<T, K>::is_empty,
         "Returns True if the sketch is empty, otherwise False")
-    .def("get_k", &density_sketch<T, K>::get_k,
-        "Returns the configured parameter k")
-    .def("get_dim", &density_sketch<T, K>::get_dim,
-        "Returns the configured parameter dim")
-    .def("get_n", &density_sketch<T, K>::get_n,
-        "Returns the length of the input stream")
-    .def("get_num_retained", &density_sketch<T, K>::get_num_retained,
-        "Returns the number of retained items (samples) in the sketch")
+    .def_prop_ro("k", &density_sketch<T, K>::get_k,
+        "The configured parameter k")
+    .def_prop_ro("dim", &density_sketch<T, K>::get_dim,
+        "The configured parameter dim")
+    .def_prop_ro("n", &density_sketch<T, K>::get_n,
+        "The length of the input stream")
+    .def_prop_ro("num_retained", &density_sketch<T, K>::get_num_retained,
+        "The number of retained items (samples) in the sketch")
     .def("is_estimation_mode", &density_sketch<T, K>::is_estimation_mode,
         "Returns True if the sketch is in estimation mode, otherwise False")
     .def("get_estimate", &density_sketch<T, K>::get_estimate, nb::arg("point"),
@@ -101,9 +107,12 @@ void init_density(nb::module_ &m) {
   prepare_numpy();
 
   // generic kernel function
-  nb::class_<kernel_function, KernelFunction>(m, "KernelFunction")
+  nb::class_<kernel_function, KernelFunction>(m, "KernelFunction",
+     "KernelFunction provicdes a generic base class from which user-defined kernels must inherit. \
+     The class contains only a __call__ method that must be overridden.")
     .def(nb::init())
-    .def("__call__", &kernel_function::operator(), nb::arg("a"), nb::arg("b"))
+    .def("__call__", &kernel_function::operator(), nb::arg("a"), nb::arg("b"),
+     "A method to evaluate a kernel with given inputs a and b.")
     ;
 
   // the old sketch names can almost be defined, but the kernel_function_holder won't work in init()

src/ebpps_wrapper.cpp

@@ -34,7 +34,11 @@ void bind_ebpps_sketch(nb::module_ &m, const char* name) {
   using namespace datasketches;
 
   nb::class_<ebpps_sketch<T>>(m, name)
-    .def(nb::init<uint32_t>(), nb::arg("k"))
+    .def(nb::init<uint32_t>(), nb::arg("k"),
+         "Creates a new EBPPS sketch instance\n\n"
+         ":param k: Maximum number of samples in the sketch\n:type k: int\n"
+         )
+    .def("__copy__", [](const ebpps_sketch<T>& sk){ return ebpps_sketch<T>(sk); })
     .def("__str__", &ebpps_sketch<T>::to_string,
          "Produces a string summary of the sketch")
     .def("to_string",
@@ -51,11 +55,11 @@ void bind_ebpps_sketch(nb::module_ &m, const char* name) {
     .def("merge", (void (ebpps_sketch<T>::*)(const ebpps_sketch<T>&)) &ebpps_sketch<T>::merge,
          nb::arg("sketch"), "Merges the sketch with the given sketch")
     .def_prop_ro("k", &ebpps_sketch<T>::get_k,
-         "Returns the sketch's maximum configured sample size")
+         "The sketch's maximum configured sample size")
     .def_prop_ro("n", &ebpps_sketch<T>::get_n,
-         "Returns the total stream length")         
+         "The total stream length")         
     .def_prop_ro("c", &ebpps_sketch<T>::get_c,
-         "Returns the expected number of samples returned upon a call to get_result() or the creation of an iterator. "
+         "The expected number of samples returned upon a call to get_result() or the creation of an iterator. "
          "The number is a floating point value, where the fractional portion represents the probability of including "
          "a \"partial item\" from the sample. The value C should be no larger than the sketch's configured value of k, "
          "although numerical precision limitations mean it may exceed k by double precision floating point error margins in certain cases.")

src/fi_wrapper.cpp

@@ -45,7 +45,13 @@ void bind_fi_sketch(nb::module_ &m, const char* name) {
   using namespace datasketches;
 
   auto fi_class = nb::class_<frequent_items_sketch<T, W, H, E>>(m, name)
-    .def(nb::init<uint8_t>(), nb::arg("lg_max_k"))
+    .def(nb::init<uint8_t>(), nb::arg("lg_max_k"),
+         "Creates an instance of the sketch\n\n"
+         ":param lg_max_k: base 2 logarithm of the maximum size of the internal hash map of the sketch. Maximum "
+         "capacity is 0.75 of this value, which is the maximum number of distinct items the sketch can contain.\n"
+         ":type lg_max_k: int\n"
+         )
+    .def("__copy__", [](const frequent_items_sketch<T, W, H, E>& sk){ return frequent_items_sketch<T,W,H,E>(sk); })
     .def("__str__", &frequent_items_sketch<T, W, H, E>::to_string, nb::arg("print_items")=false,
          "Produces a string summary of the sketch")
     .def("to_string", &frequent_items_sketch<T, W, H, E>::to_string, nb::arg("print_items")=false,
@@ -56,10 +62,10 @@ void bind_fi_sketch(nb::module_ &m, const char* name) {
          "Merges the given sketch into this one")
     .def("is_empty", &frequent_items_sketch<T, W, H, E>::is_empty,
          "Returns True if the sketch is empty, otherwise False")
-    .def("get_num_active_items", &frequent_items_sketch<T, W, H, E>::get_num_active_items,
-         "Returns the number of active items in the sketch")
-    .def("get_total_weight", &frequent_items_sketch<T, W, H, E>::get_total_weight,
-         "Returns the sum of the weights (frequencies) in the stream seen so far by the sketch")
+    .def_prop_ro("num_active_items", &frequent_items_sketch<T, W, H, E>::get_num_active_items,
+         "The number of active items in the sketch")
+    .def_prop_ro("total_weight", &frequent_items_sketch<T, W, H, E>::get_total_weight,
+         "The sum of the weights (frequencies) in the stream seen so far by the sketch")
     .def("get_estimate", &frequent_items_sketch<T, W, H, E>::get_estimate, nb::arg("item"),
          "Returns the estimate of the weight (frequency) of the given item.\n"
          "Note: The true frequency of a item would be the sum of the counts as a result of the "
@@ -68,8 +74,8 @@ void bind_fi_sketch(nb::module_ &m, const char* name) {
          "Returns the guaranteed lower bound weight (frequency) of the given item.")
     .def("get_upper_bound", &frequent_items_sketch<T, W, H, E>::get_upper_bound, nb::arg("item"),
          "Returns the guaranteed upper bound weight (frequency) of the given item.")
-    .def("get_sketch_epsilon", (double (frequent_items_sketch<T, W, H, E>::*)(void) const) &frequent_items_sketch<T, W, H, E>::get_epsilon,
-         "Returns the epsilon value used by the sketch to compute error")
+    .def_prop_ro("epsilon", (double (frequent_items_sketch<T, W, H, E>::*)(void) const) &frequent_items_sketch<T, W, H, E>::get_epsilon,
+         "The epsilon value used by the sketch to compute error")
     .def(
         "get_frequent_items",
         [](const frequent_items_sketch<T, W, H, E>& sk, frequent_items_error_type err_type, uint64_t threshold) {

src/hll_wrapper.cpp

@@ -34,17 +34,23 @@ void init_hll(nb::module_ &m) {
     .export_values();
 
   nb::class_<hll_sketch>(m, "hll_sketch")
-    .def(nb::init<uint8_t>(), nb::arg("lg_k"))
-    .def(nb::init<uint8_t, target_hll_type>(), nb::arg("lg_k"), nb::arg("tgt_type"))
-    .def(nb::init<uint8_t, target_hll_type, bool>(), nb::arg("lg_k"), nb::arg("tgt_type"), nb::arg("start_max_size")=false)
+    .def(nb::init<uint8_t, target_hll_type, bool>(), nb::arg("lg_k"), nb::arg("tgt_type")=HLL_8, nb::arg("start_max_size")=false,
+         "Constructs a new HLL sketch\n\n"
+         ":param lg_config_k: A full sketch can hold 2^lg_config_k rows. Must be between 7 and 21, inclusive,\n"
+         ":type lg_config_k: int\n"
+         ":param tgt_type: The HLL mode to use, if/when the sketch reaches estimation mode\n"
+         ":type tgt_type: tgt_hll_type\n"
+         ":param start_full_size: Indicates whether to start in HLL mode, keeping memory use constant (if HLL_6 or "
+         "HLL_8) at the cost of much higher initial memory use. Default (and recommended) is False.\n"
+         ":type start_full_size: bool"
+     )
     .def("__str__", (std::string (hll_sketch::*)(bool,bool,bool,bool) const) &hll_sketch::to_string,
-         nb::arg("summary")=true, nb::arg("detail")=false, nb::arg("aux_detail")=false, nb::arg("all")=false,
          "Produces a string summary of the sketch")
     .def("to_string", (std::string (hll_sketch::*)(bool,bool,bool,bool) const) &hll_sketch::to_string,
          nb::arg("summary")=true, nb::arg("detail")=false, nb::arg("aux_detail")=false, nb::arg("all")=false,
          "Produces a string summary of the sketch")
     .def_prop_ro("lg_config_k", &hll_sketch::get_lg_config_k, "Configured lg_k value for the sketch")
-    .def_prop_ro("tgt_type", &hll_sketch::get_target_type, "Returns the HLL type (4, 6, or 8) when in estimation mode")
+    .def_prop_ro("tgt_type", &hll_sketch::get_target_type, "The HLL type (4, 6, or 8) when in estimation mode")
     .def("get_estimate", &hll_sketch::get_estimate,
          "Estimate of the distinct count of the input stream")
     .def("get_lower_bound", &hll_sketch::get_lower_bound, nb::arg("num_std_devs"),
@@ -97,9 +103,12 @@ void init_hll(nb::module_ &m) {
     );
 
   nb::class_<hll_union>(m, "hll_union")
-    .def(nb::init<uint8_t>(), nb::arg("lg_max_k"))
+    .def(nb::init<uint8_t>(), nb::arg("lg_max_k"),
+         "Construct an hll_union object if the given size.\n\n"
+         ":param lg_max_k: The maximum size, in log2, of k. Must be between 7 and 21, inclusive.\n"
+         ":type lg_max_k: int"
+         )
     .def_prop_ro("lg_config_k", &hll_union::get_lg_config_k, "Configured lg_k value for the union")
-    .def_prop_ro("tgt_type", &hll_union::get_target_type, "Returns the HLL type (4, 6, or 8) when in estimation mode")
     .def("get_estimate", &hll_union::get_estimate,
          "Estimate of the distinct count of the input stream")
     .def("get_lower_bound", &hll_union::get_lower_bound, nb::arg("num_std_devs"),

src/kll_wrapper.cpp

@@ -37,24 +37,28 @@ void bind_kll_sketch(nb::module_ &m, const char* name) {
   using namespace datasketches;
 
   auto kll_class = nb::class_<kll_sketch<T, C>>(m, name)
-    .def(nb::init<uint16_t>(), nb::arg("k")=kll_constants::DEFAULT_K)
-    .def(nb::init<const kll_sketch<T, C>&>())
+    .def(nb::init<uint16_t>(), nb::arg("k")=kll_constants::DEFAULT_K,
+         "Creates a KLL sketch instance with the given value of k.\n\n"
+         ":param k: Controls the size/accuracy trade-off of the sketch. Default is 200.\n"
+         ":type k: int, optional"
+         )
+    .def("__copy__", [](const kll_sketch<T, C>& sk){ return kll_sketch<T, C>(sk); })
     .def("update", static_cast<void (kll_sketch<T, C>::*)(const T&)>(&kll_sketch<T, C>::update), nb::arg("item"),
         "Updates the sketch with the given value")
     .def("merge", (void (kll_sketch<T, C>::*)(const kll_sketch<T, C>&)) &kll_sketch<T, C>::merge, nb::arg("sketch"),
         "Merges the provided sketch into this one")
-    .def("__str__", &kll_sketch<T, C>::to_string, nb::arg("print_levels")=false, nb::arg("print_items")=false,
+    .def("__str__", &kll_sketch<T, C>::to_string,
         "Produces a string summary of the sketch")
     .def("to_string", &kll_sketch<T, C>::to_string, nb::arg("print_levels")=false, nb::arg("print_items")=false,
         "Produces a string summary of the sketch")
     .def("is_empty", &kll_sketch<T, C>::is_empty,
         "Returns True if the sketch is empty, otherwise False")
-    .def("get_k", &kll_sketch<T, C>::get_k,
-        "Returns the configured parameter k")
-    .def("get_n", &kll_sketch<T, C>::get_n,
-        "Returns the length of the input stream")
-    .def("get_num_retained", &kll_sketch<T, C>::get_num_retained,
-        "Returns the number of retained items (samples) in the sketch")
+    .def_prop_ro("k", &kll_sketch<T, C>::get_k,
+        "The configured parameter k")
+    .def_prop_ro("n", &kll_sketch<T, C>::get_n,
+        "The length of the input stream")
+    .def_prop_ro("num_retained", &kll_sketch<T, C>::get_num_retained,
+        "The number of retained items (samples) in the sketch")
     .def("is_estimation_mode", &kll_sketch<T, C>::is_estimation_mode,
         "Returns True if the sketch is in estimation mode, otherwise False")
     .def("get_min_value", &kll_sketch<T, C>::get_min_item,