KNearestNeighborClassifier (Lucene 10.5.0 classification API)
Description: declaration: package: org.apache.lucene.classification, class: KNearestNeighborClassifier

Package 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
  Description
  `protected final String`
  `classFieldName`
  the name of the field used as the output text
  `protected final IndexSearcher`
  `indexSearcher`
  an `IndexSearcher` used to perform queries
  `protected final int`
  `k`
  the no.
  `protected final MoreLikeThis`
  `mlt`
  a `MoreLikeThis` instance used to perform MLT queries
  `protected final Query`
  `query`
  a `Query` used to filter the documents that should be used from this classifier's underlying `LeafReader`
  `protected final String[]`
  `textFieldNames`
  the name of the fields used as the input text

- ## Constructor Summary

  Constructors
  Constructor
  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

  Modifier and Type
  Method
  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 Details

  - ### 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 Details

  - ### KNearestNeighborClassifier

    public KNearestNeighborClassifier(IndexReader indexReader, Similarity similarity, Analyzer analyzer, Query query, int k, int minDocsFreq, int minTermFreq, String classFieldName, String... textFieldNames) throws IOException
    Creates a `KNearestNeighborClassifier`.
    Parameters:
      `indexReader` - the reader on the index to be used for classification
      `similarity` - the `Similarity` to be used by the underlying `IndexSearcher` or `null` (defaults to `BM25Similarity`)
      `analyzer` - an `Analyzer` used to analyze unseen text
      `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
    Throws:
      `IOException`

- ## Method Details

  - ### 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`