SweetSpotSimilarity (Lucene 10.5.0 misc API)
Description: declaration: package: org.apache.lucene.misc, class: SweetSpotSimilarity

Package org.apache.lucene.misc

# Class SweetSpotSimilarity

java.lang.Object
org.apache.lucene.search.similarities.Similarity
org.apache.lucene.search.similarities.TFIDFSimilarity
org.apache.lucene.search.similarities.ClassicSimilarity
org.apache.lucene.misc.SweetSpotSimilarity

public class SweetSpotSimilarity extends ClassicSimilarity
A similarity with a lengthNorm that provides for a "plateau" of equally good lengths, and tf helper functions.

For lengthNorm, A min/max can be specified to define the plateau of lengths that should all have a norm of 1.0. Below the min, and above the max the lengthNorm drops off in a sqrt function.

For tf, baselineTf and hyperbolicTf functions are provided, which subclasses can choose between.

See Also:
  - A Gnuplot file used to generate some of the visualizations referenced from each function.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class org.apache.lucene.search.similarities.Similarity

  `Similarity.BulkSimScorer, Similarity.SimScorer`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SweetSpotSimilarity()`
  Default constructor: parameter-free
  `SweetSpotSimilarity(boolean discountOverlaps)`
  Primary constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `float`
  `baselineTf(float freq)`
  Implemented as: `(x <= min) ? base : sqrt(x+(base**2)-min)` ...but with a special case check for 0.
  `float`
  `hyperbolicTf(float freq)`
  Uses a hyperbolic tangent function that allows for a hard max...
  `float`
  `lengthNorm(int numTerms)`
  Implemented as: `1/sqrt( steepness * (abs(x-min) + abs(x-max) - (max-min)) + 1 )` .
  `void`
  `setBaselineTfFactors(float base, float min)`
  Sets the baseline and minimum function variables for baselineTf
  `void`
  `setHyperbolicTfFactors(float min, float max, double base, float xoffset)`
  Sets the function variables for the hyperbolicTf functions
  `void`
  `setLengthNormFactors(int min, int max, float steepness)`
  Sets the default function variables used by lengthNorm when no field specific variables have been set.
  `float`
  `tf(float freq)`
  Delegates to baselineTf
  `String`
  `toString()`

  ### Methods inherited from class org.apache.lucene.search.similarities.ClassicSimilarity

  `idf, idfExplain`

  ### Methods inherited from class org.apache.lucene.search.similarities.TFIDFSimilarity

  `idfExplain, scorer`

  ### Methods inherited from class org.apache.lucene.search.similarities.Similarity

  `computeNorm, getDiscountOverlaps`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### SweetSpotSimilarity

    public SweetSpotSimilarity()
    Default constructor: parameter-free

  - ### SweetSpotSimilarity

    public SweetSpotSimilarity(boolean discountOverlaps)
    Primary constructor.

- ## Method Details

  - ### setBaselineTfFactors

    public void setBaselineTfFactors(float base, float min)
    Sets the baseline and minimum function variables for baselineTf
    See Also:
      - `baselineTf(float)`

  - ### setHyperbolicTfFactors

    public void setHyperbolicTfFactors(float min, float max, double base, float xoffset)
    Sets the function variables for the hyperbolicTf functions
    Parameters:
      `min` - the minimum tf value to ever be returned (default: 0.0)
      `max` - the maximum tf value to ever be returned (default: 2.0)
      `base` - the base value to be used in the exponential for the hyperbolic function (default: 1.3)
      `xoffset` - the midpoint of the hyperbolic function (default: 10.0)
    See Also:
      - `hyperbolicTf(float)`

  - ### setLengthNormFactors

    public void setLengthNormFactors(int min, int max, float steepness)
    Sets the default function variables used by lengthNorm when no field specific variables have been set.
    See Also:
      - `lengthNorm(int)`

  - ### lengthNorm

    public float lengthNorm(int numTerms)
    Implemented as: `1/sqrt( steepness * (abs(x-min) + abs(x-max) - (max-min)) + 1 )` .

    This degrades to `1/sqrt(x)` when min and max are both 1 and steepness is 0.5

    :TODO: potential optimization is to just flat out return 1.0f if numTerms is between min and max.

    Overrides:
      `lengthNorm` in class `ClassicSimilarity`
    See Also:
      - `setLengthNormFactors(int, int, float)`
      - An SVG visualization of this function

  - ### tf

    public float tf(float freq)
    Delegates to baselineTf
    Overrides:
      `tf` in class `ClassicSimilarity`
    See Also:
      - `baselineTf(float)`

  - ### baselineTf

    public float baselineTf(float freq)
    Implemented as: `(x <= min) ? base : sqrt(x+(base**2)-min)` ...but with a special case check for 0.

    This degrades to `sqrt(x)` when min and base are both 0

    See Also:
      - `setBaselineTfFactors(float, float)`
      - An SVG visualization of this function

  - ### hyperbolicTf

    public float hyperbolicTf(float freq)
    Uses a hyperbolic tangent function that allows for a hard max... `tf(x)=min+(max-min)/2*(((base**(x-xoffset)-base**-(x-xoffset))/(base**(x-xoffset)+base**-(x-xoffset)))+1)`

    This code is provided as a convenience for subclasses that want to use a hyperbolic tf function.

    See Also:
      - `setHyperbolicTfFactors(float, float, double, float)`
      - An SVG visualization of this function

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `ClassicSimilarity`