org.apache.datasketches.thetacommon.BoundsOnRatiosInTupleSketchedSets Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of datasketches-java Show documentation
Core sketch algorithms used alone and by other Java repositories in the DataSketches library.
There is a newer version: 6.1.1
/*
 * 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.
 */

package org.apache.datasketches.thetacommon;

import static org.apache.datasketches.common.Util.LONG_MAX_VALUE_AS_DOUBLE;

import org.apache.datasketches.common.BoundsOnRatiosInSampledSets;
import org.apache.datasketches.common.SketchesArgumentException;
import org.apache.datasketches.tuple.Sketch;
import org.apache.datasketches.tuple.Summary;

/**
 * This class is used to compute the bounds on the estimate of the ratio B / A, where:
 * 
 * A is a Tuple Sketch of population PopA.
 * B is a Tuple or Theta Sketch of population PopB that is a subset of A,
 * obtained by an intersection of A with some other Tuple or Theta Sketch C,
 * which acts like a predicate or selection clause.
 * The estimate of the ratio PopB/PopA is
 * BoundsOnRatiosInThetaSketchedSets.getEstimateOfBoverA(A, B).
 * The Upper Bound estimate on the ratio PopB/PopA is
 * BoundsOnRatiosInThetaSketchedSets.getUpperBoundForBoverA(A, B).
 * The Lower Bound estimate on the ratio PopB/PopA is
 * BoundsOnRatiosInThetaSketchedSets.getLowerBoundForBoverA(A, B).
 * 
 * Note: The theta of A cannot be greater than the theta of B.
 * If B is formed as an intersection of A and some other set C,
 * then the theta of B is guaranteed to be less than or equal to the theta of B.
 *
 * @author Kevin Lang
 * @author Lee Rhodes
 * @author David Cromberge
 */
public final class BoundsOnRatiosInTupleSketchedSets {

  private BoundsOnRatiosInTupleSketchedSets() {}

  /**
   * Gets the approximate lower bound for B over A based on a 95% confidence interval
   * @param sketchA the Tuple sketch A with summary type S
   * @param sketchB the Tuple sketch B with summary type S
   * @param  Summary
   * @return the approximate lower bound for B over A
   */
  public static  double getLowerBoundForBoverA(
      final Sketch sketchA,
      final Sketch sketchB) {
    final long thetaLongA = sketchA.getThetaLong();
    final long thetaLongB = sketchB.getThetaLong();
    checkThetas(thetaLongA, thetaLongB);

    final int countB = sketchB.getRetainedEntries();
    final int countA = thetaLongB == thetaLongA
        ? sketchA.getRetainedEntries()
        : sketchA.getCountLessThanThetaLong(thetaLongB);

    if (countA <= 0) { return 0; }
    final double f = thetaLongB / LONG_MAX_VALUE_AS_DOUBLE;
    return BoundsOnRatiosInSampledSets.getLowerBoundForBoverA(countA, countB, f);
  }

  /**
   * Gets the approximate lower bound for B over A based on a 95% confidence interval
   * @param sketchA the Tuple sketch A with summary type S
   * @param sketchB the Theta sketch B
   * @param  Summary
   * @return the approximate lower bound for B over A
   */
  public static  double getLowerBoundForBoverA(
      final Sketch sketchA,
      final org.apache.datasketches.theta.Sketch sketchB) {
    final long thetaLongA = sketchA.getThetaLong();
    final long thetaLongB = sketchB.getThetaLong();
    checkThetas(thetaLongA, thetaLongB);

    final int countB = sketchB.getRetainedEntries();
    final int countA = thetaLongB == thetaLongA
            ? sketchA.getRetainedEntries()
            : sketchA.getCountLessThanThetaLong(thetaLongB);

    if (countA <= 0) { return 0; }
    final double f = thetaLongB / LONG_MAX_VALUE_AS_DOUBLE;
    return BoundsOnRatiosInSampledSets.getLowerBoundForBoverA(countA, countB, f);
  }

