oracle.dmt.odm.result
Class MiningApplyOutput

java.lang.Object
  |
  +--oracle.dmt.odm.MiningObject
        |
        +--oracle.dmt.odm.result.MiningApplyOutput

All Implemented Interfaces:

java.io.Serializable

public class MiningApplyOutput

extends MiningObject

An instance of MiningApplyOutput specifies the data (columns) to be included in the apply output table created as the result of the apply mining operation.

For example, an apply output table looks like a table with columns (1) caseID, (2) score value with the highest probability, and (3) its probablility with caseID being the key field.

• caseId: Key column of the input table
• score: The predicted target value with the highest probability
• probability: The probability of the score

The columns in the apply output table are described by a combination of ApplyContentItem objects. The table may contain columns from the input table using ApplySourceAttributeItem to identify the records and make the output table more meaningful in its own. One of the following options may be combined with source attributes in a MiningApplyOutput object.

1. ApplyMultipleScoringItem: top/bottom n predictions ordered by probability
2. ApplyTargetProbabilityItem: a list of particular target values
3. ApplyRuleItem: valid only if AdaptiveBayesModel is SingleFeatureBuild, a list of detail rules (since 9.2.0.4)

Example 1: Top 3 predictions with a key column
When interested in only the top 3 predictions (i.e., three target values with highest probabilities), use ApplyMultipleScoringItem. A key column may be present in the apply output table to identify the input record for which the prediction is made. An ApplySourceAttributeItem object is used to describe the key column. The column names of the apply output table are designated by the user. A typical apply output table for this example contains the following columns:

• CustomerID: The key column from the input table
• Prediction: The predicted target value (one of the top 3)
• Probability: The probability of the prediction (optional)

Note that one row of this table represents only one prediction. Therefore, three rows of this apply output table constitute top 3 predictions for each input record. The format of this output table is similar to the transactional format, where a column of the typical two-dimesional table is converted to a row. Refer to TransactionalDataSpecification and NonTransactionalDataSpecification for further details on the data formats.

Example 2: Target values blue and yellow with a key column
When interested in a set of particular target values (regardless of the probability) ApplyTargetProbabilityItem must be used. for example, if interested in only blue and yellow when the target attribute is color. If the key column ProductID from the input table is to be included in the output table, the apply output table to be produced is:

• ProductID: The key column from the input table
• Prediction: One of the two target values blue and yellow
• Rank: The rank of the prediction between 1 and the number of total target values, with 1 being the highest (optional)
• Probability: The probability of the prediction (optional)

Note that one row of this table represents only one prediction. Therefore, two rows of this apply output table are required for each input record.

Since:

9.0.1

See Also:

MiningApplyTask,
MiningApplyResult, Serialized Form

Constructor Summary

MiningApplyOutput()
Creates an empty instance of MiningApplyOutput.

Method Summary

void	addItem(ApplyContentItem contentItem) Adds an instance of ApplyContentItem.
static MiningApplyOutput	createDefault() Creates a default apply output settings.
static MiningApplyOutput	createDefault(MiningAttribute sourceAttr) Creates a default apply output settings with a source column that is provided by the user.
static MiningApplyOutput	createDefault(java.lang.String predAttrName, java.lang.String probAttrName) Creates a default apply output settings by which an apply output table is created with the specified attribute names The resulting apply output table will contain the top score and its associated probability.
ApplyContentOptionItem[]	getApplyContentOptionItems() Returns an array of ApplyContentOptionItem objects contained in this object.
ApplyMultipleScoringItem[]	getApplyMultipleScoringItems() Returns an array of ApplyMultipleScoringItem objects contained in this object.
ApplyContentItem[]	getApplyOutputContentItems() Returns an array of ApplyContentItem objects contained in this object.
ApplyRuleItem	getApplyRuleItem() Returns an ApplyRuleItem object contained in this object.
ApplySourceAttributeItem[]	getApplySourceAttributes() Returns an array of ApplySourceAttributeItem objects contained in this object.
ApplyTargetProbabilityItem[]	getApplyTargetProbabilityItems() Returns the array of ApplyTargetProbabilityItem objects contained to this object.
static java.lang.Integer	getMiningApplyOutputID(java.sql.Connection dbConn, java.lang.String maoName)
static MiningApplyOutput	restoreInternal(java.sql.Connection dbConn, java.lang.Object maoKey) Returns an instance of MiningApplyOutput with the specified name persisted in the data mining server given a database connection and the name of the MiningApplyOutput.
java.lang.Integer	storeInternal(java.sql.Connection dbConn, java.lang.String maoName) Stores the user-specified mining apply output object int the data mining server.
void	validate() Validates if the content of this apply output object can produce a valid output table.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MiningApplyOutput

public MiningApplyOutput()

Creates an empty instance of MiningApplyOutput. Subsequent add methods must be invoked to make this instance valid.

Method Detail

createDefault

public static MiningApplyOutput createDefault()
                                                             throws ODMException

Creates a default apply output settings. The resulting apply output table will contain the top score and its associated probability. The column name of the output table are MAO_PREDICTION for score and MAO_PROBABILITY for probability.

Returns:

MiningApplyOutput - An instance with the default settings.

Throws:

ODMException - Inherited exception

Since:

9.2.0

createDefault

public static MiningApplyOutput createDefault(MiningAttribute sourceAttr)
                                                             throws ODMException

Creates a default apply output settings with a source column that is provided by the user. The resulting apply output table will contain the top score, its associated probability, and the source column provided by the user. The column name of the output table are MAO_SOURCE for the user-provded source column, MAO_PREDICTION for score, and MAO_PROBABILITY for probability. The source column must exist in the input table to be used for apply operation, and is usually a key column.

