class BM25Model extends AnnotatorModel[BM25Model] with HasSimpleAnnotate[BM25Model] with ParamsAndFeaturesWritable

Fitted model produced by BM25Approach. It holds the corpus-level statistics (IDF map, average document length and document count) and scores every document in a dataset against a user-provided query using the Okapi BM25 ranking function.

The query is provided at transform time, so the same fitted model can be reused for many different queries ("fit once, query many times"). Provide it either as a raw string with setQuery(...) (the model splits it on non-word characters) or — recommended when the corpus was analyzed by a non-trivial pipeline — as already-analyzed tokens with setQueryTokens(...), so the query and the documents are tokenized/normalized identically (see the analyzer-symmetry note on the query parameter). For every input document the model emits a single BM25_RANKINGS annotation whose result is the BM25 score and whose metadata contains:

  • bm25_score — the BM25 relevance score of the document for the current query
  • num_query_terms_matched — how many distinct query terms occur in the document
  • query — the query the document was scored against
  • doc_len — the number of tokens in the document

Example

import com.johnsnowlabs.nlp.base.DocumentAssembler
import com.johnsnowlabs.nlp.annotators.{StopWordsCleaner, Tokenizer}
import com.johnsnowlabs.nlp.annotators.similarity.{BM25Approach, BM25Model}
import org.apache.spark.ml.Pipeline
import org.apache.spark.sql.functions.{col, explode}

val documentAssembler = new DocumentAssembler().setInputCol("text").setOutputCol("document")
val tokenizer = new Tokenizer().setInputCols("document").setOutputCol("token")
val stopWords = new StopWordsCleaner().setInputCols("token").setOutputCol("clean_token")
val bm25 = new BM25Approach().setInputCols("clean_token").setOutputCol("bm25_rankings")

val model = new Pipeline()
  .setStages(Array(documentAssembler, tokenizer, stopWords, bm25))
  .fit(corpus)

val bm25Model = model.stages.last.asInstanceOf[BM25Model]
bm25Model.setQuery("vitamin C health benefits fruits")

model.transform(corpus)
  .select(explode(col("bm25_rankings")).alias("ranking"))
  .select(col("ranking.metadata")("bm25_score").alias("bm25_score"))
  .show(false)
Linear Supertypes
HasSimpleAnnotate[BM25Model], AnnotatorModel[BM25Model], CanBeLazy, RawAnnotator[BM25Model], HasOutputAnnotationCol, HasInputAnnotationCols, HasOutputAnnotatorType, ParamsAndFeaturesWritable, HasFeatures, DefaultParamsWritable, MLWritable, Model[BM25Model], Transformer, PipelineStage, Logging, Params, Serializable, Serializable, Identifiable, AnyRef, Any
Ordering
  1. Grouped
  2. Alphabetic
  3. By Inheritance
Inherited
  1. BM25Model
  2. HasSimpleAnnotate
  3. AnnotatorModel
  4. CanBeLazy
  5. RawAnnotator
  6. HasOutputAnnotationCol
  7. HasInputAnnotationCols
  8. HasOutputAnnotatorType
  9. ParamsAndFeaturesWritable
  10. HasFeatures
  11. DefaultParamsWritable
  12. MLWritable
  13. Model
  14. Transformer
  15. PipelineStage
  16. Logging
  17. Params
  18. Serializable
  19. Serializable
  20. Identifiable
  21. AnyRef
  22. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Instance Constructors

  1. new BM25Model()
  2. new BM25Model(uid: String)

