PMML 4.1 - Output fields

Example

<Output>
  <OutputField name="P_responseYes" optype="continuous" dataType="double" targetField="response" feature="probability" value="YES"/>

  <OutputField name="P_responseNo" optype="continuous" dataType="double" targetField="response" feature="probability" value="NO"/>

  <OutputField name="I_response" optype="categorical" dataType="string" targetField="response" feature="predictedValue"/>

  <OutputField name="U_response" optype="categorical" dataType="string" targetField="response" feature="predictedDisplayValue"/>
</Output>

If a model contains this Output element a PMML consumer could map an input table to an output table with columns named P_responseYes, P_responseNo, etc. The values for P_responseYes are determined as the probability that the target field, with name response has the value YES.

Schema:

<xs:element name="Output">
  <xs:complexType>
    <xs:sequence>
      <xs:element ref="Extension" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element ref="OutputField" minOccurs="1" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>
</xs:element>

<xs:element name="OutputField">
  <xs:complexType>
    <xs:sequence>
      <xs:element ref="Extension" minOccurs="0" maxOccurs="unbounded"/>
      <xs:sequence minOccurs="0" maxOccurs="1">
        <xs:element ref="Decisions" minOccurs="0" maxOccurs="1"/>
        <xs:group ref="EXPRESSION" minOccurs="1" maxOccurs="1"/>
      </xs:sequence>
    </xs:sequence>
    <xs:attribute name="name" type="FIELD-NAME" use="required"/>
    <xs:attribute name="displayName" type="xs:string"/>
    <xs:attribute name="optype" type="OPTYPE"/>
    <xs:attribute name="dataType" type="DATATYPE"/>
    <xs:attribute name="targetField" type="FIELD-NAME"/>
    <xs:attribute name="feature" type="RESULT-FEATURE"/>
    <xs:attribute name="value" type="xs:string"/>
    <xs:attribute name="ruleFeature" type="RULE-FEATURE" default="consequent"/>
    <xs:attribute name="algorithm" default="exclusiveRecommendation">
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:enumeration value="recommendation"/>
          <xs:enumeration value="exclusiveRecommendation"/>
          <xs:enumeration value="ruleAssociation"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
    <xs:attribute name="rank" type="INT-NUMBER" default="1"/>
    <xs:attribute name="rankBasis" default="confidence">
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:enumeration value="confidence"/>
          <xs:enumeration value="support"/>
          <xs:enumeration value="lift"/>
          <xs:enumeration value="leverage"/>
          <xs:enumeration value="affinity"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
    <xs:attribute name="rankOrder" default="descending">
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:enumeration value="descending"/>
          <xs:enumeration value="ascending"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
    <xs:attribute name="isMultiValued" default="0"/>
    <xs:attribute name="segmentId" type="xs:string"/>
  </xs:complexType>
</xs:element>

<xs:simpleType name="RESULT-FEATURE">
  <xs:restriction base="xs:string">
    <xs:enumeration value="predictedValue"/>  
    <xs:enumeration value="predictedDisplayValue"/>
    <xs:enumeration value="transformedValue"/> 
    <xs:enumeration value="decision"/>
    <xs:enumeration value="probability"/>
    <xs:enumeration value="affinity"/>
    <xs:enumeration value="residual"/>
    <xs:enumeration value="standardError"/>
    <xs:enumeration value="clusterId"/>
    <xs:enumeration value="clusterAffinity"/>
    <xs:enumeration value="entityId"/>
    <xs:enumeration value="entityAffinity"/>
    <xs:enumeration value="warning"/>
    <xs:enumeration value="ruleValue"/>
    <xs:enumeration value="reasonCode"/>
  </xs:restriction>
</xs:simpleType>

<xs:element name="Decisions">
  <xs:complexType>
    <xs:sequence>
      <xs:element ref="Extension" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element ref="Decision" minOccurs="1" maxOccurs="unbounded"/>
    </xs:sequence>
    <xs:attribute name="businessProblem" type="xs:string"/>
    <xs:attribute name="description" type="xs:string"/>
  </xs:complexType>
