oracle.dmt.odm.model
Class AttributeImportanceModel

java.lang.Object
  |
  +--oracle.dmt.odm.MiningObject
        |
        +--oracle.dmt.odm.LocatableObject
              |
              +--oracle.dmt.odm.model.MiningModel
                    |
                    +--oracle.dmt.odm.model.AttributeImportanceModel
All Implemented Interfaces:
java.io.Serializable

public abstract class AttributeImportanceModel
extends MiningModel

The abstract class AttributeImportanceModel is a Java representation of the attribute importance model. This class provides methods to access a set of attributes based on their respective importance within the model such as Other statistical metadata.

Attribute Importance is used to select the relevant and important attributes from a build dataset. For ODM 9.2.0, the AttributeImportanceModel is applicable to supervised mining models, and provides an assessment of attribute usefulness. It assigns an importance value and rank to each of the active attributes used for building supervised models. From this ranking, the user can select a subset of important attributes from the complete set of active attributes. The attribute and the corresponding attribute importance value and the rank are stored as a database table.

Since:
9.2.0
See Also:
Serialized Form

Method Summary
TypeMethod
 AttributeImportanceEntry[] getAttributeImportanceEntries()
          Returns all AttributeImportanceEntry objects in the model, each of which contains an attribute name, its importance value, and its rank.
 java.lang.String getAttributeImportanceTableName()
          Returns the table name where each row contains an attribute name, its importance value, and its rank.
static java.lang.String getAttributeImportanceTableName(Connection dmsConn, java.lang.String modelName)
          Returns the table name where each row contains a attribute name, its importance value, and its rank.
 java.lang.String[] getAttributes(AttributeImportanceEntry[] entries)
          Returns an array of attribute names that correspond to the specified array of AttributeImportanceEntry objects
static java.lang.String[] getAttributesByImportance(Connection dmsConn, java.lang.String modelName, float threshold, boolean aboveThreshold)
          Returns an array of attribute names based on the threshold specified for attribute importance value, given the connection to the data mining server and the model name.
static java.lang.String[] getAttributesByImportance(Connection dmsConn, java.lang.String modelName, float lowerBound, float upperBound)
          Returns an array of attribute names whose importance values fall in the specified range, given the connection to the data mining server and the model name.
static java.lang.String[] getAttributesByPercentage(Connection dmsConn, java.lang.String modelName, float percentage, boolean aboveThreshold)
          Returns an array of attribute names whose importance ranks fall in the specified percentile, given the connection to the data mining server and the model name.
static java.lang.String[] getAttributesByRank(Connection dmsConn, java.lang.String modelName, int rank, boolean aboveThreshold)
          Returns an array of attribute names based on the threshold specified for attribute importance rank, given the connection to the data mining server and the model name.
static java.lang.String[] getAttributesByRank(Connection dmsConn, java.lang.String modelName, int lowerBoundRank, int upperBoundRank)
          Returns an array of attribute names whose importance ranks fall in the specified range, given the connection to the data mining server and the model name.
static AttributeImportanceEntry[] getAttributeSetByImportance(Connection dmsConn, java.lang.String modelName, float threshold, boolean aboveThreshold)
          Returns an array of AttributeImportanceEntry objects based on the threshold specified for attribute importance value, given the connection to the data mining server and the model name.
static AttributeImportanceEntry[] getAttributeSetByPercentage(Connection dmsConn, java.lang.String modelName, float percentage, boolean aboveThreshold)
          Returns an array of attribute importance entries whose importance ranks fall in the specified percentile, given the connection to the data mining server and the model name.
static AttributeImportanceEntry[] getAttributeSetByRank(Connection dmsConn, java.lang.String modelName, int rank, boolean aboveThreshold)
          Returns an array of attribute importance entries based on the threshold specified for attribute importance rank, given the connection to the data mining server and the model name.
static AttributeImportanceModel restore(Connection dmsConn, java.lang.String modelName)
          Returns an instance of AttributeImportanceModel with the specified name persisted in the data mining server given a connection to the data mining server and the model name.
 
Methods inherited from class oracle.dmt.odm.model.MiningModel
build, getBinCategoricalTableName, getBinNumericTableName, getMiningAlgorithm, getMiningFunction, getMiningFunctionSettings, getModelName, listContents, listContents, listContents, listContents, remove, setModelNameForMig
 
