org.jpmml.evaluator.Evaluator Maven / Gradle / Ivy

/*
 * Copyright (c) 2013 Villu Ruusmann
 *
 * This file is part of JPMML-Evaluator
 *
 * JPMML-Evaluator is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * JPMML-Evaluator is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with JPMML-Evaluator.  If not, see .
 */
package org.jpmml.evaluator;

import java.util.Map;

import org.dmg.pmml.MiningFunction;
import org.dmg.pmml.Model;
import org.jpmml.model.MarkupException;

/**
 * 
 * Performs the evaluation of a {@link Model}.
 * 
 *
 * Building and verifying an Evaluator instance
 * {@code
 * EvaluatorBuilder evaluatorBuilder = new LoadingModelEvaluatorBuilder()
 *   .load(new File("model.pmml"));
 * Evaluator evaluator = evaluatorBuilder.build();
 * evaluator.verify();
 * }
 *
 * Preparing arguments
 * 

 * Transforming an user-supplied map of arguments to a known-good PMML map of arguments:
 * {@code
 * Map userArguments = ...;
 * Map arguments = new LinkedHashMap<>();
 * List inputFields = evaluator.getInputFields();
 * for(InputField inputField : inputFields){
 *   String inputName = inputField.getName();
 *   Object rawValue = userArguments.get(inputName);
 *   FieldValue inputValue = inputField.prepare(rawValue);
 *   arguments.put(inputName, inputValue);
 * }
 * }
 *
 * Performing the evaluation
 * {@code
 * Map results = evaluator.evaluate(arguments);
 * }
 *
 * Processing results
 * 

 * Retrieving the values of {@link #getTargetFields() target fields} (ie. primary results):
 * {@code
 * List targetFields = evaluator.getTargetFields();
 * for(TargetField targetField : targetFields){
 *   String targetName = targetField.getName();
 *   Object targetValue = results.get(targetName);
 * }
 * }
 *
 * Decoding a {@link Computable complex value} to a Java primitive value:
 * {@code
 * if(targetValue instanceof Computable){
 *   Computable computable = (Computable)targetValue;
 *   targetValue = computable.getResult();
 * }
 * }
 *
 * Retrieving the values of {@link #getOutputFields() output fields} (ie. secondary results):
 * {@code
 * List outputFields = evaluator.getOutputFields();
 * for(OutputField outputField : outputFields){
 *   String outputName = outputField.getName();
 *   Object outputValue = results.get(outputName);
 * }
 * }
 *
 * Handling exceptions
 * 

 * A code block that does exception-prone work should be surrounded with two levels of try-catch statements.
 * The inner try statement should catch {@link EvaluationException} instances that indicate "local" problems, which are related to individual data records.
 * The outer try statement should catch {@link MarkupException} instances that indicate "global" problems, which are related to the class model object.
 * {@code
 * try {
 *   Lis> records = ...;
 *   for(Map record : records){
 *     try {
 *       // Do exception-prone work
 *     } catch(EvaluationException ee){
 *       // The work failed because of the data record.
 *       // Skip this data record and proceed as usual with the next one
 *     }
 *   }
 * } catch(MarkupException me){
 *   // The work failed because of the class model object.
 *   // This is a persistent problem that is very likely to affect all data records
 *   // Decommission the Evaluator instance
 * }
 * }
 *
 * @see EvaluatorUtil
 *
 * @see HasGroupFields
 * @see HasOrderFields
 *
 * @see HasPMML
 * @see HasModel
 */
public interface Evaluator extends HasInputFields, HasResultFields {

	/**
	 * 
	 * Gets a short description of the {@link Model}.
	 * 
	 */
	String getSummary();

	/**
	 * 
	 * Gets the type of the {@link Model}.
	 * 
	 */
	MiningFunction getMiningFunction();

	/**
	 * 
	 * Verifies the model.
	 * 
	 *
	 * @throws EvaluationException If the verification fails.
	 * @throws MarkupException
	 */
	Evaluator verify();

	/**
	 * 
	 * Evaluates the model with the specified arguments.
	 * 
	 *
	 * @param arguments Map of {@link #getInputFields() input field} values.
	 *
	 * @return Map of {@link #getTargetFields() target field} and {@link #getOutputFields() output field} values.
	 * A target field could be mapped to a complex value or a simple value.
	 * An output field is always mapped to a simple value.
	 * Complex values are represented as instances of {@link Computable} that return simple values.
	 * Simple values are represented using the Java equivalents of PMML data types (eg. String, Integer, Float, Double etc.).
	 * A missing value is represented by null.
	 *
	 * @throws EvaluationException If the evaluation fails.
	 * @throws MarkupException
	 *
	 * @see Computable
	 */
	Map evaluate(Map arguments);

	/**
	 * 
	 * The name of the default target field.
	 * 
	 */
	String DEFAULT_TARGET_NAME = null;
}