</xs:element>

<xs:element name="Decision">
  <xs:complexType>
    <xs:sequence>
      <xs:element ref="Extension" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
    <xs:attribute name="value" type="xs:string" use="required"/>
    <xs:attribute name="displayValue" type="xs:string"/>
    <xs:attribute name="description" type="xs:string"/>
  </xs:complexType>
</xs:element>

<xs:simpleType name="RULE-FEATURE">
  <xs:restriction base="xs:string">
    <xs:enumeration value="antecedent"/>
    <xs:enumeration value="consequent"/>
    <xs:enumeration value="rule"/>
    <xs:enumeration value="ruleId"/>
    <xs:enumeration value="confidence"/>
    <xs:enumeration value="support"/>
    <xs:enumeration value="lift"/>
    <xs:enumeration value="leverage"/>
    <xs:enumeration value="affinity"/>
  </xs:restriction>
</xs:simpleType>

The attribute name specifies the name of a the OutputField. The name itself does not define how the output values are computed. For information on the naming of OutputFields, see Scope of Fields.

The dataType of an OutputField element specifies the default column type. opType can be used to indicate admissible operations on the values. A clusterId field, for example, can have integer as its dataType, but categorical as its opType. For details, see the description of DataDictionary.

The attribute targetField must refer either to a MiningField of type predicted or to a Target in the Targets section. targetField is a required attribute in case the model predicts multiple fields.

If the attribute feature is not specified then the output value is a copy of the target field value. In this case, the target field is a required input for scoring in addition to the active fields in the MiningSchema.

If the attribute feature is specified then the output field value is computed from the mining result.

The attribute value contains the raw, not the displayValue of a value in the target field, either specified in targetField or implied as the only target field in the model. This attribute is used only in conjunction with result features referring to an individual target value, for example probability. If the attribute value is not specified and the value of the attribute feature is probability then the probability of the predicted categorical value should be returned as an output. Otherwise, value indicates the category for which a probability is returned.

An output field may contain an association rule or any of its properties. ruleFeature specifies which feature of an association rule to return.

The attribute algorithm applies only to Association Rules models, and specifies which scoring algorithm to use when computing the output value.

The attribute rank is used to specify which item from a set of outputs should be selected. It is used by Scorecards and Association Rules models.

Scorecards can return multiple reason codes depending on the complexity of the scorecard. If the scorecard calls for multiple reason codes to be given, rank="1" returns the top reason code. To return other reason codes, rank must be set to the appropriate index.

In a similar manner, Association Rules models can return multiple result values as a result of the scoring process. In this case, if the result consists of three items, the default behavior (rank="1") is for the first item to be returned as the result (assuming isMultiValued has a value of "0"; see below for more information about isMultiValued). To return other items, rank must be set to the appropriate index. The attribute rankBasis is used to specify which criterion is used to sort the multiple result values. For instance, the results could be sorted by the confidence, support or lift of the rules. The sorting order is determined by the rankOrder attribute. The default behavior (rankOrder="descending") indicates that the rules with the highest rank will appear first on the sorted list. In this case, setting rank="1" would return the first rule from the sorted list, which would be the highest ranked rule. Note that attributes isMultiValued, rankBasis and rankOrder apply only to Association Rules models.

The attribute isMultiValued indicates that the output can represent multiple output values. If the value of the attribute is "1", then the rank value indicates the number of output values that should be returned - a positive value indicates the number of output values to be returned, based on the rankBasis and rankOrder, while a zero value indicates that all output values are to be returned. If the value of isMultiValued is "0" (default), then rank indicates a particular output, as defined above.

The Output element allows for post-processing of output fields. This can take a generic form through the use of EXPRESSION (see Transformations for more information). Expressions are only allowed for some result features. For details, see section Result Features below.

The attribute field in an EXPRESSION must always refer to the name of an OutputField in Output. References to Output Fields must not be cyclic.

