org.apache.lucene.search.Explanation Java Examples

public Explanation explain(LeafReaderContext context, Weight childWeight) throws IOException {
  int prevParentDoc = parentBits.prevSetBit(parentApproximation.docID() - 1);
  int start = context.docBase + prevParentDoc + 1; // +1 b/c prevParentDoc is previous parent doc
  int end = context.docBase + parentApproximation.docID() - 1; // -1 b/c parentDoc is parent doc

  Explanation bestChild = null;
  int matches = 0;
  for (int childDoc = start; childDoc <= end; childDoc++) {
    Explanation child = childWeight.explain(context, childDoc - context.docBase);
    if (child.isMatch()) {
      matches++;
      if (bestChild == null || child.getValue().floatValue() > bestChild.getValue().floatValue()) {
        bestChild = child;
      }
    }
  }

  return Explanation.match(score(), String.format(Locale.ROOT,
      "Score based on %d child docs in range from %d to %d, best match:", matches, start, end), bestChild
  );
}
 

@Override
public Explanation explain(LeafReaderContext context, int doc) throws IOException {
    Explanation subQueryExpl = subQueryWeight.explain(context, doc);
    if (!subQueryExpl.isMatch()) {
        return subQueryExpl;
    }
    Explanation expl;
    if (function != null) {
        Explanation functionExplanation = function.getLeafScoreFunction(context).explainScore(doc, subQueryExpl);
        expl = combineFunction.explain(subQueryExpl, functionExplanation, maxBoost);
    } else {
        expl = subQueryExpl;
    }
    if (minScore != null && minScore > expl.getValue()) {
        expl = Explanation.noMatch("Score value is too low, expected at least " + minScore + " but got " + expl.getValue(), expl);
    }
    return expl;
}
 

@Override
public Explanation explain(BasicStats stats, double tfn, double aeTimes1pTfn) {
  double F = stats.getTotalTermFreq();
  double N = stats.getNumberOfDocuments();
  double ne = N * (1 - Math.pow((N - 1) / N, F));
  Explanation explNe = Explanation.match((float) ne,
      "ne, computed as N * (1 - Math.pow((N - 1) / N, F)) from:",
      Explanation.match((float) F,
          "F, total number of occurrences of term across all docs"),
      Explanation.match((float) N,
          "N, total number of documents with field"));

  return Explanation.match(
      (float) (score(stats, tfn, aeTimes1pTfn) * (1 + tfn) / aeTimes1pTfn),
      getClass().getSimpleName() + ", computed as " +
          "tfn * log2((N + 1) / (ne + 0.5)) from:",
      Explanation.match((float) tfn, "tfn, normalized term frequency"),
      explNe);
}
 

@Test
public void testCustom() throws Exception {

  final LTRScoringModel model = createModelFromFiles("neuralnetworkmodel_custom.json",
      "neuralnetworkmodel_features.json");

  final float featureValue1 = 4f;
  final float featureValue2 = 2f;
  final float[] featureValues = { featureValue1, featureValue2 };

  final double expectedScore = (featureValue1+featureValue2) * 42f;
  float actualScore = model.score(featureValues);
  assertEquals(expectedScore, actualScore, 0.001);

  final List<Explanation> explanations = new ArrayList<Explanation>();
  for (int ii=0; ii<featureValues.length; ++ii)
  {
    explanations.add(Explanation.match(featureValues[ii], ""));
  }
  final Explanation explanation = model.explain(null, 0, actualScore, explanations);
  assertEquals(actualScore+" = (name=neuralnetworkmodel_custom"+
      ",featureValues=[constantFour=4.0,constantTwo=2.0]"+
      ",layers=[(matrix=1x2,activation=answer)]"+
      ")\n",
      explanation.toString());
}
 

private Explanation explainScore(Explanation freq, long encodedNorm, float[] normTable) {
  List<Explanation> subs = new ArrayList<Explanation>();
  if (boost != 1F) {
    subs.add(Explanation.match(boost, "boost"));
  }
  subs.add(idf);
  Explanation tf = Explanation.match(tf(freq.getValue().floatValue()), "tf(freq="+freq.getValue()+"), with freq of:", freq);
  subs.add(tf);

  float norm = normTable[(int) (encodedNorm & 0xFF)];
  
  Explanation fieldNorm = Explanation.match(norm, "fieldNorm");
  subs.add(fieldNorm);
  
  return Explanation.match(
      queryWeight * tf.getValue().floatValue() * norm,
      "score(freq="+freq.getValue()+"), product of:",
      subs);
}
 

