lucene-java-3.5.0/lucene/contrib/facet/src/java/org/apache/lucene/facet/search/sampling/SamplingParams.java

   1 package org.apache.lucene.facet.search.sampling;
   2
   3 /**
   4  * Licensed to the Apache Software Foundation (ASF) under one or more
   5  * contributor license agreements.  See the NOTICE file distributed with
   6  * this work for additional information regarding copyright ownership.
   7  * The ASF licenses this file to You under the Apache License, Version 2.0
   8  * (the "License"); you may not use this file except in compliance with
   9  * the License.  You may obtain a copy of the License at
  10  *
  11  *     http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  */
  19
  20 /**
  21  * Parameters for sampling, dictating whether sampling is to take place and how.
  22  *
  23  * @lucene.experimental
  24  */
  25 public class SamplingParams {
  26
  27   /**
  28    * Default factor by which more results are requested over the sample set.
  29    * @see SamplingParams#getOversampleFactor()
  30    */
  31   public static final double DEFAULT_OVERSAMPLE_FACTOR = 2d;
  32
  33   /**
  34    * Default ratio between size of sample to original size of document set.
  35    * @see Sampler#getSampleSet(org.apache.lucene.facet.search.ScoredDocIDs)
  36    */
  37   public static final double DEFAULT_SAMPLE_RATIO = 0.01;
  38
  39   /**
  40    * Default maximum size of sample.
  41    * @see Sampler#getSampleSet(org.apache.lucene.facet.search.ScoredDocIDs)
  42    */
  43   public static final int DEFAULT_MAX_SAMPLE_SIZE = 10000;
  44
  45   /**
  46    * Default minimum size of sample.
  47    * @see Sampler#getSampleSet(org.apache.lucene.facet.search.ScoredDocIDs)
  48    */
  49   public static final int DEFAULT_MIN_SAMPLE_SIZE = 100;
  50
  51   /**
  52    * Default sampling threshold, if number of results is less than this number - no sampling will take place
  53    * @see SamplingParams#getSampleRatio()
  54    */
  55   public static final int DEFAULT_SAMPLING_THRESHOLD = 75000;
  56
  57   private int maxSampleSize = DEFAULT_MAX_SAMPLE_SIZE;
  58   private int minSampleSize = DEFAULT_MIN_SAMPLE_SIZE;
  59   private double sampleRatio = DEFAULT_SAMPLE_RATIO;
  60   private int samplingThreshold = DEFAULT_SAMPLING_THRESHOLD;
  61   private double oversampleFactor = DEFAULT_OVERSAMPLE_FACTOR;
  62
  63   /**
  64    * Return the maxSampleSize.
  65    * In no case should the resulting sample size exceed this value.
  66    * @see Sampler#getSampleSet(org.apache.lucene.facet.search.ScoredDocIDs)
  67    */
  68   public final int getMaxSampleSize() {
  69     return maxSampleSize;
  70   }
  71
  72   /**
  73    * Return the minSampleSize.
  74    * In no case should the resulting sample size be smaller than this value.
  75    * @see Sampler#getSampleSet(org.apache.lucene.facet.search.ScoredDocIDs)
  76    */
  77   public final int getMinSampleSize() {
  78     return minSampleSize;
  79   }
  80
  81   /**
  82    * @return the sampleRatio
  83    * @see Sampler#getSampleSet(org.apache.lucene.facet.search.ScoredDocIDs)
  84    */
  85   public final double getSampleRatio() {
  86     return sampleRatio;
  87   }
  88
  89   /**
  90    * Return the samplingThreshold.
  91    * Sampling would be performed only for document sets larger than this.
  92    */
  93   public final int getSamplingThreshold() {
  94     return samplingThreshold;
  95   }
  96
  97   /**
  98    * @param maxSampleSize
  99    *          the maxSampleSize to set
 100    * @see #getMaxSampleSize()
 101    */
 102   public void setMaxSampleSize(int maxSampleSize) {
 103     this.maxSampleSize = maxSampleSize;
 104   }
 105
 106   /**
 107    * @param minSampleSize
 108    *          the minSampleSize to set
 109    * @see #getMinSampleSize()
 110    */
 111   public void setMinSampleSize(int minSampleSize) {
 112     this.minSampleSize = minSampleSize;
 113   }
 114
 115   /**
 116    * @param sampleRatio
 117    *          the sampleRatio to set
 118    * @see #getSampleRatio()
 119    */
 120   public void setSampleRatio(double sampleRatio) {
 121     this.sampleRatio = sampleRatio;
 122   }
 123
 124   /**
 125    * Set a sampling-threshold
 126    * @see #getSamplingThreshold()
 127    */
 128   public void setSampingThreshold(int sampingThreshold) {
 129     this.samplingThreshold = sampingThreshold;
 130   }
 131
 132   /**
 133    * Check validity of sampling settings, making sure that
 134    * <ul>
 135    * <li> <code>minSampleSize <= maxSampleSize <= samplingThreshold </code></li>
 136    * <li> <code>0 < samplingRatio <= 1 </code></li>
 137    * </ul>
 138    *
 139    * @return true if valid, false otherwise
 140    */
 141   public boolean validate() {
 142     return
 143       samplingThreshold >= maxSampleSize &&
 144       maxSampleSize >= minSampleSize &&
 145       sampleRatio > 0 &&
 146       sampleRatio < 1;
 147   }
 148
 149   /**
 150    * Return the oversampleFactor. When sampling, we would collect that much more
 151    * results, so that later, when selecting top out of these, chances are higher
 152    * to get actual best results. Note that having this value larger than 1 only
 153    * makes sense when using a SampleFixer which finds accurate results, such as
 154    * <code>TakmiSampleFixer</code>. When this value is smaller than 1, it is
 155    * ignored and no oversampling takes place.
 156    */
 157   public final double getOversampleFactor() {
 158     return oversampleFactor;
 159   }
 160
 161   /**
 162    * @param oversampleFactor the oversampleFactor to set
 163    * @see #getOversampleFactor()
 164    */
 165   public void setOversampleFactor(double oversampleFactor) {
 166     this.oversampleFactor = oversampleFactor;
 167   }
 168
 169 }