Package org.apache.lucene.search.similarities

## Class Axiomatic

- java.lang.Object
- - org.apache.lucene.search.similarities.Similarity
  - - org.apache.lucene.search.similarities.SimilarityBase
    - - org.apache.lucene.search.similarities.Axiomatic

- Direct Known Subclasses:
    `AxiomaticF1EXP`, `AxiomaticF1LOG`, `AxiomaticF2EXP`, `AxiomaticF2LOG`, `AxiomaticF3EXP`, `AxiomaticF3LOG`

      public abstract class Axiomatic
      extends SimilarityBase

  Axiomatic approaches for IR. From Hui Fang and Chengxiang Zhai 2005. An Exploration of Axiomatic Approaches to Information Retrieval. In Proceedings of the 28th annual international ACM SIGIR conference on Research and development in information retrieval (SIGIR '05). ACM, New York, NY, USA, 480-487.

  There are a family of models. All of them are based on BM25, Pivoted Document Length Normalization and Language model with Dirichlet prior. Some components (e.g. Term Frequency, Inverted Document Frequency) in the original models are modified so that they follow some axiomatic constraints.

  WARNING: This API is experimental and might change in incompatible ways in the next release.

- - ### Nested Class Summary

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

      `Similarity.SimScorer`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected float` | `k` | hyperparam for the primitive weighthing function
    `protected int` | `queryLen` | the query length
    `protected float` | `s` | hyperparam for the growth function

    - ### Fields inherited from class org.apache.lucene.search.similarities.SimilarityBase

      `discountOverlaps`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Axiomatic()` | Default constructor
    `Axiomatic​(float s)` | Constructor setting only s, letting k and queryLen to default
    `Axiomatic​(float s, int queryLen)` | Constructor setting s and queryLen, letting k to default
    `Axiomatic​(float s, int queryLen, float k)` | Constructor setting all Axiomatic hyperparameters

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `explain​(List<Explanation> subs, BasicStats stats, double freq, double docLen)` | Subclasses should implement this method to explain the score.
    `protected Explanation` | `explain​(BasicStats stats, Explanation freq, double docLen)` | Explains the score.
    `protected abstract double` | `gamma​(BasicStats stats, double freq, double docLen)` | compute the gamma component (only for F3EXp and F3LOG)
    `protected abstract double` | `idf​(BasicStats stats, double freq, double docLen)` | compute the inverted document frequency component
    `protected abstract Explanation` | `idfExplain​(BasicStats stats, double freq, double docLen)` | Explain the score of the inverted document frequency component for a single document
    `protected abstract double` | `ln​(BasicStats stats, double freq, double docLen)` | compute the document length component
    `protected abstract Explanation` | `lnExplain​(BasicStats stats, double freq, double docLen)` | Explain the score of the document length component for a single document
    `double` | `score​(BasicStats stats, double freq, double docLen)` | Scores the document `doc`.
    `protected abstract double` | `tf​(BasicStats stats, double freq, double docLen)` | compute the term frequency component
    `protected abstract Explanation` | `tfExplain​(BasicStats stats, double freq, double docLen)` | Explain the score of the term frequency component for a single document
    `protected abstract double` | `tfln​(BasicStats stats, double freq, double docLen)` | compute the mixed term frequency and document length component
    `protected abstract Explanation` | `tflnExplain​(BasicStats stats, double freq, double docLen)` | Explain the score of the mixed term frequency and document length component for a single document
    `abstract String` | `toString()` | Name of the axiomatic method.

    - ### Methods inherited from class org.apache.lucene.search.similarities.SimilarityBase

      `computeNorm, fillBasicStats, getDiscountOverlaps, log2, newStats, scorer, setDiscountOverlaps`

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

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

- - ### Field Detail

    - #### s

          protected final float s

      hyperparam for the growth function

    - #### k

          protected final float k

      hyperparam for the primitive weighthing function

    - #### queryLen

          protected final int queryLen

      the query length

  - ### Constructor Detail

    - #### Axiomatic

          public Axiomatic​(float s,
                           int queryLen,
                           float k)

      Constructor setting all Axiomatic hyperparameters
      Parameters:
        `s` - hyperparam for the growth function
        `queryLen` - the query length
        `k` - hyperparam for the primitive weighting function

    - #### Axiomatic

          public Axiomatic​(float s)

      Constructor setting only s, letting k and queryLen to default
      Parameters:
        `s` - hyperparam for the growth function

    - #### Axiomatic

          public Axiomatic​(float s,
                           int queryLen)

      Constructor setting s and queryLen, letting k to default
      Parameters:
        `s` - hyperparam for the growth function
        `queryLen` - the query length

    - #### Axiomatic

          public Axiomatic()

      Default constructor

  - ### Method Detail

    - #### score

          public double score​(BasicStats stats,
                              double freq,
                              double docLen)

      Description copied from class: `SimilarityBase`
      Scores the document `doc`.

      Subclasses must apply their scoring formula in this class.

      Specified by:
        `score` in class `SimilarityBase`
      Parameters:
        `stats` - the corpus level statistics.
        `freq` - the term frequency.
        `docLen` - the document length.
      Returns:
        the score.

    - #### explain

          protected Explanation explain​(BasicStats stats,
                                        Explanation freq,
                                        double docLen)

      Description copied from class: `SimilarityBase`
      Explains the score. The implementation here provides a basic explanation in the format score(name-of-similarity, doc=doc-id, freq=term-frequency), computed from:, and attaches the score (computed via the `SimilarityBase.score(BasicStats, double, double)` method) and the explanation for the term frequency. Subclasses content with this format may add additional details in `SimilarityBase.explain(List, BasicStats, double, double)`.
      Overrides:
        `explain` in class `SimilarityBase`
      Parameters:
        `stats` - the corpus level statistics.
        `freq` - the term frequency and its explanation.
        `docLen` - the document length.
      Returns:
        the explanation.

    - #### explain

          protected void explain​(List<Explanation> subs,
                                 BasicStats stats,
                                 double freq,
                                 double docLen)

      Description copied from class: `SimilarityBase`
      Subclasses should implement this method to explain the score. `expl` already contains the score, the name of the class and the doc id, as well as the term frequency and its explanation; subclasses can add additional clauses to explain details of their scoring formulae.

      The default implementation does nothing.

      Overrides:
        `explain` in class `SimilarityBase`
      Parameters:
        `subs` - the list of details of the explanation to extend
        `stats` - the corpus level statistics.
        `freq` - the term frequency.
        `docLen` - the document length.

    - #### toString

          public abstract String toString()

      Name of the axiomatic method.
      Specified by:
        `toString` in class `SimilarityBase`

    - #### tf

          protected abstract double tf​(BasicStats stats,
                                       double freq,
                                       double docLen)

      compute the term frequency component

    - #### ln

          protected abstract double ln​(BasicStats stats,
                                       double freq,
                                       double docLen)

      compute the document length component

    - #### tfln

          protected abstract double tfln​(BasicStats stats,
                                         double freq,
                                         double docLen)

      compute the mixed term frequency and document length component

    - #### idf

          protected abstract double idf​(BasicStats stats,
                                        double freq,
                                        double docLen)

      compute the inverted document frequency component

    - #### gamma

          protected abstract double gamma​(BasicStats stats,
                                          double freq,
                                          double docLen)

      compute the gamma component (only for F3EXp and F3LOG)

    - #### tfExplain

          protected abstract Explanation tfExplain​(BasicStats stats,
                                                   double freq,
                                                   double docLen)

      Explain the score of the term frequency component for a single document
      Parameters:
        `stats` - the corpus level statistics
        `freq` - number of occurrences of term in the document
        `docLen` - the document length
      Returns:
        Explanation of how the tf component was computed

    - #### lnExplain

          protected abstract Explanation lnExplain​(BasicStats stats,
                                                   double freq,
                                                   double docLen)

      Explain the score of the document length component for a single document
      Parameters:
        `stats` - the corpus level statistics
        `freq` - number of occurrences of term in the document
        `docLen` - the document length
      Returns:
        Explanation of how the ln component was computed

    - #### tflnExplain

          protected abstract Explanation tflnExplain​(BasicStats stats,
                                                     double freq,
                                                     double docLen)

      Explain the score of the mixed term frequency and document length component for a single document
      Parameters:
        `stats` - the corpus level statistics
        `freq` - number of occurrences of term in the document
        `docLen` - the document length
      Returns:
        Explanation of how the tfln component was computed

    - #### idfExplain

          protected abstract Explanation idfExplain​(BasicStats stats,
                                                    double freq,
                                                    double docLen)

      Explain the score of the inverted document frequency component for a single document
      Parameters:
        `stats` - the corpus level statistics
        `freq` - number of occurrences of term in the document
        `docLen` - the document length
      Returns:
        Explanation of how the idf component was computed