NORSYS SOFTWARE © 2012

NETICA API

JAVA VERSION 5.04

norsys.netica
Class Caseset

java.lang.Object
  |
  +--norsys.netica.Caseset

public class Caseset

extends java.lang.Object

A collection of cases. Currently this class is used only by the Learner class.

Since:

v2.26

Version:

5.04 - January 21, 2012

Constructor Summary

Caseset()

Creates and returns a new Caseset, initially containing no cases, in the default environment, and with a name of null.

Caseset(java.lang.String name, Environ env)

Creates and returns a new Caseset, initially containing no cases.

Method Summary

void	addCases(DatabaseManager dbMgr, double degree, NodeList nodeList, java.lang.String columnNames, java.lang.String tables, java.lang.String condition, java.lang.String options) Searches the database attached to dbMgr for cases to add to this caseset.
void	addCases(Streamer inStream, double degree, java.lang.String options) Indicates that all the cases within inStream should be added to this caseset.
void	finalize() Removes the Caseset and frees all its resources (e.g., memory).
Environ	getEnviron() Returns the Environ that this object belongs to.
void	writeCases(Streamer outStream, java.lang.String options) Writes all the cases within this Caseset to outStream.

Methods inherited from class java.lang.Object

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

Constructor Detail

public Caseset ( ) throws NeticaException

Creates and returns a new Caseset, initially containing no cases, in the default environment, and with a name of null.

Currently, Casesets are used in batch learning (see Learner.learnCPTs), but in future they will be used for much more.

Version:

Versions 2.26 and later have this method.

See Also:

Caseset(String,Environ)		Same, but for any environment and assigns name
finalize		Release the resources (e.g., memory) used by the Caseset
addCases		Add cases from text stream
addCases		Add cases from a database
Learner.learnCPTs		Use the Caseset for batch learning

public Caseset (

String	name,
Environ	env

) throws NeticaException

Creates and returns a new Caseset, initially containing no cases.

name can be null, or a legal IDname, which means it must have NAME_MAX (30) or fewer characters, all of which are letters, digits or underscores, and it must start with a letter.

name will be used in Netica error messages to identify the case-set, and in future versions of Netica it will have further uses.

Netica will make a copy of name; it won't modify or free the passed string.

Parameters:

String		name		The name of this caseset.
Environ		env		The Environ in which this new caseset will be placed.

Version:

Versions 2.26 and later have this method. In versions previous to 3.15 this method did not have the name parameter.
In the C Version of the API, this function is named NewCaseset_cs.

See Also:

Caseset()		Same, but for the default environment and no name
finalize		Release the resources (e.g., memory) used by the Caseset
addCases		Add cases from text stream
addCases		Add cases from a database
Learner.learnCPTs		Use the Caseset for batch learning

Method Detail

public void addCases (

Streamer	inStream,
double	degree,
String	options

) throws NeticaException

Indicates that all the cases within inStream should be added to this caseset.

degree indicates how each case in the stream should be weighted. See reviseCPTsByFindings for more information about the relative weighting of cases.

Pass null for options. It is only for future expansion.

TEMPORARY LIMITATION: Currently you can only add one file or database retrieval to a caseset.

Parameters:

Streamer		inStream		The stream to search for cases
double		degree		A frequency factor to apply to each case in the stream
String		options		For future expandability. Pass null for now.

Version:

Versions 2.26 and later have this method.
In the C Version of the API, this function is named AddFileToCaseset_cs.

See Also:

writeCases		Reverse method.
Caseset		Create a new Caseset.
finalize		Free the resources (e.g., memory) used by the Caseset.
Learner.learnCPTs		Use the Caseset for learning.
testWithCaseset		Use the Caseset for testing a net.
addCases		Add cases from a database instead of a stream.

public void addCases (

DatabaseManager	dbMgr,
double	degree,
NodeList	nodeList,
String	columnNames,
String	tables,
String	condition,
String	options

) throws NeticaException

Searches the database attached to dbMgr for cases to add to this caseset.

The cases are retrieved from the database by invoking the SQL¹ SELECT statement:

SELECT columnNames FROM tables WHERE condition.

degree indicates how each case that is retrieved should be weighted. See reviseCPTsByFindings for more information about the relative weighting of cases.

nodeList represents the nodes whose values will be selected. It must not be null, and must contain at least one node.