@Override
public Explanation explain(LeafReaderContext context, int doc) throws IOException {
  SortedDocValues values = DocValues.getSorted(context.reader(), joinField);
  if (values == null) {
    return Explanation.noMatch("Not a match");
  }

  if (values.advance(doc) != doc) {
    return Explanation.noMatch("Not a match");
  }
  int segmentOrd = values.ordValue();
  BytesRef joinValue = values.lookupOrd(segmentOrd);

  int ord;
  if (globalOrds != null) {
    ord = (int) globalOrds.getGlobalOrds(context.ord).get(segmentOrd);
  } else {
    ord = segmentOrd;
  }
  if (foundOrds.get(ord) == false) {
    return Explanation.noMatch("Not a match, join value " + Term.toString(joinValue));
  }

  return Explanation.match(score(), "A match, join value " + Term.toString(joinValue));
}
 

@Override
public Explanation explain(LeafReaderContext context, int doc) throws IOException {
  SortedDocValues values = DocValues.getSorted(context.reader(), joinField);
  if (values == null) {
    return Explanation.noMatch("Not a match");
  }
  if (values.advance(doc) != doc) {
    return Explanation.noMatch("Not a match");
  }

  int segmentOrd = values.ordValue();
  BytesRef joinValue = values.lookupOrd(segmentOrd);

  int ord;
  if (globalOrds != null) {
    ord = (int) globalOrds.getGlobalOrds(context.ord).get(segmentOrd);
  } else {
    ord = segmentOrd;
  }
  if (collector.match(ord) == false) {
    return Explanation.noMatch("Not a match, join value " + Term.toString(joinValue));
  }

  float score = collector.score(ord);
  return Explanation.match(score, "A match, join value " + Term.toString(joinValue));
}
 

/** Render an explanation as HTML. */
public static String toHtml(Explanation explanation) {
  StringBuilder buffer = new StringBuilder();
  buffer.append("<ul>\n");

  buffer.append("<li>");
  buffer.append(explanation.getValue()).append(" = ").append(explanation.getDescription());
  buffer.append("<br />\n");

  Explanation[] details = explanation.getDetails();
  for (int i = 0 ; i < details.length; i++) {
    buffer.append(toHtml(details[i]));
  }

  buffer.append("</li>\n");
  buffer.append("</ul>\n");

  return buffer.toString();
}
 

public void testScoreModifyingSource() throws Exception {

    BooleanQuery bq = new BooleanQuery.Builder()
        .add(new TermQuery(new Term(TEXT_FIELD, "first")), BooleanClause.Occur.SHOULD)
        .add(new TermQuery(new Term(TEXT_FIELD, "text")), BooleanClause.Occur.SHOULD)
        .build();
    TopDocs plain = searcher.search(bq, 1);

    FunctionScoreQuery fq = FunctionScoreQuery.boostByValue(bq, DoubleValuesSource.fromIntField("iii"));

    QueryUtils.check(random(), fq, searcher, rarely());

    int[] expectedDocs = new int[]{ 4, 7, 9, 8, 12 };
    TopDocs docs = searcher.search(fq, 5);
    assertEquals(plain.totalHits.value, docs.totalHits.value);
    for (int i = 0; i < expectedDocs.length; i++) {
      assertEquals(expectedDocs[i], docs.scoreDocs[i].doc);
    }

    Explanation expl = searcher.explain(fq, 4);
    assertTrue(expl.toString().contains("first"));
    assertTrue(expl.toString().contains("iii"));

  }
 

private void debugExplainResults(String indexName, Hits hits, IndexSearcher searcher,
        Query q, Set<Term> queryTerms)
    throws IOException {
    log.debug("Parsed Query is " + q.toString());
    log.debug("Looking at index:  " + indexName);
    for (int i = 0; i < hits.length(); i++) {
        if ((i < 10)) {
            Document doc = hits.doc(i);
            Float score = hits.score(i);
            Explanation ex = searcher.explain(q, hits.id(i));
            log.debug("Looking at hit<" + i + ", " + hits.id(i) + ", " + score +
                    ">: " + doc);
            log.debug("Explanation: " + ex);
            MatchingField match = new MatchingField(q.toString(), doc, queryTerms);
            String fieldName = match.getFieldName();
            String fieldValue = match.getFieldValue();
            log.debug("Guessing that matched fieldName is " + fieldName + " = " +
                    fieldValue);
        }
    }
}
 

@Override
public Explanation explain(LeafReaderContext context, int doc) throws IOException {
    Scorer scorer = this.scorer(context);
    int newDoc = scorer.iterator().advance(doc);
    if (newDoc == doc) {
        return Explanation
                .match(scorer.score(), "weight(" + this.getQuery() + " in doc " + newDoc + ")");
    }
    return Explanation.noMatch("no matching term");
}
 