Parameters:

sourceAttr - A logical representation of a column in the input table to be used for apply operation and to appear in the output table

Returns:

MiningApplyOutput - An instance with the default settings and the provided source attribute

Throws:

ODMException - when the name of sourceAttr is empty or exceeds 30 bytes in length.

Since:

9.2.0

createDefault

public static MiningApplyOutput createDefault(java.lang.String predAttrName,
                                              java.lang.String probAttrName)
                                                             throws ODMException,
InvalidArgumentException

Creates a default apply output settings by which an apply output table is created with the specified attribute names The resulting apply output table will contain the top score and its associated probability.

Parameters:

predAttrName - The column name of the apply output table for the top prediction

probAttrName - The column name of the apply output table for probability of the top prediction

Returns:

MiningApplyOutput - An instance with the default settings with the provided destination columns

Throws:

InvalidArgumentException - when either predAttrName or probAttrName is null.

ODMException - when either predAttrName or probAttrName is empty or exceeds 30 bytes in length.

Since:

9.2.0

addItem

public void addItem(ApplyContentItem contentItem)
             throws InvalidArgumentException

Adds an instance of ApplyContentItem.

Parameters:

contentItem - An instance of ApplyContentItem to be added in this object.

Returns:

void

Throws:

InvalidArgumentException - when contentItem is null.

getApplyOutputContentItems

public ApplyContentItem[] getApplyOutputContentItems()

Returns an array of ApplyContentItem objects contained in this object.

Returns:

ApplyContentItem[] - An array of apply content items

getApplyContentOptionItems

public ApplyContentOptionItem[] getApplyContentOptionItems()

Returns an array of ApplyContentOptionItem objects contained in this object.

Returns:

ApplyContentOptionItem[] - An array of apply content option items

getApplySourceAttributes

public ApplySourceAttributeItem[] getApplySourceAttributes()

Returns an array of ApplySourceAttributeItem objects contained in this object.

Returns:

ApplySourceAttributeItem[] - An array of source attribute items

getApplyMultipleScoringItems

public ApplyMultipleScoringItem[] getApplyMultipleScoringItems()

Returns an array of ApplyMultipleScoringItem objects contained in this object.

Returns:

ApplyMultipleScoringItem[] - An array of apply multiple scoring items

Since:

9.2.0

getApplyTargetProbabilityItems

public ApplyTargetProbabilityItem[] getApplyTargetProbabilityItems()

Returns the array of ApplyTargetProbabilityItem objects contained to this object.

Returns:

ApplyTargetProbabilityItem[] - An array of apply target probability items

Since:

9.2.0

getApplyRuleItem

public ApplyRuleItem getApplyRuleItem()

Returns an ApplyRuleItem object contained in this object.

Returns:

ApplyRuleItem - An apply rule item

Since:

9.2.0.4

validate

public void validate()
              throws MiningObjectException

Validates if the content of this apply output object can produce a valid output table. An instance of MiningApplyOutput is valid if it meets certain integrity constraints, e.g., all items are uniquely named. The constraints include:

• empty object,
• no ApplyContentOptionItem, ApplyMultipleScoringItem, or ApplyTargetProbabilityItem present,
• more than one instance of ApplyContentOptionItem object has the same option (score, probability, and sequenceId),
• no instance of ApplyContentOptionItem object with score option,
• any two of ApplyContentOptionItem, ApplyMultipleScoringItem, and ApplyTargetProbabilityItem are present in this object,
• no target value contained in ApplyTargetProbabilityItem,
• more than one instance of a target value present in ApplyTargetProbabilityItem,
• data types of the target values are different in ApplyTargetProbabilityItem,
• any column names described in ApplySourceAttributeItem are identical,
• more than one ApplySourceAttributeItem objects with the same MiningAttribute,
• any two destination columns are identical, or
• the total number of columns exceeds 1000 columns.
• more than one instance of ApplyRuleItem

Throws:

MiningObjectException - when this instance of apply output object is invalid.

restoreInternal

public static MiningApplyOutput restoreInternal(java.sql.Connection dbConn,
                                                java.lang.Object maoKey)
                                                               throws InvalidArgumentException,
MiningObjectException,
                                                                      java.sql.SQLException,
ODMException

Returns an instance of MiningApplyOutput with the specified name persisted in the data mining server given a database connection and the name of the MiningApplyOutput.

Parameters:

dbConn - A database connection to the data mining server

Returns:

MiningApplyOutput - An instance of MiningApplyOutput restored

Throws:

InvalidArgumentException

MiningObjectException

SQLException

MiningObjectException

InvalidArgumentException

MiningObjectException

java.sql.SQLException

ODMException

storeInternal

public java.lang.Integer storeInternal(java.sql.Connection dbConn,
                                       java.lang.String maoName)
                                throws ODMException,
                                       java.sql.SQLException

Stores the user-specified mining apply output object int the data mining server.

Parameters:

maoName - Name of the mining apply output.

Throws:

InvalidArgumentException - is thrown
- when the dmsConn/taskName are null
- when the maoName is null or its length > 64 characters

MiningObjectException - is thrown
- when the store fails

SQLException - is thrown
- when there is a failure in JDBC calls

ODMException

java.sql.SQLException

getMiningApplyOutputID

public static java.lang.Integer getMiningApplyOutputID(java.sql.Connection dbConn,
                                                       java.lang.String maoName)