Struct CompactTupleSketch

Source

pub struct CompactTupleSketch<S: TupleSummary> { /* private fields */ }

Expand description

An immutable snapshot of a generic Tuple sketch, produced by TupleSketch::compact or by any set operation’s result.

Serialization is not part of this version; it is the subject of a follow-up design.

Implementations§

Source §

impl<S: TupleSummary> CompactTupleSketch<S>

Source

pub fn get_estimate(&self) -> f64

Returns the current estimate of the number of distinct keys.

Examples found in repository ?

examples/tuple_generic.rs (line 97)

63fn main() {
64    let mut january: TupleSketch<Activity> = TupleSketchBuilder::new().lg_k(12).build().unwrap();
65    for user in 0..10_000u64 {
66        january.update_u64(
67            user,
68            &Event {
69                revenue_cents: 250 + (user % 100),
70                country: if user % 2 == 0 { "GB" } else { "US" },
71            },
72        );
73    }
74
75    let mut february: TupleSketch<Activity> = TupleSketchBuilder::new().lg_k(12).build().unwrap();
76    for user in 5_000..15_000u64 {
77        february.update_u64(
78            user,
79            &Event {
80                revenue_cents: 400,
81                country: "US",
82            },
83        );
84    }
85
86    println!("January unique users:  {:.0}", january.get_estimate());
87    println!("February unique users: {:.0}", february.get_estimate());
88
89    // Union: everyone who appeared in either month, with their activity merged.
90    let mut union = TupleUnionBuilder::<Activity>::new()
91        .lg_k(12)
92        .build()
93        .unwrap();
94    union.update(&january);
95    union.update(&february);
96    let combined = union.get_result(true);
97    println!("Users across both months: {:.0}", combined.get_estimate());
98
99    // Per-entry summaries are the point of a Tuple sketch. Scale the retained
100    // sample back up by 1/theta to estimate population totals.
101    let retained_revenue: u64 = combined.entries().map(|(_, a)| a.revenue_cents).sum();
102    let biggest_order = combined
103        .entries()
104        .map(|(_, a)| a.largest_order_cents)
105        .max()
106        .unwrap_or(0);
107    println!(
108        "Estimated total revenue: {:.2} (from {} retained entries, theta = {:.4})",
109        (retained_revenue as f64 / combined.get_theta()) / 100.0,
110        combined.get_num_retained(),
111        combined.get_theta()
112    );
113    println!(
114        "Largest single order seen: {:.2}",
115        biggest_order as f64 / 100.0
116    );
117
118    // Intersection: users active in both months.
119    let mut intersection = TupleIntersection::<Activity>::new();
120    intersection.update(&january);
121    intersection.update(&february);
122    match intersection.get_result(true) {
123        Ok(returning) => {
124            println!("Returning users: {:.0}", returning.get_estimate());
125            // `intersection_combine`'s `min` semantics at work: a returning
126            // user's sessions/countries reflect only what showed up in BOTH
127            // months, not the union of the two.
128            if let Some((_, activity)) = returning.entries().next() {
129                println!(
130                    "  e.g. one returning user: {} session(s), countries seen in both months: {:?}",
131                    activity.sessions, activity.countries
132                );
133            }
134        }
135        Err(e) => println!("No intersection result: {e}"),
136    }
137
138    // A-not-b: users who churned after January.
139    let churned = TupleAnotB::<Activity>::new().compute(&january, &february, true);
140    println!("Churned after January: {:.0}", churned.get_estimate());
141
142    // Jaccard similarity of the two months' audiences.
143    let similarity = tuple_jaccard_similarity(&january, &february);
144    println!(
145        "Audience overlap (Jaccard): {:.3} (range [{:.3}, {:.3}])",
146        similarity.estimate, similarity.lower_bound, similarity.upper_bound
147    );
148}

Source

pub fn get_lower_bound(&self, num_std_dev: u8) -> Result<f64, SketchError>

Returns the lower bound of the confidence interval around Self::get_estimate, for num_std_dev of 1, 2, or 3.

Source

pub fn get_upper_bound(&self, num_std_dev: u8) -> Result<f64, SketchError>

Returns the upper bound of the confidence interval around Self::get_estimate. See Self::get_lower_bound.

Source

pub fn is_empty(&self) -> bool

Returns true if this sketch represents an empty set.

Source

pub fn is_estimation_mode(&self) -> bool

Returns true if the estimate is a statistical estimate rather than an exact count.

Source

pub fn is_ordered(&self) -> bool

Returns true if retained entries are sorted by hash value.

Source

pub fn get_theta(&self) -> f64

Returns the current theta threshold.

Examples found in repository ?

examples/tuple_generic.rs (line 109)