columnNames is a comma-delimited list of database column names. The names in this list must be in the exact same order as their corresponding nodes in nodeList. If columnNames is null, then for each Node, Netica will use that Node's title (or, if title not defined, then the name) as the corresponding column name. If you are selecting columns from different tables, then you cannot use the null option just mentioned, and you must also prefix the column names with the table name followed by a period, as per the standard SQL syntax.

tables is a comma-delimited list of database table names. If the database has only one conventional (non-system) table, then you can submit null for this parameter and Netica will find the implied table for you.

condition is the text following the "WHERE" clause. It may be null.

Pass null for options; it is only for future expansion.

Thus, for the SQL command SELECT col1,col2,...,colN FROM table1 WHERE surname="smith", tables should be "table1"; columnNames should be "col1,col2,...,colN"; nodeList should be a list of nodes in the order node1, node2, ..., nodeN; and condition should be "surname=\"smith\"".

If there is a problem with the SQL SELECT command, a Netica exception will be thrown explaining the nature of the problem.

NOTICE:After calling this, you should not modify the database until you are done with the Caseset.

TEMPORARY LIMITATION: Currently you can only add one file or database retrieval to a caseset.

¹ SQL is a standard query language for accessing databases. To properly use this method, you should have basic familiarity with the SQL SELECT statement.

Parameters:

DatabaseManager		dbMgr		the database to search.
double		degree		A frequency factor to apply to each case retrieved.
NodeList		nodeList		The nodes whose values will be selected.
String		columnNames		The comma-delimited list of database column names, in the same order as the nodes in nodeList. If null, then Netica will use the Node titles or names as the column names.
String		tables		the comma-delimited list of database table names into which you are selecting. May be null, if the database has only one conventional (non-system) table.
String		condition		the conditions that follow the "WHERE" clause in a SQL SELECT statement.
String		options		For future expandability. Pass null for now.

Version:

Versions 3.15 and later have this method.
In the C Version of the API, this function is named AddDBCasesToCaseset_cs.

See Also:

DatabaseManager		Creates the DatabaseManager
Caseset		Create an empty Caseset
addCases		Add cases from text stream instead of database

Example:

Here is an example program to use EM learning to learn Bayes net parameters
 from a database:
 DatabaseManager dbMgr = new DatabaseManager( 
      "driver=Microsoft Access Driver (*.mdb); dbq=.\\myDB.mdb;UID=dba1;",
      "pooling",  // enableConnectionPooling
      env );
 Net net = new Net();
 net.setName ("databaseTestNet");
 Node sexNode       = new Node ("sex",       2, net);
 Node heightNode    = new Node ("height",    0, net);
 Node ownsHouseNode = new Node ("ownsHouse", 2, net);
 Node numDogsNode   = new Node ("numDogs",   0, net);
 NodeList nodes = net.getNodes();
 sexNode.state(0).setName ("M");
 sexNode.state(1).setName ("F");
 Caseset cs = new Caseset();
 cs.addCases (dbMgr,
              1.0,
              nodes, 
              "Sex, Height, \"Owns a house\", \"Number of dogs\"",
              null,
              "'Owns a house' = 'yes'",
              null);
 Learner learner = new Learner (Learner.EM_LEARNING, null, env);
 learner.learnCPTs (nodes, cs, 1.0);
 learner.finalize();
 cs.finalize();

public void finalize ( ) throws NeticaException

Removes the Caseset and frees all its resources (e.g., memory).

Version:

Versions 2.26 and later have this method.
In the C Version of the API, this function is named DeleteCaseset_cs.

See Also:

Caseset

Create a new Caseset.

Overrides:

finalize in class java.lang.Object

public Environ getEnviron ( )

Returns the Environ that this object belongs to.

Version:

Versions 2.26 and later have this method.

public void writeCases (

Streamer	outStream,
String	options

) throws NeticaException

Writes all the cases within this Caseset to outStream.

They are written in the standard Netica case file format.

In future, options will allow you to control what gets copied. For now, pass null.

Parameters:

Streamer		outStream		The stream to receive the cases
String		options		For future expandability. Pass null for now.

Version:

Versions 2.28 and later have this method.
In the C Version of the API, this function is named WriteCaseset_cs.

See Also:

addCases		Reverse method.
Caseset		Create a new Caseset.
finalize		Free the resources (e.g., memory) used by the Caseset.
Learner.learnCPTs		Use the Caseset for learning.