Methods inherited from class oracle.dmt.odm.LocatableObject
deserialize, serialize
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getAttributeImportanceEntries

public AttributeImportanceEntry[] getAttributeImportanceEntries()
Returns all AttributeImportanceEntry objects in the model, each of which contains an attribute name, its importance value, and its rank.
Returns:
AttributeImportanceEntry[] - An array of AttributeImportanceEntry objects

getAttributeImportanceTableName

public java.lang.String getAttributeImportanceTableName()
Returns the table name where each row contains an attribute name, its importance value, and its rank.
Returns:
String - The name of the table

getAttributeImportanceTableName

public static java.lang.String getAttributeImportanceTableName(Connection dmsConn,
                                                               java.lang.String modelName)
                                                        throws java.sql.SQLException,
                                                               InvalidArgumentException,
                                                               MiningObjectException,
                                                               ODMException
Returns the table name where each row contains a attribute name, its importance value, and its rank.
Parameters:
dmsConn - The connection to the data mining server
modelName - The name of the model from which the table name is retrieved
Returns:
String - The name of the model table
Throws:
SQLException - -
     - if the model table does not exist in the database
     - if the model name is invalid
InvalidArgumentException -
     - if modelName is null
     - if dmsConn is null
MiningObjectException -
     - if the model with the specified name does not exist
ODMException - if modelName is empty or exceeds 64 characters in length

getAttributeSetByImportance

public static AttributeImportanceEntry[] getAttributeSetByImportance(Connection dmsConn,
                                                                     java.lang.String modelName,
                                                                     float threshold,
                                                                     boolean aboveThreshold)
                                                              throws java.sql.SQLException,
                                                                     InvalidArgumentException,
                                                                     MiningObjectException,
                                                                     ODMException
Returns an array of AttributeImportanceEntry objects based on the threshold specified for attribute importance value, given the connection to the data mining server and the model name. The valid value for the threshold ranges between 0 and 1.

For example, list attributes importance entries with importance values above 0.01.
     - threshold = 0.01, aboveThrshold = true

Parameters:
dmsConn - The connection to the data mining server
modelName - The name of the model from which the table name is retrieved
threshold - The value for attribute importance value
aboveThreshold - Returns an array of entries whose importance values are above threashold value if true, or returns an array of entries whose importance values are below threshold if false.
Returns:
AttributeImportanceEntry[] - An array of AttributeImportanceEntry that meet the specified creteria.
Throws:
SQLException -
    - if the model table does not exist in the database
     - if the model name is invalid
InvalidArgumentException -
     - if modelName is null
     - if dmsConn is null
     - if threshold is less than 0
     - if threshold is greater than 1
MiningObjectException -
     - if the model with the specified name does not exist
ODMException - if modelName is empty or exceeds 64 characters in length

getAttributesByImportance

public static java.lang.String[] getAttributesByImportance(Connection dmsConn,
                                                           java.lang.String modelName,
                                                           float threshold,
                                                           boolean aboveThreshold)
                                                    throws java.sql.SQLException,
                                                           InvalidArgumentException,
                                                           MiningObjectException,
                                                           ODMException
Returns an array of attribute names based on the threshold specified for attribute importance value, given the connection to the data mining server and the model name. The valid value for the threshold ranges between 0 and 1.

For example, list attributes with importance value above 0.01:
     - threshold = 0.01, aboveThrshold = true

Parameters:
dmsConn - The connection to the data mining server
modelName - The name of the model from which the table name is retrieved
threshold - The value for attribute importance value
aboveThreshold - Returns an array of attribute names whose importance values are above threashold value if true, or returns an array of attribute names whose importance values are below threshold if false.
Returns:
String[] - An array of attribute names that meet the specified criteria
Throws:
- SQLException
     - if the model table does not exist in the database
     - if the model name is invalid
InvalidArgumentException -
     - if modelName is null
     - if dmsConn is null
     - if threshold is less than 0
     - if threshold is greater than 1
MiningObjectException -
     - if the model with the specified name does not exist
ODMException - if modelName is empty or exceeds 64 characters in length

getAttributesByImportance

public static java.lang.String[] getAttributesByImportance(Connection dmsConn,
                                                           java.lang.String modelName,
                                                           float lowerBound,
                                                           float upperBound)
                                                    throws java.sql.SQLException,
                                                           InvalidArgumentException,
                                                           MiningObjectException,
                                                           ODMException