public final Explanation explain(BasicStats stats) {
  return Explanation.match(
      lambda(stats),
      getClass().getSimpleName()
          + ", computed as (F + 1) / (N + 1) from:",
      Explanation.match(stats.getTotalTermFreq(),
          "F, total number of occurrences of term across all documents"),
      Explanation.match(stats.getNumberOfDocuments(),
          "N, total number of documents with field"));
}
 

protected Explanation idfExplain(BasicStats stats, double freq, double docLen){
  return Explanation.match((float) idf(stats, freq, docLen),
      "idf, inverted document frequency computed as log((N + 1) / n) from:",
      Explanation.match((float) stats.getNumberOfDocuments(),
          "N, total number of documents with field"),
      Explanation.match((float) stats.getDocFreq(),
          "n, number of documents containing term"));
}
 

@Test
void testConvertAttribute() {
  when(dataService.getEntityType(ATTRIBUTE_META_DATA)).thenReturn(attributeMetadata);
  Explanation explanation = Explanation.match(0.3f, "match");
  when(elasticSearchExplainService.explain(query, attributeMetadata, "attrID"))
      .thenReturn(explanation);
  when(elasticSearchExplainService.findQueriesFromExplanation(
          collectExpandedQueryMap, explanation))
      .thenReturn(explainedQueryStrings);

  assertEquals(
      explainedQueryStrings,
      semanticSearchService.convertAttributeToExplainedAttribute(
          attribute, collectExpandedQueryMap, query));
}
 

@Override
public Explanation explain(final LeafReaderContext context, final int doc) throws IOException {

    Scorer scorer = scorer(context);
    if (scorer != null) {
        int newDoc = scorer.iterator().advance(doc);
        if (newDoc == doc) {

            Explanation scoreExplanation = Explanation.match(score, "product of:",
                    Explanation.match(queryBoost, "queryBoost"),
                    Explanation.match(fieldBoost, "fieldBoost")
            );

            Explanation result = Explanation.match(scorer.score(),
                    "weight(" + getQuery() + " in " + doc + ") ["
                            + FieldBoostTermQuery.this.fieldBoost.getClass().getSimpleName() + "], result of:",
                    scoreExplanation

            );



            return result;
        }
    }
    return Explanation.noMatch("no matching term");
}
 

private void buildExplanation(XContentBuilder builder, Explanation explanation) throws IOException {
    builder.startObject();
    builder.field(Fields.VALUE, explanation.getValue());
    builder.field(Fields.DESCRIPTION, explanation.getDescription());
    Explanation[] innerExps = explanation.getDetails();
    if (innerExps != null) {
        builder.startArray(Fields.DETAILS);
        for (Explanation exp : innerExps) {
            buildExplanation(builder, exp);
        }
        builder.endArray();
    }
    builder.endObject();
}
 

protected Explanation idfExplain(BasicStats stats, double freq, double docLen){
  return Explanation.match((float) idf(stats, freq, docLen),
      "idf, inverted document frequency computed as " +
          "Math.pow((N + 1) / n, k) from:",
      Explanation.match((float) stats.getNumberOfDocuments(),
          "N, total number of documents with field"),
      Explanation.match((float) stats.getDocFreq(),
          "n, number of documents containing term"));
}
 

public List<String> explanations( ){
    List<String> toReturn = new ArrayList<String>( );
    validateQuery( );
    fullTextQuery.setProjection( FullTextQuery.EXPLANATION );
    for ( Object obj : fullTextQuery.list( ) ) {
        toReturn.add( ( (Explanation ) ( (Object[] ) obj )[0] ).toHtml( ) );
    };
    fullTextQuery.setProjection( FullTextQuery.THIS );
    return toReturn;

}
 

@Override
public Explanation explain(LeafReaderContext context, int doc,
    float finalScore, List<Explanation> featureExplanations) {
  final List<Explanation> details = new ArrayList<>();
  int index = 0;

  for (final Explanation featureExplain : featureExplanations) {
    final List<Explanation> featureDetails = new ArrayList<>();
    featureDetails.add(Explanation.match(featureToWeight[index],
        "weight on feature"));
    featureDetails.add(featureExplain);

    details.add(Explanation.match(featureExplain.getValue().floatValue()
        * featureToWeight[index], "prod of:", featureDetails));
    index++;
  }

  return Explanation.match(finalScore, toString()
      + " model applied to features, sum of:", details);
}
 

public TFIDFScorer(float boost, Explanation idf, float[] normTable) {
  // TODO: Validate?
  this.idf = idf;
  this.boost = boost;
  this.queryWeight = boost * idf.getValue().floatValue();
  this.normTable = normTable;
}
 