Type Members

  1. type AnnotationContent = Seq[Row]

    internal types to show Rows as a relevant StructType Should be deleted once Spark releases UserDefinedTypes to @developerAPI

    internal types to show Rows as a relevant StructType Should be deleted once Spark releases UserDefinedTypes to @developerAPI

    Attributes
    protected
    Definition Classes
    AnnotatorModel
  2. type AnnotatorType = String
    Definition Classes
    HasOutputAnnotatorType

Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int
    Definition Classes
    AnyRef → Any
  3. final def $[T](param: Param[T]): T
    Attributes
    protected
    Definition Classes
    Params
  4. def $$[T](feature: StructFeature[T]): T
    Attributes
    protected
    Definition Classes
    HasFeatures
  5. def $$[K, V](feature: MapFeature[K, V]): Map[K, V]
    Attributes
    protected
    Definition Classes
    HasFeatures
  6. def $$[T](feature: SetFeature[T]): Set[T]
    Attributes
    protected
    Definition Classes
    HasFeatures
  7. def $$[T](feature: ArrayFeature[T]): Array[T]
    Attributes
    protected
    Definition Classes
    HasFeatures
  8. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  9. def _transform(dataset: Dataset[_], recursivePipeline: Option[PipelineModel]): DataFrame
    Attributes
    protected
    Definition Classes
    AnnotatorModel
  10. def afterAnnotate(dataset: DataFrame): DataFrame
    Attributes
    protected
    Definition Classes
    AnnotatorModel
  11. def annotate(annotations: Seq[Annotation]): Seq[Annotation]

    takes a document and annotations and produces new annotations of this annotator's annotation type

    takes a document and annotations and produces new annotations of this annotator's annotation type

    annotations

    Annotations that correspond to inputAnnotationCols generated by previous annotators if any

    returns

    any number of annotations processed for every input annotation. Not necessary one to one relationship

    Definition Classes
    BM25Model → HasSimpleAnnotate
  12. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  13. val avgDocLength: DoubleParam

    Average document length (in tokens) of the training corpus.

  14. val b: DoubleParam

    Length-normalization parameter b (carried over from BM25Approach).

  15. def beforeAnnotate(dataset: Dataset[_]): Dataset[_]
    Definition Classes
    BM25Model → AnnotatorModel
  16. val caseSensitive: BooleanParam

    Whether tokens are treated case-sensitively.

    Whether tokens are treated case-sensitively. This is fixed when the corpus statistics are computed by BM25Approach and carried onto the model: the IDF vocabulary keys are stored with that exact case handling. Changing it on a fitted model would desynchronize the query/document terms from the stored vocabulary and silently corrupt the scores, so it is deliberately read-only here — there is no setCaseSensitive on the model. The query is normalized with the same setting before scoring.

  17. final def checkSchema(schema: StructType, inputAnnotatorType: String): Boolean
    Attributes
    protected
    Definition Classes
    HasInputAnnotationCols
  18. final def clear(param: Param[_]): BM25Model.this.type
    Definition Classes
    Params
  19. def clone(): AnyRef
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( ... ) @native()
  20. def copy(extra: ParamMap): BM25Model

    requirement for annotators copies

    requirement for annotators copies

    Definition Classes
    RawAnnotator → Model → Transformer → PipelineStage → Params
  21. def copyValues[T <: Params](to: T, extra: ParamMap): T
    Attributes
    protected
    Definition Classes
    Params
  22. final def defaultCopy[T <: Params](extra: ParamMap): T
    Attributes
    protected
    Definition Classes
    Params
  23. def dfAnnotate: UserDefinedFunction

    Wraps annotate to happen inside SparkSQL user defined functions in order to act with org.apache.spark.sql.Column

    Wraps annotate to happen inside SparkSQL user defined functions in order to act with org.apache.spark.sql.Column

    returns

    udf function to be applied to inputCols using this annotator's annotate function as part of ML transformation

    Definition Classes
    HasSimpleAnnotate
  24. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  25. def equals(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  26. def explainParam(param: Param[_]): String
    Definition Classes
    Params
  27. def explainParams(): String
    Definition Classes
    Params
  28. final val extraInputCols: StringArrayParam
    Attributes
    protected
    Definition Classes
    HasInputAnnotationCols
  29. def extraValidate(structType: StructType): Boolean
    Attributes
    protected
    Definition Classes
    RawAnnotator
  30. def extraValidateMsg: String

    Override for additional custom schema checks

    Override for additional custom schema checks

    Attributes
    protected
    Definition Classes
    RawAnnotator
  31. final def extractParamMap(): ParamMap
    Definition Classes
    Params
  32. final def extractParamMap(extra: ParamMap): ParamMap
    Definition Classes
    Params
  33. val features: ArrayBuffer[Feature[_, _, _]]
    Definition Classes
    HasFeatures
  34. def finalize(): Unit
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  35. def get[T](feature: StructFeature[T]): Option[T]
    Attributes
    protected
    Definition Classes
    HasFeatures
  36. def get[K, V](feature: MapFeature[K, V]): Option[Map[K, V]]
    Attributes
    protected
    Definition Classes
    HasFeatures
  37. def get[T](feature: SetFeature[T]): Option[Set[T]]
    Attributes
    protected
    Definition Classes
    HasFeatures
  38. def get[T](feature: ArrayFeature[T]): Option[Array[T]]
    Attributes
    protected
    Definition Classes
    HasFeatures
  39. final def get[T](param: Param[T]): Option[T]
    Definition Classes
    Params
  40. def getAvgDocLength: Double

  41. def getB: Double

  42. def getCaseSensitive: Boolean

  43. final def getClass(): Class[_]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  44. final def getDefault[T](param: Param[T]): Option[T]
    Definition Classes
    Params
  45. def getIdf: Map[String, Double]

  46. def getInputCols: Array[String]

    returns

    input annotations columns currently used

    Definition Classes
    HasInputAnnotationCols
  47. def getK1: Double

  48. def getLazyAnnotator: Boolean
    Definition Classes
    CanBeLazy
  49. def getNumDocuments: Long

  50. final def getOrDefault[T](param: Param[T]): T
    Definition Classes
    Params
  51. final def getOutputCol: String

    Gets annotation column name going to generate

    Gets annotation column name going to generate

    Definition Classes
    HasOutputAnnotationCol
  52. def getParam(paramName: String): Param[Any]
    Definition Classes
    Params
  53. def getQuery: String

  54. def getQueryTokens: Array[String]

  55. final def hasDefault[T](param: Param[T]): Boolean
    Definition Classes
    Params
  56. def hasParam(paramName: String): Boolean
    Definition Classes
    Params
  57. def hasParent: Boolean
    Definition Classes
    Model
  58. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  59. val idf: MapFeature[String, Double]

    Learned inverse document frequency for every vocabulary term.

  60. def initializeLogIfNecessary(isInterpreter: Boolean, silent: Boolean): Boolean
    Attributes
    protected
    Definition Classes
    Logging
  61. def initializeLogIfNecessary(isInterpreter: Boolean): Unit
    Attributes
    protected
    Definition Classes
    Logging
  62. val inputAnnotatorTypes: Array[AnnotatorType]

    Input annotator type: TOKEN

    Input annotator type: TOKEN

    Definition Classes
    BM25Model → HasInputAnnotationCols
  63. final val inputCols: StringArrayParam

    columns that contain annotations necessary to run this annotator AnnotatorType is used both as input and output columns if not specified

    columns that contain annotations necessary to run this annotator AnnotatorType is used both as input and output columns if not specified

    Attributes
    protected
    Definition Classes
    HasInputAnnotationCols
  64. final def isDefined(param: Param[_]): Boolean
    Definition Classes
    Params
  65. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  66. final def isSet(param: Param[_]): Boolean
    Definition Classes
    Params
  67. def isTraceEnabled(): Boolean
    Attributes
    protected
    Definition Classes
    Logging
  68. val k1: DoubleParam

    Term-frequency saturation parameter k1 (carried over from BM25Approach).

  69. val lazyAnnotator: BooleanParam
    Definition Classes
    CanBeLazy
  70. def log: Logger
    Attributes
    protected
    Definition Classes
    Logging
  71. def logDebug(msg: ⇒ String, throwable: Throwable): Unit
    Attributes
    protected
    Definition Classes
    Logging
  72. def logDebug(msg: ⇒ String): Unit
    Attributes
    protected
    Definition Classes
    Logging
  73. def logError(msg: ⇒ String, throwable: Throwable): Unit
    Attributes
    protected
    Definition Classes
    Logging
  74. def logError(msg: ⇒ String): Unit
    Attributes
    protected
    Definition Classes
    Logging
  75. def logInfo(msg: ⇒ String, throwable: Throwable): Unit
    Attributes
    protected
    Definition Classes
    Logging
  76. def logInfo(msg: ⇒ String): Unit
    Attributes
    protected
    Definition Classes
    Logging
  77. def logName: String
    Attributes
    protected
    Definition Classes
    Logging
  78. def logTrace(msg: ⇒ String, throwable: Throwable): Unit
    Attributes
    protected
    Definition Classes
    Logging
  79. def logTrace(msg: ⇒ String): Unit
    Attributes
    protected
    Definition Classes
    Logging
  80. def logWarning(msg: ⇒ String, throwable: Throwable): Unit
    Attributes
    protected
    Definition Classes
    Logging
  81. def logWarning(msg: ⇒ String): Unit
    Attributes
    protected
    Definition Classes
    Logging
  82. def msgHelper(schema: StructType): String
    Attributes
    protected
    Definition Classes
    HasInputAnnotationCols
  83. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  84. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  85. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  86. val numDocuments: LongParam

    Total number of documents in the training corpus.

  87. def onWrite(path: String, spark: SparkSession): Unit
    Attributes
    protected
    Definition Classes
    ParamsAndFeaturesWritable
  88. val optionalInputAnnotatorTypes: Array[String]
    Definition Classes
    HasInputAnnotationCols
  89. val outputAnnotatorType: AnnotatorType

    Output annotator type: BM25_RANKINGS

    Output annotator type: BM25_RANKINGS

    Definition Classes
    BM25Model → HasOutputAnnotatorType
  90. final val outputCol: Param[String]
    Attributes
    protected
    Definition Classes
    HasOutputAnnotationCol
  91. lazy val params: Array[Param[_]]
    Definition Classes
    Params
  92. var parent: Estimator[BM25Model]
    Definition Classes
    Model
  93. val query: Param[String]

    The query that documents are scored against, as a raw string.

    The query that documents are scored against, as a raw string. This is a convenience: the model tokenizes it itself by splitting on non-word characters (\W+) and applying the model's case handling — it does not run the query through the same annotator pipeline used for the corpus.

    Analyzer-symmetry warning. BM25 only scores a query term when it matches a key in the learned IDF vocabulary, and those keys were produced by the pipeline placed in front of BM25Approach (e.g. Tokenizer, Normalizer, a stemmer/lemmatizer, ...). If that pipeline transforms tokens (stemming, lemmatization, punctuation stripping, ...), a raw-string query analyzed only by \W+ + lowercasing can fail to match and silently contribute nothing to the score. For anything beyond plain tokenization, analyze the query with the same pipeline and pass the resulting tokens via setQueryTokens.

    Either query or queryTokens must be set before transform; when both are set, queryTokens takes precedence (Default: empty).

  94. val queryTokens: StringArrayParam

    The query as a list of already-analyzed terms.

    The query as a list of already-analyzed terms. This is the recommended way to query when the corpus was built with a non-trivial pipeline: run the query string through the very same stages used for the documents (for example with a LightPipeline) and pass the resulting tokens here, so the query and the documents are analyzed identically. When non-empty, queryTokens overrides query. The model still applies its (read-only) case handling to these tokens so they line up with the stored IDF keys (Default: empty).

  95. def save(path: String): Unit
    Definition Classes
    MLWritable
    Annotations
    @Since( "1.6.0" ) @throws( ... )
  96. def set[T](feature: StructFeature[T], value: T): BM25Model.this.type
    Attributes
    protected
    Definition Classes
    HasFeatures
  97. def set[K, V](feature: MapFeature[K, V], value: Map[K, V]): BM25Model.this.type
    Attributes
    protected
    Definition Classes
    HasFeatures
  98. def set[T](feature: SetFeature[T], value: Set[T]): BM25Model.this.type
    Attributes
    protected
    Definition Classes
    HasFeatures
  99. def set[T](feature: ArrayFeature[T], value: Array[T]): BM25Model.this.type
    Attributes
    protected
    Definition Classes
    HasFeatures
  100. final def set(paramPair: ParamPair[_]): BM25Model.this.type
    Attributes
    protected
    Definition Classes
    Params
  101. final def set(param: String, value: Any): BM25Model.this.type
    Attributes
    protected
    Definition Classes
    Params
  102. final def set[T](param: Param[T], value: T): BM25Model.this.type
    Definition Classes
    Params
  103. def setAvgDocLength(value: Double): BM25Model.this.type

  104. def setB(value: Double): BM25Model.this.type

  105. def setDefault[T](feature: StructFeature[T], value: () ⇒ T): BM25Model.this.type
    Attributes
    protected
    Definition Classes
    HasFeatures
  106. def setDefault[K, V](feature: MapFeature[K, V], value: () ⇒ Map[K, V]): BM25Model.this.type
    Attributes
    protected
    Definition Classes
    HasFeatures
  107. def setDefault[T](feature: SetFeature[T], value: () ⇒ Set[T]): BM25Model.this.type
    Attributes
    protected
    Definition Classes
    HasFeatures
  108. def setDefault[T](feature: ArrayFeature[T], value: () ⇒ Array[T]): BM25Model.this.type
    Attributes
    protected
    Definition Classes
    HasFeatures
  109. final def setDefault(paramPairs: ParamPair[_]*): BM25Model.this.type
    Attributes
    protected
    Definition Classes
    Params
  110. final def setDefault[T](param: Param[T], value: T): BM25Model.this.type
    Attributes
    protected[org.apache.spark.ml]
    Definition Classes
    Params
  111. def setExtraInputCols(value: Array[String]): BM25Model.this.type
    Definition Classes
    HasInputAnnotationCols
  112. def setIdf(value: Map[String, Double]): BM25Model.this.type

  113. final def setInputCols(value: String*): BM25Model.this.type
    Definition Classes
    HasInputAnnotationCols
  114. def setInputCols(value: Array[String]): BM25Model.this.type

    Overrides required annotators column if different than default

    Overrides required annotators column if different than default

    Definition Classes
    HasInputAnnotationCols
  115. def setK1(value: Double): BM25Model.this.type

  116. def setLazyAnnotator(value: Boolean): BM25Model.this.type
    Definition Classes
    CanBeLazy
  117. def setNumDocuments(value: Long): BM25Model.this.type

  118. final def setOutputCol(value: String): BM25Model.this.type

    Overrides annotation column name when transforming

    Overrides annotation column name when transforming

    Definition Classes
    HasOutputAnnotationCol
  119. def setParent(parent: Estimator[BM25Model]): BM25Model
    Definition Classes
    Model
  120. def setQuery(value: String): BM25Model.this.type

  121. def setQueryTokens(value: Array[String]): BM25Model.this.type

  122. final def synchronized[T0](arg0: ⇒ T0): T0
    Definition Classes
    AnyRef
  123. def toString(): String
    Definition Classes
    Identifiable → AnyRef → Any
  124. final def transform(dataset: Dataset[_]): DataFrame

    Given requirements are met, this applies ML transformation within a Pipeline or stand-alone Output annotation will be generated as a new column, previous annotations are still available separately metadata is built at schema level to record annotations structural information outside its content

    Given requirements are met, this applies ML transformation within a Pipeline or stand-alone Output annotation will be generated as a new column, previous annotations are still available separately metadata is built at schema level to record annotations structural information outside its content

    dataset

    Dataset[Row]

    Definition Classes
    AnnotatorModel → Transformer
  125. def transform(dataset: Dataset[_], paramMap: ParamMap): DataFrame
    Definition Classes
    Transformer
    Annotations
    @Since( "2.0.0" )
  126. def transform(dataset: Dataset[_], firstParamPair: ParamPair[_], otherParamPairs: ParamPair[_]*): DataFrame
    Definition Classes
    Transformer
    Annotations
    @Since( "2.0.0" ) @varargs()
  127. final def transformSchema(schema: StructType): StructType

    requirement for pipeline transformation validation.

    requirement for pipeline transformation validation. It is called on fit()

    Definition Classes
    RawAnnotator → PipelineStage
  128. def transformSchema(schema: StructType, logging: Boolean): StructType
    Attributes
    protected
    Definition Classes
    PipelineStage
    Annotations
    @DeveloperApi()
  129. val uid: String
    Definition Classes
    BM25Model → Identifiable
  130. def validate(schema: StructType): Boolean

    takes a Dataset and checks to see if all the required annotation types are present.

    takes a Dataset and checks to see if all the required annotation types are present.

    schema

    to be validated

    returns

    True if all the required types are present, else false

    Attributes
    protected
    Definition Classes
    RawAnnotator
  131. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  132. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  133. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... ) @native()
  134. def wrapColumnMetadata(col: Column): Column
    Attributes
    protected
    Definition Classes
    RawAnnotator
  135. def write: MLWriter
    Definition Classes
    ParamsAndFeaturesWritable → DefaultParamsWritable → MLWritable

Inherited from HasSimpleAnnotate[BM25Model]

Inherited from AnnotatorModel[BM25Model]

Inherited from CanBeLazy

Inherited from RawAnnotator[BM25Model]

Inherited from HasOutputAnnotationCol

Inherited from HasInputAnnotationCols

Inherited from HasOutputAnnotatorType

Inherited from ParamsAndFeaturesWritable

Inherited from HasFeatures

Inherited from DefaultParamsWritable

Inherited from MLWritable

Inherited from Model[BM25Model]

Inherited from Transformer

Inherited from PipelineStage

Inherited from Logging

Inherited from Params

Inherited from Serializable

Inherited from Serializable

Inherited from Identifiable

Inherited from AnyRef

Inherited from Any

Parameters

Annotator types

Required input and expected output annotator types

Parameter setters

Parameter getters

Ungrouped