63fn main() {
64    let mut january: TupleSketch<Activity> = TupleSketchBuilder::new().lg_k(12).build().unwrap();
65    for user in 0..10_000u64 {
66        january.update_u64(
67            user,
68            &Event {
69                revenue_cents: 250 + (user % 100),
70                country: if user % 2 == 0 { "GB" } else { "US" },
71            },
72        );
73    }
74
75    let mut february: TupleSketch<Activity> = TupleSketchBuilder::new().lg_k(12).build().unwrap();
76    for user in 5_000..15_000u64 {
77        february.update_u64(
78            user,
79            &Event {
80                revenue_cents: 400,
81                country: "US",
82            },
83        );
84    }
85
86    println!("January unique users:  {:.0}", january.get_estimate());
87    println!("February unique users: {:.0}", february.get_estimate());
88
89    // Union: everyone who appeared in either month, with their activity merged.
90    let mut union = TupleUnionBuilder::<Activity>::new()
91        .lg_k(12)
92        .build()
93        .unwrap();
94    union.update(&january);
95    union.update(&february);
96    let combined = union.get_result(true);
97    println!("Users across both months: {:.0}", combined.get_estimate());
98
99    // Per-entry summaries are the point of a Tuple sketch. Scale the retained
100    // sample back up by 1/theta to estimate population totals.
101    let retained_revenue: u64 = combined.entries().map(|(_, a)| a.revenue_cents).sum();
102    let biggest_order = combined
103        .entries()
104        .map(|(_, a)| a.largest_order_cents)
105        .max()
106        .unwrap_or(0);
107    println!(
108        "Estimated total revenue: {:.2} (from {} retained entries, theta = {:.4})",
109        (retained_revenue as f64 / combined.get_theta()) / 100.0,
110        combined.get_num_retained(),
111        combined.get_theta()
112    );
113    println!(
114        "Largest single order seen: {:.2}",
115        biggest_order as f64 / 100.0
116    );
117
118    // Intersection: users active in both months.
119    let mut intersection = TupleIntersection::<Activity>::new();
120    intersection.update(&january);
121    intersection.update(&february);
122    match intersection.get_result(true) {
123        Ok(returning) => {
124            println!("Returning users: {:.0}", returning.get_estimate());
125            // `intersection_combine`'s `min` semantics at work: a returning
126            // user's sessions/countries reflect only what showed up in BOTH
127            // months, not the union of the two.
128            if let Some((_, activity)) = returning.entries().next() {
129                println!(
130                    "  e.g. one returning user: {} session(s), countries seen in both months: {:?}",
131                    activity.sessions, activity.countries
132                );
133            }
134        }
135        Err(e) => println!("No intersection result: {e}"),
136    }
137
138    // A-not-b: users who churned after January.
139    let churned = TupleAnotB::<Activity>::new().compute(&january, &february, true);
140    println!("Churned after January: {:.0}", churned.get_estimate());
141
142    // Jaccard similarity of the two months' audiences.
143    let similarity = tuple_jaccard_similarity(&january, &february);
144    println!(
145        "Audience overlap (Jaccard): {:.3} (range [{:.3}, {:.3}])",
146        similarity.estimate, similarity.lower_bound, similarity.upper_bound
147    );
148}

Source

pub fn get_num_retained(&self) -> u32

Returns the number of retained entries.

Examples found in repository ?

examples/tuple_generic.rs (line 110)

63fn main() {
64    let mut january: TupleSketch<Activity> = TupleSketchBuilder::new().lg_k(12).build().unwrap();
65    for user in 0..10_000u64 {
66        january.update_u64(
67            user,
68            &Event {
69                revenue_cents: 250 + (user % 100),
70                country: if user % 2 == 0 { "GB" } else { "US" },
71            },
72        );
73    }
74
75    let mut february: TupleSketch<Activity> = TupleSketchBuilder::new().lg_k(12).build().unwrap();
76    for user in 5_000..15_000u64 {
77        february.update_u64(
78            user,
79            &Event {
80                revenue_cents: 400,
81                country: "US",
82            },
83        );
84    }
85
86    println!("January unique users:  {:.0}", january.get_estimate());
87    println!("February unique users: {:.0}", february.get_estimate());
88
89    // Union: everyone who appeared in either month, with their activity merged.
90    let mut union = TupleUnionBuilder::<Activity>::new()
91        .lg_k(12)
92        .build()
93        .unwrap();
94    union.update(&january);
95    union.update(&february);
96    let combined = union.get_result(true);
97    println!("Users across both months: {:.0}", combined.get_estimate());
98
99    // Per-entry summaries are the point of a Tuple sketch. Scale the retained
100    // sample back up by 1/theta to estimate population totals.
101    let retained_revenue: u64 = combined.entries().map(|(_, a)| a.revenue_cents).sum();
102    let biggest_order = combined
103        .entries()
104        .map(|(_, a)| a.largest_order_cents)
105        .max()
106        .unwrap_or(0);
107    println!(
108        "Estimated total revenue: {:.2} (from {} retained entries, theta = {:.4})",
109        (retained_revenue as f64 / combined.get_theta()) / 100.0,
110        combined.get_num_retained(),
111        combined.get_theta()
112    );
113    println!(
114        "Largest single order seen: {:.2}",
115        biggest_order as f64 / 100.0
116    );
117
118    // Intersection: users active in both months.
119    let mut intersection = TupleIntersection::<Activity>::new();
120    intersection.update(&january);
121    intersection.update(&february);
122    match intersection.get_result(true) {
123        Ok(returning) => {
124            println!("Returning users: {:.0}", returning.get_estimate());
125            // `intersection_combine`'s `min` semantics at work: a returning
126            // user's sessions/countries reflect only what showed up in BOTH
127            // months, not the union of the two.
128            if let Some((_, activity)) = returning.entries().next() {
129                println!(
130                    "  e.g. one returning user: {} session(s), countries seen in both months: {:?}",
131                    activity.sessions, activity.countries
132                );
133            }
134        }
135        Err(e) => println!("No intersection result: {e}"),
136    }
137
138    // A-not-b: users who churned after January.
139    let churned = TupleAnotB::<Activity>::new().compute(&january, &february, true);
140    println!("Churned after January: {:.0}", churned.get_estimate());
141
142    // Jaccard similarity of the two months' audiences.
143    let similarity = tuple_jaccard_similarity(&january, &february);
144    println!(
145        "Audience overlap (Jaccard): {:.3} (range [{:.3}, {:.3}])",
146        similarity.estimate, similarity.lower_bound, similarity.upper_bound
147    );
148}

