You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@datasketches.apache.org by GitBox <gi...@apache.org> on 2020/04/16 21:30:36 UTC
[GitHub] [incubator-datasketches-cpp] AlexanderSaydakov opened a new pull
request #109: API and docs
AlexanderSaydakov opened a new pull request #109: API and docs
URL: https://github.com/apache/incubator-datasketches-cpp/pull/109
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datasketches.apache.org
For additional commands, e-mail: commits-help@datasketches.apache.org
[GitHub] [incubator-datasketches-cpp] jmalkin commented on a change in pull
request #109: API and docs
Posted by GitBox <gi...@apache.org>.
jmalkin commented on a change in pull request #109: API and docs
URL: https://github.com/apache/incubator-datasketches-cpp/pull/109#discussion_r409907568
##########
File path: kll/include/kll_sketch.hpp
##########
@@ -190,23 +287,123 @@ class kll_sketch {
*/
std::vector<T, A> get_quantiles(size_t num) const;
+ /**
+ * Returns an approximation to the normalized (fractional) rank of the given value from 0 to 1,
+ * inclusive.
+ *
+ * <p>The resulting approximation has a probabilistic guarantee that can be obtained from the
+ * get_normalized_rank_error(false) function.
+ *
+ * <p>If the sketch is empty this returns NaN.
+ *
+ * @param value to be ranked
+ * @return an approximate rank of the given value
+ */
double get_rank(const T& value) const;
+
+ /**
+ * Returns an approximation to the Probability Mass Function (PMF) of the input stream
+ * given a set of split points (values).
+ *
+ * <p>The resulting approximations have a probabilistic guarantee that can be obtained from the
+ * get_normalized_rank_error(true) function.
+ *
+ * <p>If the sketch is empty this returns an empty vector.
+ *
+ * @param split_points an array of <i>m</i> unique, monotonically increasing float values
+ * that divide the real number line into <i>m+1</i> consecutive disjoint intervals.
+ * The definition of an "interval" is inclusive of the left split point (or minimum value) and
+ * exclusive of the right split point, with the exception that the last interval will include
+ * the maximum value.
+ * It is not necessary to include either the min or max values in these split points.
+ *
+ * @return an array of m+1 doubles each of which is an approximation
+ * to the fraction of the input stream values (the mass) that fall into one of those intervals.
+ * The definition of an "interval" is inclusive of the left split point and exclusive of the right
Review comment:
it should be fine, but this definition is given right above, too
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datasketches.apache.org
For additional commands, e-mail: commits-help@datasketches.apache.org
[GitHub] [incubator-datasketches-cpp] jmalkin commented on a change in pull
request #109: API and docs
Posted by GitBox <gi...@apache.org>.
jmalkin commented on a change in pull request #109: API and docs
URL: https://github.com/apache/incubator-datasketches-cpp/pull/109#discussion_r410325049
##########
File path: theta/include/theta_sketch.hpp
##########
@@ -53,36 +53,124 @@ class theta_sketch_alloc {
static const uint64_t MAX_THETA = LLONG_MAX; // signed max for compatibility with Java
static const uint8_t SERIAL_VERSION = 3;
- theta_sketch_alloc(bool is_empty, uint64_t theta);
- theta_sketch_alloc(const theta_sketch_alloc<A>& other);
- theta_sketch_alloc(theta_sketch_alloc<A>&& other) noexcept;
virtual ~theta_sketch_alloc();
- theta_sketch_alloc<A>& operator=(const theta_sketch_alloc<A>& other);
- theta_sketch_alloc<A>& operator=(theta_sketch_alloc<A>&& other);
-
+ /**
+ * @return true if this sketch represents an empty set (not the same as no retained entries!)
+ */
bool is_empty() const;
+
+ /**
+ * @return estimate of the distinct count of the input stream
+ */
double get_estimate() const;
+
+ /**
+ * Returns the approximate lower error bound given a number of standard deviations.
+ * This parameter is similar to the number of standard deviations of the normal distribution
+ * and corresponds to approximately 67%, 95% and 99% confidence intervals.
+ * @param num_std_devs number of Standard Deviations (1, 2 or 3)
+ * @return the lower bound
+ */
double get_lower_bound(uint8_t num_std_devs) const;
+
+ /**
+ * Returns the approximate upper error bound given a number of standard deviations.
+ * This parameter is similar to the number of standard deviations of the normal distribution
+ * and corresponds to approximately 67%, 95% and 99% confidence intervals.
+ * @param num_std_devs number of Standard Deviations (1, 2 or 3)
+ * @return the upper bound
+ */
double get_upper_bound(uint8_t num_std_devs) const;
+
+ /**
+ * @return true if the sketch is in estimation mode (as opposed to exact mode)
+ */
bool is_estimation_mode() const;
+
+ /**
+ * @return theta as a fraction from 0 to 1 (effective sampling rate)
+ */
double get_theta() const;
+
+ /**
+ * @return theta as a positive integer between 0 and LLONG_MAX
+ */
uint64_t get_theta64() const;
+ /**
+ * @return the number of retained entries in the sketch
+ */
virtual uint32_t get_num_retained() const = 0;
+
virtual uint16_t get_seed_hash() const = 0;
+
+ /**
+ * @return true if retained entries are ordered
+ */
virtual bool is_ordered() const = 0;
+
+ /**
+ * Writes a human-readable summary of this sketch to a given stream
+ * @param os output stream
+ * @param print_items if true include the list of items retained by the sketch
+ */
virtual void to_stream(std::ostream& os, bool print_items = false) const = 0;
+
+ /**
+ * This method serializes the sketch into a given stream in a binary form
+ * @param os output stream
+ */
virtual void serialize(std::ostream& os) const = 0;
- typedef vector_u8<A> vector_bytes; // alias for users
+
+ // This is a convenience alias for users
+ // The type returned by the following serialize method
+ typedef vector_u8<A> vector_bytes;
+
+ /**
+ * This method serializes the sketch as a vector of bytes.
+ * An optional header can be reserved in front of the sketch.
+ * It is an uninitialized space of a given size.
+ * This header is used in Datasketches PostgreSQL extension.
+ * @param header_size_bytes space to reserve in front of the sketch
+ */
virtual vector_bytes serialize(unsigned header_size_bytes = 0) const = 0;
+ // This is a convenience alias for users
+ // The type returned by the following deserialize methods
+ // It is not possible to return instances of an abstract type, so this has to be a pointer
typedef std::unique_ptr<theta_sketch_alloc<A>, std::function<void(theta_sketch_alloc<A>*)>> unique_ptr;
Review comment:
nevermind, this is a typedef within the class so it's fine.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datasketches.apache.org
For additional commands, e-mail: commits-help@datasketches.apache.org
[GitHub] [incubator-datasketches-cpp] AlexanderSaydakov merged pull request
#109: API and docs
Posted by GitBox <gi...@apache.org>.
AlexanderSaydakov merged pull request #109: API and docs
URL: https://github.com/apache/incubator-datasketches-cpp/pull/109
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datasketches.apache.org
For additional commands, e-mail: commits-help@datasketches.apache.org
[GitHub] [incubator-datasketches-cpp] jmalkin commented on a change in pull
request #109: API and docs
Posted by GitBox <gi...@apache.org>.
jmalkin commented on a change in pull request #109: API and docs
URL: https://github.com/apache/incubator-datasketches-cpp/pull/109#discussion_r410005330
##########
File path: theta/include/theta_sketch.hpp
##########
@@ -53,36 +53,124 @@ class theta_sketch_alloc {
static const uint64_t MAX_THETA = LLONG_MAX; // signed max for compatibility with Java
static const uint8_t SERIAL_VERSION = 3;
- theta_sketch_alloc(bool is_empty, uint64_t theta);
- theta_sketch_alloc(const theta_sketch_alloc<A>& other);
- theta_sketch_alloc(theta_sketch_alloc<A>&& other) noexcept;
virtual ~theta_sketch_alloc();
- theta_sketch_alloc<A>& operator=(const theta_sketch_alloc<A>& other);
- theta_sketch_alloc<A>& operator=(theta_sketch_alloc<A>&& other);
-
+ /**
+ * @return true if this sketch represents an empty set (not the same as no retained entries!)
+ */
bool is_empty() const;
+
+ /**
+ * @return estimate of the distinct count of the input stream
+ */
double get_estimate() const;
+
+ /**
+ * Returns the approximate lower error bound given a number of standard deviations.
+ * This parameter is similar to the number of standard deviations of the normal distribution
+ * and corresponds to approximately 67%, 95% and 99% confidence intervals.
+ * @param num_std_devs number of Standard Deviations (1, 2 or 3)
+ * @return the lower bound
+ */
double get_lower_bound(uint8_t num_std_devs) const;
+
+ /**
+ * Returns the approximate upper error bound given a number of standard deviations.
+ * This parameter is similar to the number of standard deviations of the normal distribution
+ * and corresponds to approximately 67%, 95% and 99% confidence intervals.
+ * @param num_std_devs number of Standard Deviations (1, 2 or 3)
+ * @return the upper bound
+ */
double get_upper_bound(uint8_t num_std_devs) const;
+
+ /**
+ * @return true if the sketch is in estimation mode (as opposed to exact mode)
+ */
bool is_estimation_mode() const;
+
+ /**
+ * @return theta as a fraction from 0 to 1 (effective sampling rate)
+ */
double get_theta() const;
+
+ /**
+ * @return theta as a positive integer between 0 and LLONG_MAX
+ */
uint64_t get_theta64() const;
+ /**
+ * @return the number of retained entries in the sketch
+ */
virtual uint32_t get_num_retained() const = 0;
+
virtual uint16_t get_seed_hash() const = 0;
+
+ /**
+ * @return true if retained entries are ordered
+ */
virtual bool is_ordered() const = 0;
+
+ /**
+ * Writes a human-readable summary of this sketch to a given stream
+ * @param os output stream
+ * @param print_items if true include the list of items retained by the sketch
+ */
virtual void to_stream(std::ostream& os, bool print_items = false) const = 0;
+
+ /**
+ * This method serializes the sketch into a given stream in a binary form
+ * @param os output stream
+ */
virtual void serialize(std::ostream& os) const = 0;
- typedef vector_u8<A> vector_bytes; // alias for users
+
+ // This is a convenience alias for users
+ // The type returned by the following serialize method
+ typedef vector_u8<A> vector_bytes;
+
+ /**
+ * This method serializes the sketch as a vector of bytes.
+ * An optional header can be reserved in front of the sketch.
+ * It is an uninitialized space of a given size.
+ * This header is used in Datasketches PostgreSQL extension.
+ * @param header_size_bytes space to reserve in front of the sketch
+ */
virtual vector_bytes serialize(unsigned header_size_bytes = 0) const = 0;
+ // This is a convenience alias for users
+ // The type returned by the following deserialize methods
+ // It is not possible to return instances of an abstract type, so this has to be a pointer
typedef std::unique_ptr<theta_sketch_alloc<A>, std::function<void(theta_sketch_alloc<A>*)>> unique_ptr;
Review comment:
hadn't looked at this closely before.
is this too generic a name? we can only have 1 sketch in the library use it, otherwise another app that uses multiple sketch types could run into issues.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datasketches.apache.org
For additional commands, e-mail: commits-help@datasketches.apache.org