Returns an array of attribute names whose importance values fall in the specified range, given the connection to the data mining server and the model name. The valid value for the threshold ranges between 0 and 1.

For example, list attributes with importance value between 0.01 and 0.02:
     - lowerBound = 0.01, upperBound = 0.02

Parameters:
dmsConn - The connection to the data mining server
modelName - The name of the model from which the table name is retrieved
lowerBound - The lower bound of the threshold
upperBound - The upper bound for the threshold
Returns:
String[] - An array of attribute names that meet the specified criteria
Throws:
SQLException -
     - if the model table does not exist in the database
     - if the model name is invalid
InvalidArgumentException -
     - if modelName is null
     - if dmsConn is null
     - if lowerBound is less than 0
     - if lowerBound is greater than 1
     - if upperBound is less than 0
     - if upperBound is greater than 1
     - if lowerBound is greater than upperBound
MiningObjectException -
     - if the model with the specified name does not exist
ODMException - if modelName is empty or exceeds 64 characters in length

getAttributeSetByRank

public static AttributeImportanceEntry[] getAttributeSetByRank(Connection dmsConn,
                                                               java.lang.String modelName,
                                                               int rank,
                                                               boolean aboveThreshold)
                                                        throws java.sql.SQLException,
                                                               InvalidArgumentException,
                                                               MiningObjectException,
                                                               ODMException
Returns an array of attribute importance entries based on the threshold specified for attribute importance rank, given the connection to the data mining server and the model name. The valid value for the rank ranges between 1 and the number of attributes.

For example, list attribute Importance Entries where rank >= 5:
     - threshold = 5, aboveThreshold = true

Parameters:
dmsConn - The connection to the data mining server
modelName - The name of the model from which the table name is retrieved
threshold - The value for attribute importance rank
aboveThreshold - Returns an array of entries whose importance ranks are above rank value if true, or returns an array of entries whose importance ranks are below rank if false.
Returns:
AttributeImportanceEntry[] - An array of attribute importance entries that meet the specified criteria
Throws:
SQLException -
     - if the model table does not exist in the database
     - if the model name is invalid
InvalidArgumentException -
     - if modelName is null
     - if dmsConn is null
     - if rank is less than 1
MiningObjectException -
     - if the model with the specified name does not exist
ODMException - if modelName is empty or exceeds 64 characters in length

getAttributesByRank

public static java.lang.String[] getAttributesByRank(Connection dmsConn,
                                                     java.lang.String modelName,
                                                     int rank,
                                                     boolean aboveThreshold)
                                              throws java.sql.SQLException,
                                                     InvalidArgumentException,
                                                     MiningObjectException,
                                                     ODMException
Returns an array of attribute names based on the threshold specified for attribute importance rank, given the connection to the data mining server and the model name. The valid value for the rank ranges between 1 and the number of attributes.

For example, list attributes where rank >= 5 ordered by rank:
     - threshold = 5, aboveThreshold = true

Parameters:
dmsConn - The connection to the data mining server
modelName - The name of the model from which the table name is retrieved
threshold - The value for attribute importance rank
aboveThreshold - Returns an array of entries whose importance ranks are above rank value if true, or returns an array of entries whose importance ranks are below rank if false.
Returns:
String[] - An array of attribute names that meet the specified criteria
Throws:
SQLException -
     - if the model table does not exist in the database
     - if the model name is invalid
InvalidArgumentException -
     - if modelName is null
     - if dmsConn is null
     - if rank is less than 1
MiningObjectException -
     - if the model with the specified name does not exist
ODMException - if modelName is empty or exceeds 64 characters in length

getAttributesByRank

public static java.lang.String[] getAttributesByRank(Connection dmsConn,
                                                     java.lang.String modelName,
                                                     int lowerBoundRank,
                                                     int upperBoundRank)
                                              throws java.sql.SQLException,
                                                     InvalidArgumentException,
                                                     MiningObjectException,
                                                     ODMException
Returns an array of attribute names whose importance ranks fall in the specified range, given the connection to the data mining server and the model name. The valid value for the ranks ranges between 1 (i.e., the most impoerant) and the number of attributes.

For example, list attributes with rank between 3 and 6:
     - lowerBound = 3, upperBound = 6

Parameters:
dmsConn - The connection to the data mining server
modelName - The name of the model from which the table name is retrieved
lowerBound - The lower bound of the ranks
upperBound - The upper bound for the ranks
Returns:
String[] - An array of attribute names that meet the specified criteria
Throws:
SQLException -
     - if the model table does not exist in the database
     - if the model name is invalid