The attribute segmentId is applicable to MiningModels which utilize Segmentation. This attribute provides an alternative approach to deliver results from Segments which avoids having to specify Outputs within each Segment. If the segmentId attribute matches the id attribute of a Segment within the scope of this model element (the model element containing this OutputField's parent Outputs element), and if the predicate of that segment is true, then this OutputField returns the specified result feature from the sub-model contained within the specified segment. If there is no Segment matching segmentId or if the predicate of the matching Segment evaluated to false, then by convention the result delivered by this OutputField is missing. Note that any Segment element's id attribute that is referenced by a segmentId attribute in an OutputField must be unique within the scope of this Segmentation element and any child Segmentation elements that are contained in nested MiningModels.

Result Features

predictedValue: Select the raw predicted value. More than one OutputField element can have the predictedValue feature only if the model predicts more than one field. Details can be found in the description of the individual models.
predictedDisplayValue: Select the display value that corresponds to the raw predicted value. For most models, the display value can be specified in the element Target. If it is not specified explicitly, then the raw predicted value is used by default.
transformedValue: Apply some transformation to the value of an output field. For this result feature, OutputField must contain an EXPRESSION. The transformed value is the result of the evaluation of the EXPRESSION. Often, the transformed value represents a shift of the value into a different scale. Scaling is commonly used to transform a value into a value that is more friendly to humans, for example, transforming values 0 to 1 into 0 to 100. Another common use case is the retransformation of a value that has been scaled by the algorithm before the calculations in order to present the output in the original scale rather than the transformed one. A typical example is a logarithmic transformation, where, instead of a target value x, its logarithm log(x) is used. When presenting predicted values v, they will have to be retransformed as exp(v).
decision: Derive a decision from the output of a data mining model. For this result feature, OutputField must contain an EXPRESSION. The decision is the result of the evaluation of the EXPRESSION. If the result feature is decision all possible values resulting from the evaluation of EXPRESSION must be introduced using Decision elements.
probability: Select the probability of the target value as given by the attribute value. The target value may correspond to values in attribute targetCategory in element RegressionTable or values in attribute value in element ScoreDistribution for tree classification. That is, these values can be display values. The corresponding original values can be found in the Target elements. Attribute value in element Target matches value in OutputField; displayValue in Target is the original value.
residual: Select the residual of the target value. For numeric prediction this is the actual value minus the predicted value. For classification this is [actual value = target value] minus the predicted probability for the target value. The attribute value specifies the raw target value. The term [actual value = target value] is defined as 1.0 if the actual value is the same as the target value, and 0.0 otherwise.
standardError: Select the standard error of the predicted numeric value. In a regression model this value is computed as a square root of xVx where x is a vector of parameter coefficients based on the given predictors and V is the parameters covariance matrix.
clusterId: Select a 1-based index, indicating the position of the predicted cluster in the model. As of PMML 4.1, this result feature is deprecated. It is suggested that entityId is used instead.
clusterAffinity: clusterAffinity is the value of the distance or the similarity depending on the context of the clustering PMML document. Please note that a clustering PMML document producer may output the distance to the nearest center, instead of the cluster center. This specification supports only the distance to the cluster center given in clusterId, NOT the distance to the nearest center. As of PMML 4.1, this result feature is deprecated. It is suggested that affinity is used instead.
entityId: Select the predicted entity defined for each model type: cluster, tree node, neuron or rule. For tree models, the id of the winning tree node is output; for Clustering models, the 1-based index (implicit identifier) of the winning cluster is output; for Neural Networks, the id of the winning OutputNeuron is output; for RuleSet models, the id of the rule that fired is output, and for Association Rules models, the id of the winning rule(s).
affinity: Select the value of the distance or the similarity of the provided record to the predicted entity as defined in each of the applicable model types.
entityAffinity: entityAffinity was originally reserved for possible use in future versions of PMML. As of PMML 4.1, it is deprecated as the general affinity feature is introduced instead.
warning: Any warning message such as too many missing values.
ruleValue: Select the rule value specified by the attribute ruleFeature. Due to the fact that a rule consists of many different entities (antecedent, consequent, confidence, etc.), this identifier is required to allow for the selection of the desired output.
reasonCode: Select the reason code specified by the attribute reasonCode.

Decisions

Decisions is used in conjunction with an EXPRESSION for output fields with result feature decision. Its attribute businessProblem names the problem or question for which a decision is proposed by application of the data mining model. The attribute description can describe the decision problem in more detail.

The element contains an element Decision for every possible value of the decision. The value is a decision value as returned by the EXPRESSION. The displayValue is a string, which may be used by applications to refer to that decision. The attribute description can describe the decision in more detail.

Rule Features

The meaning of the ruleFeature attribute, when feature is set to ruleValue, is:

antecedent: Select the antecedent of the winning rule(s) (default), or the rule specified by the rank value.
consequent: Select the consequent of the winning rule(s) (default), or the rule specified by the rank value. This output is identical to the predictedValue output.
rule: Select the winning rule(s) (default), or the rule specified by the rank value. This output will return a description of the rule, formatted in the following way: {<antecedent>}->{<consequent>}.
ruleId: Select the id of the winning rule(s) (default), or the rule specified by the rank value. If the selected rule does not provide an id, a 1-based index is returned. This option is identical to the entityId output.
confidence: Select the confidence of the winning rule(s) (default), or the rule specified by the rank value. This option is identical to the probability output.
support: Select the support of the winning rule(s) (default), or the rule specified by the rank value.
lift: Select the lift of the winning rule(s) (default), or the rule specified by the rank value.
leverage: Select the leverage of the winning rule(s) (default), or the rule specified by the rank value.
affinity: Select the affinity of the winning rule(s) (default), or the rule specified by the rank value.

Examples

Example 1

Suppose a regression model has the following OutputField elements:

<Output>
  <OutputField name="RawResult" optype="continuous" dataType="double" feature="predictedValue"/>  
  <OutputField name="FinalResult" optype="continuous" dataType="double" feature="transformedValue">
    <NormContinuous field="RawResult">
      <LinearNorm orig="-100" norm="-304"/>
      <LinearNorm orig="100" norm="324"/>
    </NormContinuous>
  </OutputField> 
</Output>

In essence, this describes the rescaling function f(x) = 10 + 3.14*x in the range between -100 and 100. With a predicted value of 8, the final derived result would be 35.12.

Example 2

<Output>
  <OutputField name="RawResult" optype="continuous" dataType="double" feature="predictedValue"/>  
  <OutputField name="FinalResult" optype="continuous" dataType="double" feature="transformedValue">
    <Apply function="round">
      <NormContinuous field="RawResult">
        <LinearNorm orig="-100" norm="-21.4"/>
        <LinearNorm orig="-10" norm="-21.4"/>
        <LinearNorm orig="10.5" norm="42.97"/>
        <LinearNorm orig="100" norm="42.97"/>
      </NormContinuous>    
    </Apply>
  </OutputField> 
</Output>

In addition to the rescale function from the previous example, we now have upper and lower limits as well as rounding. Suppose the model returns a value of 8. The limits will not show effect, and after rescaling and rounding the final result will be 35. If the predicted value was 12.97, the upper limit would take effect and the maximum value 10.5 would be taken instead. After rescaling and rounding, the final derived result is 43.

Min and max can always be handled using a piecewise linear transformation (NormContinuous). For a lower limit of min and an upper limit of max and a linear behavior governed by f*x + c in between, the following example defines the transformation:

<NormContinuous field="X">
  <LinearNorm orig="VMIN" norm="f*min+c"/>
  <LinearNorm orig="min" norm="f*min+c"/>
  <LinearNorm orig="max" norm="f*max+c"/>
  <LinearNorm orig="VMAX" norm="f*max+c"/>
</NormContinuous>

Note that the following inequalities must hold: VMIN < min < max < VMAX.

Example 3

Building on the previous example, the current one shows how the final result, obtained after the rescale function takes place, can be compared with a given threshold of value 30 to determine a business decision where values greater than 30 yield a positive response.

<Output>
  <OutputField name="RawResult" optype="continuous" dataType="double" feature="predictedValue"/>  
  <OutputField name="FinalResult" optype="continuous" dataType="double" feature="transformedValue">
    <Apply function="round">
      <NormContinuous field="RawResult">
        <LinearNorm orig="-100" norm="-21.4"/>
        <LinearNorm orig="-10" norm="-21.4"/>
        <LinearNorm orig="10.5" norm="42.97"/>
        <LinearNorm orig="100" norm="42.97"/>
      </NormContinuous>    
    </Apply>
  </OutputField>
  <OutputField name="BusinessDecision" optype="categorical" dataType="string" feature="decision">
    <Decisions businessProblem="Should the outstanding amount be collected?" description="The decision depends on the likelihood to get the money and the cost to try.">
      <Decision value="waive" description="Waive any existing conditions on case and approve."/>
      <Decision value="refer" description="Keep conditions and refer case for further scrutiny."/>  
    </Decisions>
    <Apply function="if">
      <Apply function="greaterThan">
        <FieldRef field="FinalResult"/>
        <Constant>30</Constant>
      </Apply>
      <!--THEN-->
      <Constant>waive</Constant>
      <!--ELSE-->     
      <Constant>refer</Constant>
    </Apply>    
  </OutputField>     
</Output>

Outputs Per Model Type

This table shows which outputs are allowed for each type of model defined in PMML. Please note that, as new scoring procedures are added in future releases of PMML, this table can change:

Allowable Outputs based on Model Type (ok = Valid Output, X = Not Applicable)

Model Type

predicted Value

transformed Value

decision

predicted Display Value

probability

residual

standard Error

clusterId

cluster Affinity

entityID

affinity

entity Affinity

warning

ruleValue

reasonCode

Association Rules

ok

X

ok

X

ok

X

X

X

X

X

X

X

ok

ok

X

Baseline Model

ok

ok

ok

X

X

X

X

X

X

X

X

X

ok

X

X

Clustering Model

ok

X

ok

ok

X

X

X

ok

ok

ok

ok

ok

ok

X

X

GeneralRegression (regression)

ok

ok

ok

X

X

ok

ok

X

X

X

X

X

ok

X

X

GeneralRegression (classification)

ok

X

ok

ok

ok

ok

ok

X

X

X

X

X

ok

X

X

k-NN (regression)

ok

ok

ok

ok

X

X

X

X

X

ok

ok

ok

ok

X

X

k-NN (classification)

ok

X

ok

ok

X

X

X

X

X

ok

ok

ok

ok

X

X

k-NN (clustering)

ok

X

ok

ok

X

X

X

ok

ok

ok

ok

ok

ok

X

X

Naive Bayes

ok

X

ok

ok

ok

ok

X

X

X

X

X

X

ok

X

X

Neural Network (regression)

ok

ok

ok

ok

X

ok

ok

X

X

ok

ok

ok

ok

X

X

Neural Network (classification)

ok

X

ok

ok

ok

ok

ok

X

X

ok

ok

ok

ok

X

X

Regression (regression)

ok

ok

ok

ok

X

ok

ok

X

X

X

X

X

ok

X

X

Regression (classification)

ok

X

ok

ok

ok

ok

ok

X

X

X

X

X

ok

X

X

RuleSet

ok

X

ok

ok

ok

ok

X

X

X

ok

ok

ok

ok

X

X

Scorecard

ok

ok

ok

ok

X

X

X

X

X

X

X

X

ok

X

ok

Sequence

X

X

X

X

X

X

X

X

X

X

X

X

ok

X

X

Support Vector Machine (regression)

ok

ok

ok

ok

X

ok

ok

X

X

X

X

X

ok

X

X

Support Vector Machine (classification)

ok

X

ok

ok

ok

ok

ok

X

X

X

X

X

ok

X

X

Tree (regression)

ok

ok

ok

ok

X

ok

X

X

X

ok

ok

ok

ok

X

X

Tree (classification)

ok

X

ok

ok

ok

ok

X

X

X

ok

ok

ok

ok

X

X

For Model Composition, the Output values should reflect those of the last model in the calculation.