oracle.dmt.odm.data
Class LogicalDataSpecification

java.lang.Object
  |
  +--oracle.dmt.odm.MiningObject
        |
        +--oracle.dmt.odm.data.LogicalDataSpecification

All Implemented Interfaces:

java.io.Serializable

public class LogicalDataSpecification

extends MiningObject

An instance of LogicalDataSpecification (LDS) is used to describe the logical characteristics of the data used in model building, and is composed of a set of mining attributes. The mining attributes contained in an LDS must have unique names.

An instance of LogicalDataSpecification can be constructed in two ways:

1. To create an empty LogicalDataSpecification object, then add mining attributes. For example:
   LogicalDataSpecification lds = new LogicalDataSpecification();
lds.addAttribute( mAttr1 );
lds.addAttribute( mAttr2 );
...
2. To create a LogicalDataSpecification object using the create utility method, which creates the LDS based on an input table. The user can use either transactional or non-transactional tables. For example:
   LogicalDataSpecification lds = LogicalDataSpecification.create(dmsConn, pds);

Supported Oracle database Data types by ODM Java API and their defaults

Oracle database data type	Default Data Type	Default Attribute Type
VARCHAR2	String	Categorical
CHAR with greater than 1 length	String	Categorical
NUMBER	Float	Numerical
NUMBER with zero scale	Int	Numerical
CLOB	Unstructured	Text
BLOB	Unstructured	Text
BFILE	Unstructured	Text
XMLTYPE	Unstructured	Text
URITYPE	Unstructured	Text

Since:

ODM 9.0.1

See Also:

MiningAttribute, MiningFunctionSettings, Serialized Form

Constructor Summary

LogicalDataSpecification()
Creates an instance of LogicalDataSpecification with the specified array of MiningAttributes.

Method Summary

void	addAttribute(MiningAttribute attribute) Adds a mining attribute to the LDS.
void	adjustNonStringAttributesType(java.lang.String[] attrNames, AttributeType changeToType) Deprecated. As of 10.1.0, replaced by MiningFunctionSettings.adjustAttributesType method.
static LogicalDataSpecification	create(Connection dmsConn, PhysicalDataSpecification pds) Creates an instance of LogicalDataSpecification with the default settings based on the database table specified in the input.
static LogicalDataSpecification	create(java.lang.String dbUrl, java.lang.String userName, java.lang.String password, java.lang.String tableName, java.lang.String schemaName, PhysicalDataSpecification pds) Deprecated. As of ODM 9.2.0. Use other create method.
boolean	equals(LogicalDataSpecification lds) Checks the equality of two logical data specifications.
LocationAccessData	getCategoricalDiscretizationTable() Gets the LocationAccessData pointing to the categorical discretization tables.
MiningAttribute	getMiningAttribute(java.lang.String name) Returns a mining attribute with the specified name in the LDS.
MiningAttribute[]	getMiningAttributes() Returns an array of mining attributes contained in the LDS.
int	getMiningAttributesCount() Returns the total count of mining attributes contained in the LDS.
LocationAccessData	getNumericalDiscretizationTable() Gets the LocationAccessData pointing to the numerical discretization tables.
void	setUserSuppliedDiscretizationTables(LocationAccessData numericalBoundaryTable, LocationAccessData categoricalBoundaryTable) Sets the user specified discretization tables(a.k.a bin boundary tables).

Methods inherited from class java.lang.Object

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

Constructor Detail

LogicalDataSpecification

public LogicalDataSpecification()

Creates an instance of LogicalDataSpecification with the specified array of MiningAttributes. A valid LogicalDataSpecification object must have mining attributes defined corresponding to the input mining data.

Method Detail

getMiningAttributes

public MiningAttribute[] getMiningAttributes()

Returns an array of mining attributes contained in the LDS. Returns null if this LDS is empty.

Returns:

An array of mining attributes

getMiningAttribute

public MiningAttribute getMiningAttribute(java.lang.String name)

Returns a mining attribute with the specified name in the LDS. Returns null if no mining attribute exists with the specified name.

Parameters:

name - An attribute name

Returns:

A mining attribute with the given name

addAttribute

public void addAttribute(MiningAttribute attribute)
                  throws InvalidArgumentException

Adds a mining attribute to the LDS.

The name of the mining attribute being added must be unique in the LDS. Otherwise, the mining function settings object containing this LDS would become invalid, which is checked when store method in MiningFunctionSettings is invoked.

Parameters:

attribute - An instance of mining attribute

Throws:

InvalidArgumentException -

• when the attribute is null, or
• when the attribute name is not unique.

See Also:

MiningFunctionSettings

equals

public boolean equals(LogicalDataSpecification lds)

Checks the equality of two logical data specifications. Returns true when both LDS objects have the same mining attributes, false when lds is null or does not have the same mining attributes.

Parameters:

lds - An instance of LDS to be compared to this instance

Returns:

true if equal, false otherwise

See Also:

MiningAttribute

create