InvalidArgumentException -
     - if modelName is null
     - if dmsConn is null
     - if lowerBound is less than 1
     - if upperBound is less than 1
     - if lowerBound is greater than or equal to upperBound
MiningObjectException -
     - if the model with the specified name does not exist
ODMException - if modelName is empty or exceeds 64 characters in length

getAttributeSetByPercentage

public static AttributeImportanceEntry[] getAttributeSetByPercentage(Connection dmsConn,
                                                                     java.lang.String modelName,
                                                                     float percentage,
                                                                     boolean aboveThreshold)
                                                              throws java.sql.SQLException,
                                                                     InvalidArgumentException,
                                                                     MiningObjectException,
                                                                     ODMException
Returns an array of attribute importance entries whose importance ranks fall in the specified percentile, given the connection to the data mining server and the model name. The valid value for the percentage ranges between 0 and 1.

For example, list the attributes importance entries whose rank >= (10% total number of attributes)
     - percentage = 0.1, aboveThreshold = false

Parameters:
dmsConn - The connection to the data mining server
modelName - The name of the model from which the table name is retrieved
percentage - The value for percentage of attributes
aboveThreshold - Returns an array of entries whose importance ranks are within the top percentage% if true, or returns an array of entries whose importance ranks are within the bottom percentage% if false.
Returns:
AttributeImportanceEntry[] - An array of attribute importance entries that meet the specified criteria
Throws:
SQLException -
     - if the model table does not exist in the database
     - if the model name is invalid
InvalidArgumentException -
     - if modelName is null
     - if dmsConn is null
     - if percentage is less than 0, or
     - if percentage is greater than 1.
MiningObjectException -
     - if the model with the specified name does not exist
ODMException - if modelName is empty or exceeds 64 characters in length

getAttributesByPercentage

public static java.lang.String[] getAttributesByPercentage(Connection dmsConn,
                                                           java.lang.String modelName,
                                                           float percentage,
                                                           boolean aboveThreshold)
                                                    throws java.sql.SQLException,
                                                           InvalidArgumentException,
                                                           MiningObjectException,
                                                           ODMException
Returns an array of attribute names whose importance ranks fall in the specified percentile, given the connection to the data mining server and the model name. The valid value for the percentage ranges between 0 and 1.

For example, list the attributes names whose rank >= (10% total number of attributes)
     - percentage = 0.1, aboveThreshold = false

Parameters:
dmsConn - The connection to the data mining server
modelName - The name of the model from which the table name is retrieved
percentage - The value for percentage of attributes
aboveThreshold - Returns an array of attribute names whose importance ranks are within the top percentage% if true, or returns an array of attribute names whose importance ranks are within the bottom percentage% if false.
Returns:
String[] - An array of attribute importance entries that meet the specified criteria
Throws:
SQLException -
     - if the model table does not exist in the database
     - if the model name is invalid
InvalidArgumentException -
     - if modelName is null
     - if dmsConn is null
     - if percentage is less than 0, or
     - if percentage is greater than 1.
MiningObjectException -
     - if the model with the specified name does not exist
ODMException - if modelName is empty or exceeds 64 characters in length

getAttributes

public java.lang.String[] getAttributes(AttributeImportanceEntry[] entries)
Returns an array of attribute names that correspond to the specified array of AttributeImportanceEntry objects
Parameters:
entries - An array of AttributeImportanceEntry objects
Returns:
String[] An array of attribute names

restore

public static AttributeImportanceModel restore(Connection dmsConn,
                                               java.lang.String modelName)
                                        throws java.sql.SQLException,
                                               MiningObjectException,
                                               InvalidArgumentException,
                                               ODMException
Returns an instance of AttributeImportanceModel with the specified name persisted in the data mining server given a connection to the data mining server and the model name.
Parameters:
dmsConn - The connection to the data mining server
modelName - The name of the model to be restored
Returns:
AttributeImportanceModel - An instance of AttributeImportanceModel restored
Throws:
InvalidArgumentException -
     - if modelName is null
     - if dmsConn is null
ODMException - when modelName is empty or exceeds 64 acharacter in length.
- SQLException
     - if the model table does not exist in the database
     - if the model name is invalid
MiningObjectException - when the restored model is not an instance of AttributeImportanceModel.