org.apache.lucene.classification

## Class KNearestNeighborClassifier

- java.lang.Object
- - org.apache.lucene.classification.KNearestNeighborClassifier

- All Implemented Interfaces:
    Classifier<BytesRef>
  Direct Known Subclasses:
    KNearestNeighborDocumentClassifier

      public class KNearestNeighborClassifier
      extends Object
      implements Classifier<BytesRef>

  A k-Nearest Neighbor classifier (see `http://en.wikipedia.org/wiki/K-nearest_neighbors`) based on `MoreLikeThis`
  WARNING: This API is experimental and might change in incompatible ways in the next release.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected String` | `classFieldName` the name of the field used as the output text
    `protected IndexSearcher` | `indexSearcher` an `IndexSearcher` used to perform queries
    `protected int` | `k` the no.
    `protected MoreLikeThis` | `mlt` a `MoreLikeThis` instance used to perform MLT queries
    `protected Query` | `query` a `Query` used to filter the documents that should be used from this classifier's underlying `LeafReader`
    `protected String[]` | `textFieldNames` the name of the fields used as the input text

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `KNearestNeighborClassifier(IndexReader indexReader, Similarity similarity, Analyzer analyzer, Query query, int k, int minDocsFreq, int minTermFreq, String classFieldName, String... textFieldNames)` Creates a `KNearestNeighborClassifier`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `ClassificationResult<BytesRef>` | `assignClass(String text)` Assign a class (with score) to the given text String
    `protected List<ClassificationResult<BytesRef>>` | `buildListFromTopDocs(TopDocs topDocs)` build a list of classification results from search results
    `protected ClassificationResult<BytesRef>` | `classifyFromTopDocs(TopDocs knnResults)` TODO
    `List<ClassificationResult<BytesRef>>` | `getClasses(String text)` Get all the classes (sorted by score, descending) assigned to the given text String.
    `List<ClassificationResult<BytesRef>>` | `getClasses(String text, int max)` Get the first `max` classes (sorted by score, descending) assigned to the given text String.
    `String` | `toString()`

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

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

- - ### Field Detail

    - #### mlt

          protected final MoreLikeThis mlt

      a `MoreLikeThis` instance used to perform MLT queries

    - #### textFieldNames

          protected final String[] textFieldNames

      the name of the fields used as the input text

    - #### classFieldName

          protected final String classFieldName

      the name of the field used as the output text

    - #### indexSearcher

          protected final IndexSearcher indexSearcher

      an `IndexSearcher` used to perform queries

    - #### k

          protected final int k

      the no. of docs to compare in order to find the nearest neighbor to the input text

    - #### query

          protected final Query query

      a `Query` used to filter the documents that should be used from this classifier's underlying `LeafReader`

  - ### Constructor Detail

    - #### KNearestNeighborClassifier

          public KNearestNeighborClassifier(IndexReader indexReader,
                                            Similarity similarity,
                                            Analyzer analyzer,
                                            Query query,
                                            int k,
                                            int minDocsFreq,
                                            int minTermFreq,
                                            String classFieldName,
                                            String... textFieldNames)

      Creates a `KNearestNeighborClassifier`.
      Parameters:
        `indexReader` - the reader on the index to be used for classification
        `analyzer` - an `Analyzer` used to analyze unseen text
        `similarity` - the `Similarity` to be used by the underlying `IndexSearcher` or `null` (defaults to `BM25Similarity`)
        `query` - a `Query` to eventually filter the docs used for training the classifier, or `null` if all the indexed docs should be used
        `k` - the no. of docs to select in the MLT results to find the nearest neighbor
        `minDocsFreq` - `MoreLikeThis.minDocFreq` parameter
        `minTermFreq` - `MoreLikeThis.minTermFreq` parameter
        `classFieldName` - the name of the field used as the output for the classifier
        `textFieldNames` - the name of the fields used as the inputs for the classifier, they can contain boosting indication e.g. title^10

  - ### Method Detail

    - #### assignClass

          public ClassificationResult<BytesRef> assignClass(String text)
                                                     throws IOException

      Description copied from interface: `Classifier`
      Assign a class (with score) to the given text String
      Specified by:
        `assignClass` in interface `Classifier<BytesRef>`
      Parameters:
        `text` - a String containing text to be classified
      Returns:
        a `ClassificationResult` holding assigned class of type `T` and score
      Throws:
        `IOException` - If there is a low-level I/O error.

    - #### classifyFromTopDocs

          protected ClassificationResult<BytesRef> classifyFromTopDocs(TopDocs knnResults)
                                                                throws IOException

      TODO
      Throws:
        `IOException`

    - #### getClasses

          public List<ClassificationResult<BytesRef>> getClasses(String text)
                                                          throws IOException

      Description copied from interface: `Classifier`
      Get all the classes (sorted by score, descending) assigned to the given text String.
      Specified by:
        `getClasses` in interface `Classifier<BytesRef>`
      Parameters:
        `text` - a String containing text to be classified
      Returns:
        the whole list of `ClassificationResult`, the classes and scores. Returns `null` if the classifier can't make lists.
      Throws:
        `IOException` - If there is a low-level I/O error.

    - #### getClasses

          public List<ClassificationResult<BytesRef>> getClasses(String text,
                                                                 int max)
                                                          throws IOException

      Description copied from interface: `Classifier`
      Get the first `max` classes (sorted by score, descending) assigned to the given text String.
      Specified by:
        `getClasses` in interface `Classifier<BytesRef>`
      Parameters:
        `text` - a String containing text to be classified
        `max` - the number of return list elements
      Returns:
        the whole list of `ClassificationResult`, the classes and scores. Cut for "max" number of elements. Returns `null` if the classifier can't make lists.
      Throws:
        `IOException` - If there is a low-level I/O error.

    - #### buildListFromTopDocs

          protected List<ClassificationResult<BytesRef>> buildListFromTopDocs(TopDocs topDocs)
                                                                       throws IOException

      build a list of classification results from search results
      Parameters:
        `topDocs` - the search results as a `TopDocs` object
      Returns:
        a `List` of `ClassificationResult`, one for each existing class
      Throws:
        `IOException` - if it's not possible to get the stored value of class field

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

Copyright © 2000-2021 Apache Software Foundation. All Rights Reserved.