org.apache.solr.ltr.model.LinearModel Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of solr-ltr Show documentation
Apache Solr Learning to Rank Package
There is a newer version: 9.7.0
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.solr.ltr.model;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import org.apache.lucene.index.LeafReaderContext;
import org.apache.lucene.search.Explanation;
import org.apache.solr.ltr.feature.Feature;
import org.apache.solr.ltr.norm.Normalizer;

/**
 * A scoring model that computes scores using a dot product. Example models are RankSVM and
 * Pranking.
 *
 * Example configuration:
 *
 * 
 * {
 *   "class" : "org.apache.solr.ltr.model.LinearModel",
 *   "name" : "myModelName",
 *   "features" : [
 *     { "name" : "userTextTitleMatch" },
 *     { "name" : "originalScore" },
 *     { "name" : "isBook" }
 *   ],
 *   "params" : {
 *     "weights" : {
 *       "userTextTitleMatch" : 1.0,
 *       "originalScore" : 0.5,
 *       "isBook" : 0.1
 *     }
 *   }
 * }
 * 
 *
 * Training libraries:
 *
 * 

 *   LIBLINEAR -- A Library for Large
 *       Linear Classification
 * 
 *
 * 
 *   LIBSVM -- A Library for Support Vector
 *       Machines
 * 
 *
 * Background reading:
 *
 * 

 *   Thorsten
 *       Joachims. Optimizing Search Engines Using Clickthrough Data. Proceedings of the ACM
 *       Conference on Knowledge Discovery and Data Mining (KDD), ACM, 2002.
 * 
 *
 * 
 *   Koby Crammer and
 *       Yoram Singer. Pranking with Ranking. Advances in Neural Information Processing Systems
 *       (NIPS), 2001.
 * 
 */
public class LinearModel extends LTRScoringModel {

  /**
   * featureToWeight is part of the LTRScoringModel params map and therefore here it does not
   * individually influence the class hashCode, equals, etc.
   */
  protected Float[] featureToWeight;

  public void setWeights(Object weights) {
    @SuppressWarnings({"unchecked"})
    final Map modelWeights = (Map) weights;
    for (int ii = 0; ii < features.size(); ++ii) {
      final String key = features.get(ii).getName();
      final Number val = modelWeights.get(key);
      featureToWeight[ii] = (val == null ? null : val.floatValue());
    }
  }

  public LinearModel(
      String name,
      List features,
      List norms,
      String featureStoreName,
      List allFeatures,
      Map params) {
    super(name, features, norms, featureStoreName, allFeatures, params);
    featureToWeight = new Float[features.size()];
  }

  @Override
  protected void validate() throws ModelException {
    super.validate();

    final ArrayList missingWeightFeatureNames = new ArrayList<>();
    for (int i = 0; i < features.size(); ++i) {
      if (featureToWeight[i] == null) {
        missingWeightFeatureNames.add(features.get(i).getName());
      }
    }
    if (missingWeightFeatureNames.size() == features.size()) {
      throw new ModelException("Model " + name + " doesn't contain any weights");
    }
    if (!missingWeightFeatureNames.isEmpty()) {
      throw new ModelException(
          "Model " + name + " lacks weight(s) for " + missingWeightFeatureNames);
    }
  }

  @Override
  public float score(float[] modelFeatureValuesNormalized) {
    float score = 0;
    for (int i = 0; i < modelFeatureValuesNormalized.length; ++i) {
      score += modelFeatureValuesNormalized[i] * featureToWeight[i];
    }
    return score;
  }

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

    for (final Explanation featureExplain : featureExplanations) {
      final List 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);
  }

  @Override
  public String toString() {
    final StringBuilder sb = new StringBuilder(getClass().getSimpleName());
    sb.append("(name=").append(getName());
    sb.append(",featureWeights=[");
    for (int ii = 0; ii < features.size(); ++ii) {
      if (ii > 0) {
        sb.append(',');
      }
      final String key = features.get(ii).getName();
      sb.append(key).append('=').append(featureToWeight[ii]);
    }
    sb.append("])");
    return sb.toString();
  }
}