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.

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

Field Summary

Fields

Modifier and Type	Field and Description
static org.dmg.pmml.FieldName	DEFAULT_TARGET The name of the default target field.

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.
org.dmg.pmml.DataField	getDataField(org.dmg.pmml.FieldName name) Gets the definition of a field from the DataDictionary.
org.dmg.pmml.FieldName	getTargetField() Convenience method for retrieving the sole target field.
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, getGroupFields, getMiningField, getMiningFunction, getOrderFields, getOutputField, getOutputFields, getSummary, getTarget, getTargetFields

Field Detail

DEFAULT_TARGET

static final org.dmg.pmml.FieldName DEFAULT_TARGET

The name of the default target field.

See Also:

getTargetField()

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:

getDataField(FieldName), Consumer.getMiningField(FieldName)

getDataField

org.dmg.pmml.DataField getDataField(org.dmg.pmml.FieldName name)

Description copied from interface: Consumer

Gets the definition of a field from the DataDictionary.

Specified by:

getDataField in interface Consumer

Parameters:

name - The name of the field. Use DEFAULT_TARGET to represent the default target field.

getTargetField

org.dmg.pmml.FieldName getTargetField()

Convenience method for retrieving the sole target field.

A supervised model should, but is not required to, define a target field. An unsupervised model, by definition, does not define a target field. If the collection of target fields is empty, then the model consumer should assume that the model defines a default target field, which is represented by DEFAULT_TARGET.

The default target field could be either "real" or "phantom". They can be distinguished from one another by looking up the definition of the field from the DataDictionary.

 Consumer consumer = ...;

 List<FieldName> targetFields = consumer.getTargetFields();
 if(targetFields.isEmpty()){
   FieldName targetField = consumer.getTargetField();

   DataField dataField = consumer.getDataField(targetField);
   if(dataField != null){
     // A "real" default target field
   } else

   {
     // A "phantom" default target field
   }
 }
 

Returns:

The sole target field.

Throws:

InvalidFeatureException - If the number of target fields is greater than one.

See Also:

Consumer.getTargetFields()

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. 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 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.

InvalidFeatureException

UnsupportedFeatureException

See Also:

Computable