@Override
public final SimScorer scorer(float boost, CollectionStatistics collectionStats, TermStatistics... termStats) {
  Explanation idf = termStats.length == 1 ? idfExplain(collectionStats, termStats[0]) : idfExplain(collectionStats, termStats);
  float avgdl = avgFieldLength(collectionStats);

  float[] cache = new float[256];
  for (int i = 0; i < cache.length; i++) {
    cache[i] = 1f / (k1 * ((1 - b) + b * LENGTH_TABLE[i] / avgdl));
  }
  return new BM25Scorer(boost, k1, b, idf, avgdl, cache);
}
 

BM25Scorer(float boost, float k1, float b, Explanation idf, float avgdl, float[] cache) {
  this.boost = boost;
  this.idf = idf;
  this.avgdl = avgdl;
  this.k1 = k1;
  this.b = b;
  this.cache = cache;
  this.weight = boost * idf.getValue().floatValue();
}
 

protected Explanation idfExplain(BasicStats stats, double freq, double docLen){
  return Explanation.match((float) idf(stats, freq, docLen),
      "idf, inverted document frequency computed as log((N + 1) / n) from:",
      Explanation.match((float) stats.getNumberOfDocuments(),
          "N, total number of documents with field"),
      Explanation.match((float) stats.getDocFreq(),
          "n, number of documents containing term"));
}
 

@Override
public Explanation explain(LeafReaderContext context, int doc) throws IOException {
  ToChildBlockJoinScorer scorer = (ToChildBlockJoinScorer) scorer(context);
  if (scorer != null && scorer.iterator().advance(doc) == doc) {
    int parentDoc = scorer.getParentDoc();
    return Explanation.match(
      scorer.score(), 
      String.format(Locale.ROOT, "Score based on parent document %d", parentDoc + context.docBase), 
      in.explain(context, parentDoc)
    );
  }
  return Explanation.noMatch("Not a match");
}
 

protected Explanation idfExplain(BasicStats stats, double freq, double docLen){
  return Explanation.match((float) idf(stats, freq, docLen),
      "idf, inverted document frequency computed as " +
          "Math.pow((N + 1) / n, k) from:",
      Explanation.match((float) stats.getNumberOfDocuments(),
          "N, total number of documents with field"),
      Explanation.match((float) stats.getDocFreq(),
          "n, number of documents containing term"));
}
 

@Override
public Explanation explain(LeafReaderContext context, int doc) throws IOException {
  BlockJoinScorer scorer = (BlockJoinScorer) scorer(context);
  if (scorer != null && scorer.iterator().advance(doc) == doc) {
    return scorer.explain(context, in);
  }
  return Explanation.noMatch("Not a match");
}
 

public Explanation explain(Query<Entity> q, EntityType entityType, Object entityId) {
  Explanation explanation = elasticsearchService.explain(entityType, entityId, q);
  if (explanation != null) {
    if (LOG.isDebugEnabled()) {
      LOG.debug(explanation.toString());
    }

    return explanation;
  }
  return null;
}
 

@Override
protected void explain(
    List<Explanation> subs, BasicStats stats, double freq, double docLen) {
  if (stats.getBoost() != 1.0d) {
    subs.add(Explanation.match((float)stats.getBoost(), "boost, query boost"));
  }
  Explanation normExpl = normalization.explain(stats, freq, docLen);
  Explanation lambdaExpl = lambda.explain(stats);
  subs.add(normExpl);
  subs.add(lambdaExpl);
  subs.add(distribution.explain(stats, normExpl.getValue().floatValue(), lambdaExpl.getValue().floatValue()));
}
 

public Explanation explain(Similarity similarity, Query query, int doc) {
  if (!isMatched(doc)) {
    return null;
  }
  ComplexExplanation result = new ComplexExplanation();
  result.setDescription(
      "weight(" + query + " in " + doc + ") [" + similarity.getClass().getSimpleName() + "], result of:");
  Explanation scoreExplanation = docScorer.explain(doc, new Explanation(matchedFreq, "termFreq=" + matchedFreq));
  result.addDetail(scoreExplanation);
  result.setValue(scoreExplanation.getValue());
  result.setMatch(true);
  return result;
}
 

@Override
public Explanation explain(AtomicReaderContext context, int doc) throws IOException {
  FlexibleScorer scorer = (FlexibleScorer) scorer(context, context.reader().getLiveDocs());
  if (scorer != null) {
    int newDoc = scorer.advance(doc);
    if (newDoc == doc) {
      FlexibleScoreModelStrategy strategy = scorer.getStrategy();
      strategy.prepare(0, 0, true);
      return strategy.explain(similarity, query, doc);
    }
  }
  return new ComplexExplanation(false, 0.0f, "no matching term");
}