Source

pub fn entries(&self) -> impl Iterator<Item = (u64, S)> + '_

Iterates the retained entries as (hash, summary) pairs.

Each summary is cloned out of C++, so the items are owned. Ordered by hash if Self::is_ordered is true.

Examples found in repository ?

examples/tuple_generic.rs (line 101)

63fn main() {
64    let mut january: TupleSketch<Activity> = TupleSketchBuilder::new().lg_k(12).build().unwrap();
65    for user in 0..10_000u64 {
66        january.update_u64(
67            user,
68            &Event {
69                revenue_cents: 250 + (user % 100),
70                country: if user % 2 == 0 { "GB" } else { "US" },
71            },
72        );
73    }
74
75    let mut february: TupleSketch<Activity> = TupleSketchBuilder::new().lg_k(12).build().unwrap();
76    for user in 5_000..15_000u64 {
77        february.update_u64(
78            user,
79            &Event {
80                revenue_cents: 400,
81                country: "US",
82            },
83        );
84    }
85
86    println!("January unique users:  {:.0}", january.get_estimate());
87    println!("February unique users: {:.0}", february.get_estimate());
88
89    // Union: everyone who appeared in either month, with their activity merged.
90    let mut union = TupleUnionBuilder::<Activity>::new()
91        .lg_k(12)
92        .build()
93        .unwrap();
94    union.update(&january);
95    union.update(&february);
96    let combined = union.get_result(true);
97    println!("Users across both months: {:.0}", combined.get_estimate());
98
99    // Per-entry summaries are the point of a Tuple sketch. Scale the retained
100    // sample back up by 1/theta to estimate population totals.
101    let retained_revenue: u64 = combined.entries().map(|(_, a)| a.revenue_cents).sum();
102    let biggest_order = combined
103        .entries()
104        .map(|(_, a)| a.largest_order_cents)
105        .max()
106        .unwrap_or(0);
107    println!(
108        "Estimated total revenue: {:.2} (from {} retained entries, theta = {:.4})",
109        (retained_revenue as f64 / combined.get_theta()) / 100.0,
110        combined.get_num_retained(),
111        combined.get_theta()
112    );
113    println!(
114        "Largest single order seen: {:.2}",
115        biggest_order as f64 / 100.0
116    );
117
118    // Intersection: users active in both months.
119    let mut intersection = TupleIntersection::<Activity>::new();
120    intersection.update(&january);
121    intersection.update(&february);
122    match intersection.get_result(true) {
123        Ok(returning) => {
124            println!("Returning users: {:.0}", returning.get_estimate());
125            // `intersection_combine`'s `min` semantics at work: a returning
126            // user's sessions/countries reflect only what showed up in BOTH
127            // months, not the union of the two.
128            if let Some((_, activity)) = returning.entries().next() {
129                println!(
130                    "  e.g. one returning user: {} session(s), countries seen in both months: {:?}",
131                    activity.sessions, activity.countries
132                );
133            }
134        }
135        Err(e) => println!("No intersection result: {e}"),
136    }
137
138    // A-not-b: users who churned after January.
139    let churned = TupleAnotB::<Activity>::new().compute(&january, &february, true);
140    println!("Churned after January: {:.0}", churned.get_estimate());
141
142    // Jaccard similarity of the two months' audiences.
143    let similarity = tuple_jaccard_similarity(&january, &february);
144    println!(
145        "Audience overlap (Jaccard): {:.3} (range [{:.3}, {:.3}])",
146        similarity.estimate, similarity.lower_bound, similarity.upper_bound
147    );
148}