Struct TupleIntersection 

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

Computes the intersection of generic Tuple sketches fed via Self::update. Summaries of keys present in every input are merged with TupleSummary::intersection_combine; a key present in only some of the inputs is dropped and its summary never reaches the callback.

No builder: upstream’s type has a plain constructor, matching ArrayOfDoublesIntersection.

A fresh intersection is the infinite “universe”, not the empty set — see Self::get_result.

Implementations

impl<S: TupleSummary> TupleIntersection<S>

pub fn new() -> Self

Creates an intersection with no result yet — call Self::update at least once before Self::get_result.

Examples found in repository

examples/tuple_generic.rs (line 119)

fn main() {
    let mut january: TupleSketch<Activity> = TupleSketchBuilder::new().lg_k(12).build().unwrap();
    for user in 0..10_000u64 {
        january.update_u64(
            user,
            &Event {
                revenue_cents: 250 + (user % 100),
                country: if user % 2 == 0 { "GB" } else { "US" },
            },
        );
    }

    let mut february: TupleSketch<Activity> = TupleSketchBuilder::new().lg_k(12).build().unwrap();
    for user in 5_000..15_000u64 {
        february.update_u64(
            user,
            &Event {
                revenue_cents: 400,
                country: "US",
            },
        );
    }

    println!("January unique users:  {:.0}", january.get_estimate());
    println!("February unique users: {:.0}", february.get_estimate());

    // Union: everyone who appeared in either month, with their activity merged.
    let mut union = TupleUnionBuilder::<Activity>::new()
        .lg_k(12)
        .build()
        .unwrap();
    union.update(&january);
    union.update(&february);
    let combined = union.get_result(true);
    println!("Users across both months: {:.0}", combined.get_estimate());

    // Per-entry summaries are the point of a Tuple sketch. Scale the retained
    // sample back up by 1/theta to estimate population totals.
    let retained_revenue: u64 = combined.entries().map(|(_, a)| a.revenue_cents).sum();
    let biggest_order = combined
        .entries()
        .map(|(_, a)| a.largest_order_cents)
        .max()
        .unwrap_or(0);
    println!(
        "Estimated total revenue: {:.2} (from {} retained entries, theta = {:.4})",
        (retained_revenue as f64 / combined.get_theta()) / 100.0,
        combined.get_num_retained(),
        combined.get_theta()
    );
    println!(
        "Largest single order seen: {:.2}",
        biggest_order as f64 / 100.0
    );

    // Intersection: users active in both months.
    let mut intersection = TupleIntersection::<Activity>::new();
    intersection.update(&january);
    intersection.update(&february);
    match intersection.get_result(true) {
        Ok(returning) => {
            println!("Returning users: {:.0}", returning.get_estimate());
            // `intersection_combine`'s `min` semantics at work: a returning
            // user's sessions/countries reflect only what showed up in BOTH
            // months, not the union of the two.
            if let Some((_, activity)) = returning.entries().next() {
                println!(
                    "  e.g. one returning user: {} session(s), countries seen in both months: {:?}",
                    activity.sessions, activity.countries
                );
            }
        }
        Err(e) => println!("No intersection result: {e}"),
    }

    // A-not-b: users who churned after January.
    let churned = TupleAnotB::<Activity>::new().compute(&january, &february, true);
    println!("Churned after January: {:.0}", churned.get_estimate());

    // Jaccard similarity of the two months' audiences.
    let similarity = tuple_jaccard_similarity(&january, &february);
    println!(
        "Audience overlap (Jaccard): {:.3} (range [{:.3}, {:.3}])",
        similarity.estimate, similarity.lower_bound, similarity.upper_bound
    );
}

pub fn update(&mut self, input: &impl TupleInput<S>)

Narrows the running result to also require membership in input.

Infallible: unlike ArrayOfDoubles there is no num_values to agree on — the type system already guarantees both operands carry S.

Examples found in repository

examples/tuple_generic.rs (line 120)

