001/*
002 * Copyright (c) 2015-2020, Oracle and/or its affiliates. All rights reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.tribuo;
018
019import com.oracle.labs.mlrg.olcut.util.Pair;
020
021import java.util.List;
022import java.util.Map;
023
024/**
025 * Holds an {@link Example}, a {@link Prediction} and a Map from String to List of Pairs
026 * that contains the per output explanation.
027 */
028public class Excuse<T extends Output<T>> {
029
030    private final Example<T> example;
031    private final Prediction<T> prediction;
032    private final Map<String,List<Pair<String,Double>>> weights;
033
034    /**
035     * Constructs an excuse for the prediction of the supplied example, using the feature weights.
036     * @param example The example to excuse.
037     * @param prediction The prediction to excuse.
038     * @param weights The feature weights involved.
039     */
040    public Excuse(Example<T> example, Prediction<T> prediction, Map<String,List<Pair<String,Double>>> weights) {
041        this.example = example;
042        this.prediction = prediction;
043        this.weights = weights;
044    }
045
046    /**
047     * Returns the features involved in this excuse.
048     * @param label The features for the requested output.
049     * @return The features invovled.
050     */
051    public List<Pair<String,Double>> excuse(String label) {
052        return weights.get(label);
053    }
054
055    /**
056     * Returns the prediction being excused.
057     * @return The prediction.
058     */
059    public Prediction<T> getPrediction() {
060        return prediction;
061    }
062
063    /**
064     * Returns the scores for all outputs and the relevant feature values.
065     * @return The output scores and feature values.
066     */
067    public Map<String,List<Pair<String,Double>>> getScores() {
068        return weights;
069    }
070
071    /**
072     * The example being excused.
073     * @return The example.
074     */
075    public Example<T> getExample() {
076        return example;
077    }
078
079}