org.apache.datasketches.BoundsOnRatiosInThetaSketchedSets Maven / Gradle / Ivy

Go to download
/*
 * 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;

import org.apache.datasketches.theta.Sketch;

/**
 * This class is used to compute the bounds on the estimate of the ratio B / A, where:
 * 
 * A is a Theta Sketch of population PopA.
 * B is a Theta Sketch of population PopB that is a subset of A,
 * obtained by an intersection of A with some other 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
 */
public final class BoundsOnRatiosInThetaSketchedSets {

  private BoundsOnRatiosInThetaSketchedSets() {}

  /**
   * Gets the approximate lower bound for B over A based on a 95% confidence interval
   * @param sketchA the sketch A
   * @param sketchB the sketch B
   * @return the approximate lower bound for B over A
   */
  public static double getLowerBoundForBoverA(final Sketch sketchA, final Sketch sketchB) {
    final double thetaA = sketchA.getTheta();
    final double thetaB = sketchB.getTheta();
    checkThetas(thetaA, thetaB);

    final int countB = sketchB.getRetainedEntries(true);
    final int countA = (thetaB == thetaA) ? sketchA.getRetainedEntries(true)
        : sketchA.getCountLessThanTheta(thetaB);

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

    return BoundsOnRatiosInSampledSets.getLowerBoundForBoverA(countA, countB, thetaB);
  }

  /**
   * Gets the approximate upper bound for B over A based on a 95% confidence interval
   * @param sketchA the sketch A
   * @param sketchB the sketch B
   * @return the approximate upper bound for B over A
   */
  public static double getUpperBoundForBoverA(final Sketch sketchA, final Sketch sketchB) {
    final double thetaA = sketchA.getTheta();
    final double thetaB = sketchB.getTheta();
    checkThetas(thetaA, thetaB);

    final int countB = sketchB.getRetainedEntries(true);
    final int countA = (thetaB == thetaA) ? sketchA.getRetainedEntries(true)
        : sketchA.getCountLessThanTheta(thetaB);

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

    return BoundsOnRatiosInSampledSets.getUpperBoundForBoverA(countA, countB, thetaB);
  }

  /**
   * Gets the estimate for B over A
   * @param sketchA the sketch A
   * @param sketchB the sketch B
   * @return the estimate for B over A
   */
  public static double getEstimateOfBoverA(final Sketch sketchA, final Sketch sketchB) {
    final double thetaA = sketchA.getTheta();
    final double thetaB = sketchB.getTheta();
    checkThetas(thetaA, thetaB);

    final int countB = sketchB.getRetainedEntries(true);
    final int countA = (thetaB == thetaA) ? sketchA.getRetainedEntries(true)
        : sketchA.getCountLessThanTheta(thetaB);

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

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

  static void checkThetas(final double thetaA, final double thetaB) {
    if (thetaB > thetaA) {
      throw new SketchesArgumentException("ThetaB cannot be > ThetaA.");
    }
  }
}