org.jpmml.evaluator

Interface Evaluator

All Superinterfaces:

Consumer, Serializable

All Known Implementing Classes:

AssociationModelEvaluator, ClusteringModelEvaluator, GeneralRegressionModelEvaluator, MiningModelEvaluator, ModelEvaluator, NaiveBayesModelEvaluator, NearestNeighborModelEvaluator, NeuralNetworkEvaluator, RegressionModelEvaluator, RuleSetModelEvaluator, ScorecardEvaluator, SupportVectorMachineModelEvaluator, TreeModelEvaluator

public interface Evaluator
extends Consumer

Performs the evaluation of a Model in "interpreted mode".

Obtaining and verifying an Evaluator instance

 PMML pmml = ...;
 ModelEvaluatorFactory modelEvaluatorFactory = ModelEvaluatorFactory.newInstance();
 Evaluator evaluator = (Evaluator)modelEvaluatorFactory.newModelManager(pmml);
 evaluator.verify();
 

Preparing arguments

Converting an user-supplied map of arguments to a prepared map of arguments:

 Map<FieldName, ?> userArguments = ...;
 Map<FieldName, FieldValue> arguments = new LinkedHashMap<FieldName, FieldValue>();
 List<FieldName> activeFields = evaluator.getActiveFields();
 for(FieldName activeField : activeFields){
   FieldValue activeValue = evaluator.prepare(activeField, userArguments.get(activeField));
   arguments.put(activeField, activeValue);
 }
 

Performing the evaluation

 Map<FieldName, ?> result = evaluator.evaluate(arguments);
 

Processing results

Retrieving the value of the target field (ie. the primary result):

 FieldName targetField = evaluator.getTargetField();
 Object targetValue = result.get(targetField);
 

Decoding a complex value to a Java primitive value:

 if(targetValue instanceof Computable){
   Computable computable = (Computable)targetValue;

   targetValue = computable.getResult();
 }
 

Retrieving the values of output fields (ie. secondary results):

 List<FieldName> outputFields = evaluator.getOutputFields();
 for(FieldName outputField : outputFields){
   Object outputValue = result.get(outputField);
 }
 

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 EvaluationException instances that indicate "local" problems, which are related to individual data records. The outer try statement should catch InvalidFeatureException and UnsupportedFeatureException instances that indicate "global" problems, which are related to the class model object.

 try {
   List<Map<FieldName, ?>> records = ...;
   for(Map<FieldName, ?> 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(InvalidFeatureException | UnsupportedFeatureException fe){
   // 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 Also:

EvaluatorUtil

Method Summary

Methods

Modifier and Type	Method and Description
Map<org.dmg.pmml.FieldName,?>	evaluate(Map<org.dmg.pmml.FieldName,?> arguments) Evaluates the model with the specified arguments.
FieldValue	prepare(org.dmg.pmml.FieldName name, Object value) Prepares the input value for a field.
void	verify() Verifies the model.

Methods inherited from interface org.jpmml.evaluator.Consumer

getActiveFields, getDataField, getGroupFields, getMiningField, getMiningFunction, getOrderFields, getOutputField, getOutputFields, getSummary, getTarget, getTargetField, getTargetFields

Method Detail

prepare

FieldValue prepare(org.dmg.pmml.FieldName name,
                 Object value)

Prepares the input value for a field.

First, the value is converted from the user-supplied representation to internal representation. After that, the value is subjected to missing value treatment, invalid value treatment and outlier treatment.

Parameters:

name - The name of the field

string - The input value in user-supplied representation. Use null to represent a missing input value.

Throws:

EvaluationException - If the input value preparation fails.

InvalidFeatureException

UnsupportedFeatureException

See Also:

Consumer.getDataField(FieldName), Consumer.getMiningField(FieldName)

verify

void verify()

Verifies the model.

Throws:

EvaluationException - If the verification fails.

InvalidFeatureException

UnsupportedFeatureException

evaluate

Map<org.dmg.pmml.FieldName,?> evaluate(Map<org.dmg.pmml.FieldName,?> arguments)

Evaluates the model with the specified arguments.

Parameters:

arguments - Map of active field values.

Returns:

Map of target field and output field values. Simple values are represented using the Java equivalents of PMML data types (eg. String, Integer, Float, Double etc.). Complex values are represented as instances of Computable that return simple values. A missing result is represented by null.

Throws:

EvaluationException - If the evaluation fails.

InvalidFeatureException

UnsupportedFeatureException

See Also:

Computable