fn main() {
    let mut january: TupleSketch<Activity> = TupleSketchBuilder::new().lg_k(12).build().unwrap();
    for user in 0..10_000u64 {
        january.update_u64(
            user,
            &Event {
                revenue_cents: 250 + (user % 100),
                country: if user % 2 == 0 { "GB" } else { "US" },
            },
        );
    }

    let mut february: TupleSketch<Activity> = TupleSketchBuilder::new().lg_k(12).build().unwrap();
    for user in 5_000..15_000u64 {
        february.update_u64(
            user,
            &Event {
                revenue_cents: 400,
                country: "US",
            },
        );
    }

    println!("January unique users:  {:.0}", january.get_estimate());
    println!("February unique users: {:.0}", february.get_estimate());

    // Union: everyone who appeared in either month, with their activity merged.
    let mut union = TupleUnionBuilder::<Activity>::new()
        .lg_k(12)
        .build()
        .unwrap();
    union.update(&january);
    union.update(&february);
    let combined = union.get_result(true);
    println!("Users across both months: {:.0}", combined.get_estimate());

    // Per-entry summaries are the point of a Tuple sketch. Scale the retained
    // sample back up by 1/theta to estimate population totals.
    let retained_revenue: u64 = combined.entries().map(|(_, a)| a.revenue_cents).sum();
    let biggest_order = combined
        .entries()
        .map(|(_, a)| a.largest_order_cents)
        .max()
        .unwrap_or(0);
    println!(
        "Estimated total revenue: {:.2} (from {} retained entries, theta = {:.4})",
        (retained_revenue as f64 / combined.get_theta()) / 100.0,
        combined.get_num_retained(),
        combined.get_theta()
    );
    println!(
        "Largest single order seen: {:.2}",
        biggest_order as f64 / 100.0
    );

    // Intersection: users active in both months.
    let mut intersection = TupleIntersection::<Activity>::new();
    intersection.update(&january);
    intersection.update(&february);
    match intersection.get_result(true) {
        Ok(returning) => {
            println!("Returning users: {:.0}", returning.get_estimate());
            // `intersection_combine`'s `min` semantics at work: a returning
            // user's sessions/countries reflect only what showed up in BOTH
            // months, not the union of the two.
            if let Some((_, activity)) = returning.entries().next() {
                println!(
                    "  e.g. one returning user: {} session(s), countries seen in both months: {:?}",
                    activity.sessions, activity.countries
                );
            }
        }
        Err(e) => println!("No intersection result: {e}"),
    }

    // A-not-b: users who churned after January.
    let churned = TupleAnotB::<Activity>::new().compute(&january, &february, true);
    println!("Churned after January: {:.0}", churned.get_estimate());

    // Jaccard similarity of the two months' audiences.
    let similarity = tuple_jaccard_similarity(&january, &february);
    println!(
        "Audience overlap (Jaccard): {:.3} (range [{:.3}, {:.3}])",
        similarity.estimate, similarity.lower_bound, similarity.upper_bound
    );
}

pub fn get_result( &self, ordered: bool, ) -> Result<CompactTupleSketch<S>, SketchError>

Returns the current result, or SketchError::EmptyIntersection if Self::update has never been called. If ordered is true, entries are sorted by hash value.

The no-operand case is an error rather than an empty sketch because upstream defines it as the infinite “universe” and throws (theta_intersection_base::get_result). That is a genuinely different state from an intersection of disjoint operands, which succeeds and returns an empty sketch.

Examples found in repository

examples/tuple_generic.rs (line 122)

fn main() {
    let mut january: TupleSketch<Activity> = TupleSketchBuilder::new().lg_k(12).build().unwrap();
    for user in 0..10_000u64 {
        january.update_u64(
            user,
            &Event {
                revenue_cents: 250 + (user % 100),
                country: if user % 2 == 0 { "GB" } else { "US" },
            },
        );
    }

    let mut february: TupleSketch<Activity> = TupleSketchBuilder::new().lg_k(12).build().unwrap();
    for user in 5_000..15_000u64 {
        february.update_u64(
            user,
            &Event {
                revenue_cents: 400,
                country: "US",
            },
        );
    }

    println!("January unique users:  {:.0}", january.get_estimate());
    println!("February unique users: {:.0}", february.get_estimate());

    // Union: everyone who appeared in either month, with their activity merged.
    let mut union = TupleUnionBuilder::<Activity>::new()
        .lg_k(12)
        .build()
        .unwrap();
    union.update(&january);
    union.update(&february);
    let combined = union.get_result(true);
    println!("Users across both months: {:.0}", combined.get_estimate());

    // Per-entry summaries are the point of a Tuple sketch. Scale the retained
    // sample back up by 1/theta to estimate population totals.
    let retained_revenue: u64 = combined.entries().map(|(_, a)| a.revenue_cents).sum();
    let biggest_order = combined
        .entries()
        .map(|(_, a)| a.largest_order_cents)
        .max()
        .unwrap_or(0);
    println!(
        "Estimated total revenue: {:.2} (from {} retained entries, theta = {:.4})",
        (retained_revenue as f64 / combined.get_theta()) / 100.0,
        combined.get_num_retained(),
        combined.get_theta()
    );
    println!(
        "Largest single order seen: {:.2}",
        biggest_order as f64 / 100.0
    );

    // Intersection: users active in both months.
    let mut intersection = TupleIntersection::<Activity>::new();
    intersection.update(&january);
    intersection.update(&february);
    match intersection.get_result(true) {
        Ok(returning) => {
            println!("Returning users: {:.0}", returning.get_estimate());
            // `intersection_combine`'s `min` semantics at work: a returning
            // user's sessions/countries reflect only what showed up in BOTH
            // months, not the union of the two.
            if let Some((_, activity)) = returning.entries().next() {
                println!(
                    "  e.g. one returning user: {} session(s), countries seen in both months: {:?}",
                    activity.sessions, activity.countries
                );
            }
        }
        Err(e) => println!("No intersection result: {e}"),
    }

    // A-not-b: users who churned after January.
    let churned = TupleAnotB::<Activity>::new().compute(&january, &february, true);
    println!("Churned after January: {:.0}", churned.get_estimate());

    // Jaccard similarity of the two months' audiences.
    let similarity = tuple_jaccard_similarity(&january, &february);
    println!(
        "Audience overlap (Jaccard): {:.3} (range [{:.3}, {:.3}])",
        similarity.estimate, similarity.lower_bound, similarity.upper_bound
    );
}

pub fn has_result(&self) -> bool

Returns true if Self::update has been called at least once.

Trait Implementations

impl<S: TupleSummary> Default for TupleIntersection<S>

fn default() -> Self

Returns the “default value” for a type.

impl<S: TupleSummary> Send for TupleIntersection<S>