public static LogicalDataSpecification create(java.lang.String dbUrl,
                                              java.lang.String userName,
                                              java.lang.String password,
                                              java.lang.String tableName,
                                              java.lang.String schemaName,
PhysicalDataSpecification pds)
                                                           throws InvalidArgumentException,
                                                                  java.sql.SQLException,
ODMException

Deprecated. As of ODM 9.2.0. Use other create method.

Creates an instance of LogicalDataSpecification from the specified database table. This method supports both transactional and non-transaction data.

Default settings of MiningAttribute in the LDS are based on the table column data type.

• Table columns with datatype NUMBER(x,y), will have default attribute type as numerical.
• Table columns with other datatypes, will have default attribute type as categorical.

Mining attributes of type string must be categorical. To adjust non-string attribute types, use adjustNonStringAttributeType method.

Parameters:

dbUrl - A JDBC URL like jdbc:oracle:thin:@host:port:sid

userName - A user name

password - The password of the specified user name

tableName - An input table name from which a logical data specification is to be created

schemaName - The schema name where the specified input table is located

pds - A physical data specification that describes the input table

Returns:

An instance of logical data specification created

Throws:

InvalidArgumentException - when an invalid argument is passed

java.sql.SQLException - when there is a failure in JDBC calls

ODMException

See Also:

AttributeUsage,
create( oracle.dmt.odm.Connection dmsConn, PhysicalDataSpecification pds )

create

public static LogicalDataSpecification create(Connection dmsConn,
PhysicalDataSpecification pds)
                                                           throws InvalidArgumentException,
                                                                  java.sql.SQLException,
ODMException

Creates an instance of LogicalDataSpecification with the default settings based on the database table specified in the input.

Default settings of MiningAttribute in the LDS are based on the table column data type.

• Table columns with datatype NUMBER(x,y), will have default attribute type as 'Numerical'
• Table columns with other datatypes, will have default attribute type as "Categorical'

Mining attributes of type string must be categorical. To adjust non-string attribute types, use adjustNonStringAttributeType method.

Parameters:

dmsConn - A connection to the data mining server

pds - Input physical data specification used to create the associated logical data specification

Returns:

An instance of logical data specification created

Throws:

InvalidArgumentException -

• when dmsConn or pds is null, or
• when pds does not contain a LocationAccessData.

java.sql.SQLException - when there is a failure in JDBC calls.

ODMException

Since:

9.2.0

See Also:

LocationAccessData, PhysicalDataSpecification

adjustNonStringAttributesType

public void adjustNonStringAttributesType(java.lang.String[] attrNames,
AttributeType changeToType)
                                   throws InvalidArgumentException

Deprecated. As of 10.1.0, replaced by MiningFunctionSettings.adjustAttributesType method.

Changes the attribute type of the spceified mining attributes in the LDS.

This method is especially useful when LDS is created using the create utility method. Scine create method uses the table column datatype as the basis for defining attribute type, this method provides a convenient way to modify the attribute types.

Parameters:

attrNames - The names of mining attributes to be changed

changeToType - New attribute type

Throws:

InvalidArgumentException -

• when attrNames or changeToType is null, or
• when pds does not contain a LocationAccessData.

See Also:

AttributeType

getMiningAttributesCount

public int getMiningAttributesCount()

Returns the total count of mining attributes contained in the LDS.

Returns:

The total count of mining attributes

setUserSuppliedDiscretizationTables

public void setUserSuppliedDiscretizationTables(LocationAccessData numericalBoundaryTable,
LocationAccessData categoricalBoundaryTable)
                                         throws InvalidArgumentException

Sets the user specified discretization tables(a.k.a bin boundary tables). This feature allows the api user to supply a pair of bin boundary tables to be specified for the current LDS. These will be used during the build phase and stored with the model. The tables will be used to bin the test, lift and apply datasets.

USAGE : To use this feature, mark all the attributes that need preparation as Unprepared. The bin boundary tables must contain information to bin all the attributes that are unprepared. Assuming this is the api user's responsibility, ODM wll not validate the list of unprepared attributes against the contents of bin boundary tables. Supplying the bin boundary table names, will switch off automatic bin boundary tables creation. The supplied tables will be used instead. The schema of the supplied bin boundary tables MUST match the schema of the tables created using Transformation.createDiscretizationTables

Parameters:

numericalBoundaryTable - User supplied numerical boundary table

categoricalBoundaryTable - User supplied categorical boundary table

Throws:

InvalidArgumentException - is thrown - when one of the LocationAccessData objects is null

Since:

10.1.0

getNumericalDiscretizationTable

public LocationAccessData getNumericalDiscretizationTable()

Gets the LocationAccessData pointing to the numerical discretization tables.

Returns:

Numerical discretization table location details

Since:

10.1.0

getCategoricalDiscretizationTable

public LocationAccessData getCategoricalDiscretizationTable()

Gets the LocationAccessData pointing to the categorical discretization tables.

Returns:

Categorical discretization table location details

Since:

10.1.0