com.bayesia.api

Class APILearning

java.lang.Object

com.bayesia.api.APILearning

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public final class APILearning
extends java.lang.Object
implements java.io.Closeable

The class APILearning is used to perform supervised or unsepervised structure and parameter learning from given data and generate a bayesian network. The bayesian network can be generated directly from the information provided by the input database or can be updated from an existing network and the given database. Once learned, the bayesian network can be save into an xbl file. This format is used by BayesiaLab from Bayesia.

Most of the provided learning algorithms use the Minimum Description Length (MDL) as optimization score. The goal is to minimize this score.

In order to describe the input data, the Database must provide a NetworkDescriptor. If there is no initial network, the new network is created from the information given by this descriptor, otherwise, the API checks if the given network and the descriptor match perfectly.

The class APILearning allows using networks containing discrete and continuous variables. The continuous variables must be discretized. To achieve discretization, you can use APIUtils.discretize(DiscretizationSettings, double[], double[]) and APIUtils.discretize(TargetedDiscretizationSettings, double[], double[], short[]).

All the methods of this class can throw an instance of IllegalOperationException which is a subclass of RuntimeException so you can avoid to catch them.

Version:

4.2

Author:

Bayesia S.A.S.

Constructor Summary

Constructors

Constructor and Description
APILearning(Database database, BayesianNetworkTransferHandler networkHandler, java.lang.String licenseKey) Create a new APILearning with the network stored in the specified BayesianNetworkTransferHandler.
APILearning(Database database, BayesianNetworkTransferHandler networkHandler, java.lang.String licenseServerHost, int licenseServerPort, java.lang.String userName, java.lang.String password, java.lang.String account) Create a new APILearning with the network stored in the specified BayesianNetworkTransferHandler.
APILearning(Database database, java.io.InputStream stream, java.lang.String licenseKey) Create a new APILearning with the network read from the specified InputStream.
APILearning(Database database, java.io.InputStream stream, java.lang.String licenseServerHost, int licenseServerPort, java.lang.String userName, java.lang.String password, java.lang.String account) Create a new APILearning with the network read from the specified InputStream.
APILearning(Database database, java.lang.String licenseKey) Create a new APILearning with an empty bayesian network named new.xbl.
APILearning(Database database, java.lang.String licenseServerHost, int licenseServerPort, java.lang.String userName, java.lang.String password, java.lang.String account) Create a new APILearning with an empty bayesian network named new.xbl.
APILearning(Database database, java.lang.String fileName, java.lang.String licenseKey) Create a new APILearning with the network stored in the specified file.
APILearning(Database database, java.lang.String fileName, java.lang.String licenseServerHost, int licenseServerPort, java.lang.String userName, java.lang.String password, java.lang.String account) Create a new APILearning with the network stored in the specified file.

Method Summary

Modifier and Type	Method and Description
void	close() Method used to close the current instance of APILearning.
BayesianNetworkTransferHandler	exportNetwork(java.lang.String networkName) Exports the created network with the specified name into a BayesianNetworkTransferHandler in order to used it with the APIInference for example.
double	performLearning(LearningSettings learningSettings) Perform the learning algorithm corresponding to the given LearningSettings.
void	save(java.io.OutputStream stream) Saves the created network into the specified OutputStream.
void	save(java.lang.String path) Saves the created network to the file specified by the given path.

Methods inherited from class java.lang.Object

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

Constructor Detail

APILearning

public APILearning(Database database,
                   java.lang.String licenseKey)

Create a new APILearning with an empty bayesian network named new.xbl. You must provide a valid license key for learning.

Parameters:

database - an instance of Database

licenseKey - the key of the license.

APILearning

public APILearning(Database database,
                   java.lang.String licenseServerHost,
                   int licenseServerPort,
                   java.lang.String userName,
                   java.lang.String password,
                   java.lang.String account)

Create a new APILearning with an empty bayesian network named new.xbl. You must provide the host and the port of the license server. You must provide also the user name and the password of an access added to the license. This access must be associated to this license on the LicenseServer by using the Management Console of BayesiaLicenseServer. Use this constructor if you use a license server.

Parameters:

database - an instance of Database

licenseServerHost - the host of the license server.

licenseServerPort - the port of the license server.

userName - the user name corresponding to an existing access added to the license on the license server. Cannot be null.

password - the password corresponding to the access added to the license on the license server. Cannot be null.

account - the account corresponding to the license. Cannot be null, but can be set as empty String on dedicated BLS.

APILearning

public APILearning(Database database,
                   java.lang.String fileName,
                   java.lang.String licenseKey)

Create a new APILearning with the network stored in the specified file. You must provide a valid license key for learning.

