/

labelScorer

label​Scorer:​* components compute a numerical score for each label (such as document or term frequency). You can use label scores to output additional information about labels for display or filtering purposes or to recompute scores of a set of labels using information from different fields or document scopes.

You can use the following label scorers in your analysis requests:

label​Scorer:​by​Vector​Similarity

Computes the similarity between the label's embedding vector and another vector you provide.

label​Scorer:​by​Vectors​Similarity

Computes the similarity between the label's embedding vector and a set of vectors you provide.

label​Scorer:​composite

Aggregates the scores computed by the scorers you provide into a single score.

label​Scorer:​df

Computes the label's document frequency (DF).

label​Scorer:​identity

Returns the label's original weight.

label​Scorer:​idf

Computes the label's inverse document frequency (IDF).

label​Scorer:​probability​Ratio

Computes the probability ratio coefficient, which you can use to identify labels that are more probable to appear in the subset of documents of your choice than in the whole collection.

label​Scorer:​tf

Computes the label's term frequency (TF).

Here is an example where we use the labels:​scored stage to recompute the weights of labels from the title field, using document frequencies retrieved from the abstract field of the reference arXiv data set. 

{
  "stages": {
    "documents": {
      "type": "documents:byQuery",
      "query": {
        "type": "query:string",
        "query": "photon"
      },
      "limit": 500
    },
    "tf": {
      "type": "labels:scored",
      "scorer": {
        "type": "labelScorer:df",
        "fields": {
          "type": "featureFields:simple",
          "fields": [
            "abstract$phrases"
          ]
        },
        "scope": {
          "type": "documents:reference",
          "use": "documents"
        }
      },
      "labels": {
        "type": "labels:fromDocuments",
        "documents": {
          "type": "documents:reference",
          "use": "documents"
        },
        "maxLabels": {
          "type": "labelCount:fixed",
          "value": 10
        },
        "labelAggregator": {
          "type": "labelAggregator:topWeight",
          "labelCollector": {
            "type": "labelCollector:topFromFeatureFields",
            "fields": {
              "type": "featureFields:simple",
              "fields": [
                "title$phrases"
              ]
            }
          }
        }
      }
    }
  },
  "output": {
    "stages": [
      "tf"
    ]
  }
}

The result of the above request, on the reference Arxiv index:

{
  "result" : {
    "tf" : {
      "labels" : [
        {
          "label" : "single-photon",
          "weight" : 1172.25
        },
        {
          "label" : "entangled photons",
          "weight" : 356.364
        },
        {
          "label" : "photon-photon",
          "weight" : 525.168
        },
        {
          "label" : "two-photon",
          "weight" : 759.618
        },
        {
          "label" : "interference",
          "weight" : 403.254
        },
        {
          "label" : "collisions",
          "weight" : 403.254
        },
        {
          "label" : "detector",
          "weight" : 637.704
        },
        {
          "label" : "entanglement",
          "weight" : 487.656
        },
        {
          "label" : "dark photon",
          "weight" : 187.56
        }
      ]
    }
  }
}

label​Scorer:​by​Vector​Similarity

Computes the similarity between the label's embedding vector and another vector you provide.

{
  "type": "labelScorer:byVectorSimilarity",
  "failIfEmbeddingsNotAvailable": true,
  "vector": {
    "type": "vector:reference",
    "auto": true
  }
}

fail​If​Embeddings​Not​Available

Type
boolean
Default
true
Required
no

Determines the behavior of this stage if the index does not contain document embeddings.

If the index does not contain document embeddings and fail​If​Embeddings​Not​Available is:

true
this stage fails and logs an error.
false
this stage returns zero scores for all labels.

vector

Type
vector
Default
{
  "type": "vector:reference",
  "auto": true
}
Required
no

The vector against which to compute the similarity.

label​Scorer:​by​Vectors​Similarity

Computes the similarity between the label's embedding vector and a set of vectors you provide.

{
  "type": "labelScorer:byVectorsSimilarity",
  "failIfEmbeddingsNotAvailable": true,
  "minSimilarity": 0,
  "vectors": {
    "type": "vectors:reference",
    "auto": true
  }
}

fail​If​Embeddings​Not​Available

Type
boolean
Default
true
Required
no

Determines the behavior of this stage if the index does not contain document embeddings.

The label's score is the sum of the similarities against the vectors you provide. Similarity between the label's vector and the particular input vector is included in the score only when the similarity is larger than min​Similarity.

If the index does not contain document embeddings and fail​If​Embeddings​Not​Available is:

true
this stage fails and logs an error.
false
this stage returns zero scores for all labels.

min​Similarity

Type
number
Default
0
Required
no

The minimum similarity between the label's and input vector for the similarity to be included in the label's score.

vectors

Type
vectors
Default
{
  "type": "vectors:reference",
  "auto": true
}
Required
no

The vectors against which to compute the label's vector similarities.

label​Scorer:​composite

Computes an aggregate score that is a geometric mean of values returned by the scorers you provide.

{
  "type": "labelScorer:composite",
  "scorers": []
}

scorers

Type
array of labelScorer
Default
[]
Required
no

An array of scorers from which an aggregate should be computed.

label​Scorer:​df

Computes label document frequency (DF). Document frequency corresponds to the number of documents the label occurred in (contrary to the term frequency, multiple occurrences within a single document count as one). 

{
  "type": "labelScorer:df",
  "fields": {
    "type": "featureFields:reference",
    "auto": true
  },
  "scope": {
    "type": "documents:reference",
    "auto": true
  }
}

fields

Type
featureFields
Default
{
  "type": "featureFields:reference",
  "auto": true
}
Required
no

A reference to feature fields used to retrieve label statistics from.

scope

Type
documents
Default
{
  "type": "documents:reference",
  "auto": true
}
Required
no

A reference to a set of documents used to compute label statistics from.

label​Scorer:​identity

This label scorer does not change the externally provided score of the label, it is an identity scorer.

{
  "type": "labelScorer:identity"
}

label​Scorer:​idf

Computes the inverse document frequency (IDF) for each label.

{
  "type": "labelScorer:idf",
  "fields": {
    "type": "featureFields:reference",
    "auto": true
  },
  "scope": {
    "type": "documents:reference",
    "auto": true
  }
}

The inverse document frequency is computed using the following formula:

log N + 1 min ( N , df(label) ) + 1

where N is the total number of unique documents in scope and df(label) is the number of documents with occurrences of the label.

fields

Type
featureFields
Default
{
  "type": "featureFields:reference",
  "auto": true
}
Required
no

A reference to feature fields used to retrieve label statistics from.

scope

Type
documents
Default
{
  "type": "documents:reference",
  "auto": true
}
Required
no

A reference to a set of documents used to compute label statistics from.

label​Scorer:​probability​Ratio

Computes label's probability ratio coefficient, which you can use to identify labels that are more probable to appear in the subset of documents of your choice than in the whole collection. 

{
  "type": "labelScorer:probabilityRatio",
  "baseScope": {
    "type": "documents:reference",
    "auto": true
  },
  "fields": {
    "type": "featureFields:reference",
    "auto": true
  },
  "referenceScope": {
    "type": "documents:sample",
    "limit": 10000,
    "query": {
      "type": "query:all"
    },
    "randomSeed": 0,
    "samplingRatio": 1
  }
}

The probability ratio coefficient is computed as a ratio between the given label's probability of occurrence in the base scope against the reference scope. Labels with higher probability of occurrence in the base​Scope (compared to their probability of occurrence in the reference​Scope) should receive higher scores:

ratio = P ( label , base scope ) P ( label , reference scope )

The probability P for each scope is computed using the following formula, where N is equal to the number of unique labels being scored (a form of additive probability smoothing function):

P ( label , scope ) = tf(label) + 1 + N ∑ i ∈ scope labels tf(i) + 1 + N

base​Scope

Type
documents
Default
{
  "type": "documents:reference",
  "auto": true
}
Required
no

A reference to a set of documents providing the "focus" document scope.

fields

Type
featureFields
Default
{
  "type": "featureFields:reference",
  "auto": true
}
Required
no

A reference to feature fields used to retrieve label statistics from.

reference​Scope

Type
documents
Default
{
  "type": "documents:sample",
  "limit": 10000,
  "query": {
    "type": "query:all"
  },
  "randomSeed": 0,
  "samplingRatio": 1
}
Required
no

A reference to a set of documents providing the "reference" scope.

label​Scorer:​tf

Computes the term frequency (TF) for each label. The term frequency is the number of times a given label occurred throughout the scope (including repetitions within the document's fields). 

{
  "type": "labelScorer:tf",
  "fields": {
    "type": "featureFields:reference",
    "auto": true
  },
  "scope": {
    "type": "documents:reference",
    "auto": true
  }
}

fields

Type
featureFields
Default
{
  "type": "featureFields:reference",
  "auto": true
}
Required
no

A reference to feature fields used to retrieve label statistics from.

scope

Type
documents
Default
{
  "type": "documents:reference",
  "auto": true
}
Required
no

A reference to a set of documents used to compute label statistics from.

Consumers of label​Scorer:​*

The following stages and components take label​Scorer:​* as input:

Stage or component Property
label​Scorer:​composite
  • scorers
    • labels:​scored
  • scorer
    •