  /**
   * Gets the approximate upper bound for B over A based on a 95% confidence interval
   * @param sketchA the Tuple sketch A with summary type S
   * @param sketchB the Tuple sketch B with summary type S
   * @param  Summary
   * @return the approximate upper bound for B over A
   */
  public static  double getUpperBoundForBoverA(
      final Sketch sketchA,
      final Sketch sketchB) {
    final long thetaLongA = sketchA.getThetaLong();
    final long thetaLongB = sketchB.getThetaLong();
    checkThetas(thetaLongA, thetaLongB);

    final int countB = sketchB.getRetainedEntries();
    final int countA = thetaLongB == thetaLongA
            ? sketchA.getRetainedEntries()
            : sketchA.getCountLessThanThetaLong(thetaLongB);

    if (countA <= 0) { return 1.0; }
    final double f = thetaLongB / LONG_MAX_VALUE_AS_DOUBLE;
    return BoundsOnRatiosInSampledSets.getUpperBoundForBoverA(countA, countB, f);
  }

  /**
   * Gets the approximate upper bound for B over A based on a 95% confidence interval
   * @param sketchA the Tuple sketch A with summary type S
   * @param sketchB the Theta sketch B
   * @param  Summary
   * @return the approximate upper bound for B over A
   */
  public static  double getUpperBoundForBoverA(
      final Sketch sketchA,
      final org.apache.datasketches.theta.Sketch sketchB) {
    final long thetaLongA = sketchA.getThetaLong();
    final long thetaLongB = sketchB.getThetaLong();
    checkThetas(thetaLongA, thetaLongB);

    final int countB = sketchB.getRetainedEntries(true);
    final int countA = thetaLongB == thetaLongA
        ? sketchA.getRetainedEntries()
        : sketchA.getCountLessThanThetaLong(thetaLongB);

    if (countA <= 0) { return 1.0; }
    final double f = thetaLongB / LONG_MAX_VALUE_AS_DOUBLE;
    return BoundsOnRatiosInSampledSets.getUpperBoundForBoverA(countA, countB, f);
  }

  /**
   * Gets the estimate for B over A
   * @param sketchA the Tuple sketch A with summary type S
   * @param sketchB the Tuple sketch B with summary type S
   * @param  Summary
   * @return the estimate for B over A
   */
  public static  double getEstimateOfBoverA(
      final Sketch sketchA,
      final Sketch sketchB) {
    final long thetaLongA = sketchA.getThetaLong();
    final long thetaLongB = sketchB.getThetaLong();
    checkThetas(thetaLongA, thetaLongB);

    final int countB = sketchB.getRetainedEntries();
    final int countA = thetaLongB == thetaLongA
        ? sketchA.getRetainedEntries()
        : sketchA.getCountLessThanThetaLong(thetaLongB);

    if (countA <= 0) { return 0.5; }

    return (double) countB / (double) countA;
  }

  /**
   * Gets the estimate for B over A
   * @param sketchA the Tuple sketch A with summary type S
   * @param sketchB the Theta sketch B
   * @param  Summary
   * @return the estimate for B over A
   */
  public static  double getEstimateOfBoverA(
      final Sketch sketchA,
      final org.apache.datasketches.theta.Sketch sketchB) {
    final long thetaLongA = sketchA.getThetaLong();
    final long thetaLongB = sketchB.getThetaLong();
    checkThetas(thetaLongA, thetaLongB);

    final int countB = sketchB.getRetainedEntries(true);
    final int countA = thetaLongB == thetaLongA
            ? sketchA.getRetainedEntries()
            : sketchA.getCountLessThanThetaLong(thetaLongB);

    if (countA <= 0) { return 0.5; }

    return (double) countB / (double) countA;
  }

  static void checkThetas(final long thetaLongA, final long thetaLongB) {
    if (thetaLongB > thetaLongA) {
      throw new SketchesArgumentException("ThetaLongB cannot be > ThetaLongA.");
    }
  }
}