Parameters:

database - an instance of Database

fileName - the name of the xbl file containing the network

licenseKey - the key of the license.

APILearning

public APILearning(Database database,
                   java.lang.String fileName,
                   java.lang.String licenseServerHost,
                   int licenseServerPort,
                   java.lang.String userName,
                   java.lang.String password,
                   java.lang.String account)

Create a new APILearning with the network stored in the specified file. You must provide the host and the port of the license server. You must provide also the user name and the password of an access added to the license. This access must be associated to this license on the LicenseServer by using the Management Console of BayesiaLicenseServer. Use this constructor if you use a license server.

Parameters:

database - an instance of Database

fileName - the name of the xbl file containing the network

licenseServerHost - the host of the license server.

licenseServerPort - the port of the license server.

userName - the user name corresponding to an existing access added to the license on the license server. Cannot be null.

password - the passord corresponding to the access added to the license on the license server. Cannot be null.

account - the account corresponding to the license. Cannot be null, but can be set as empty String on dedicated BLS.

APILearning

public APILearning(Database database,
                   BayesianNetworkTransferHandler networkHandler,
                   java.lang.String licenseKey)

Create a new APILearning with the network stored in the specified BayesianNetworkTransferHandler. You must provide a valid license key for learning.

Parameters:

database - an instance of Database

networkHandler - the transfer handler containing the network

licenseKey - the key of the license.

APILearning

public APILearning(Database database,
                   BayesianNetworkTransferHandler networkHandler,
                   java.lang.String licenseServerHost,
                   int licenseServerPort,
                   java.lang.String userName,
                   java.lang.String password,
                   java.lang.String account)

Create a new APILearning with the network stored in the specified BayesianNetworkTransferHandler. You must provide the host and the port of the license server. You must provide also the user name and the password of an access added to the license. This access must be associated to this license on the LicenseServer by using the Management Console of BayesiaLicenseServer. Use this constructor if you use a license server.

Parameters:

database - an instance of Database

networkHandler - the transfer handler containing the network

licenseServerHost - the host of the license server.

licenseServerPort - the port of the license server.

userName - the user name corresponding to an existing access added to the license on the license server. Cannot be null.

password - the password corresponding to the access added to the license on the license server. Cannot be null.

account - the account corresponding to the license. Cannot be null, but can be set as empty String on dedicated BLS.

APILearning

public APILearning(Database database,
                   java.io.InputStream stream,
                   java.lang.String licenseKey)

Create a new APILearning with the network read from the specified InputStream. You must provide a valid license key for learning.

Parameters:

database - an instance of Database

stream - the stream of the xbl file containing the network

licenseKey - the key of the license.

APILearning

public APILearning(Database database,
                   java.io.InputStream stream,
                   java.lang.String licenseServerHost,
                   int licenseServerPort,
                   java.lang.String userName,
                   java.lang.String password,
                   java.lang.String account)

Create a new APILearning with the network read from the specified InputStream. You must provide the host and the port of the license server. You must provide also the user name and the password of an access added to the license. This access must be associated to this license on the LicenseServer by using the Management Console of BayesiaLicenseServer. Use this constructor if you use a license server.

Parameters:

database - an instance of Database

stream - the stream of the xbl file containing the network

licenseServerHost - the host of the license server.

licenseServerPort - the port of the license server.

userName - the user name corresponding to an existing access added to the license on the license server. Cannot be null.

password - the passord corresponding to the access added to the license on the license server. Cannot be null.

account - the account corresponding to the license. Cannot be null, but can be set as empty String on dedicated BLS.

Method Detail

performLearning

public double performLearning(LearningSettings learningSettings)

Perform the learning algorithm corresponding to the given LearningSettings. Return the score final score obtained by the network (MDL or other)

Parameters:

learningSettings - the settings of the learning algorithm

Returns:

the score of the learned network

save

public final void save(java.lang.String path)

Saves the created network to the file specified by the given path. The extension of the file must be xbl. The name of the network is now the name of the file.

Parameters:

path - the path to an xbl file

save

public final void save(java.io.OutputStream stream)

Saves the created network into the specified OutputStream.

Parameters:

stream - the output stream where the network is saved

exportNetwork

public final BayesianNetworkTransferHandler exportNetwork(java.lang.String networkName)

Exports the created network with the specified name into a BayesianNetworkTransferHandler in order to used it with the APIInference for example. The name of the network must be terminated by .xbl

Parameters:

networkName - the new name of the network with the xbl extension

Returns:

a handler containing the network

close

public final void close()

Method used to close the current instance of APILearning.

WARNING: If you use a license server, this method must be called once you don't need the instance anymore. It allows to release the license on the license server.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable