NeticaSession-class {RNetica}R Documentation

Class "NeticaSession"

Description

An R object which provides a link to the Netica session. One of these must be present and active to allow access to Netica from R. This object is also how one enables the Netica license.

Details

A Netica session is an R wrapper for the internal pointer to the Netica workspace. It is used by a number of high-level Netica functions to provide access to the workspace, notably: CreateNetwork, GetNthNetwork, GetNamedNetworks, and ReadNetworks. It is also needed by some lower level functions which create Netica objects: CaseFileDelimiter, CaseFileMissingCode, CaseFileStream, CaseMemoryStream, OpenCaseStream and NewNeticaRNG.

When initially created, the NeticaSession object is not active; that is, the connection to the internal Netica environment is not yet established. Calling the method startSession will start the session, making it active. The method stopSession will deallocate the Netica workspace. Note that it will also make any NeticaBN or NeticaNode objects it contains inactive. The function is.active() tests to see whether the session is currently active.

Starting with the introduction of the NeticaSession class, a license key purchased from Norsys (http://www.norsys.com/) is a field of the NeticaSession class. This field should either be a character scalar giving the complete string supplied by Norsys or a character scalar vector of length zero (the default). The licence key is passed to Netica with the call to startSession(); if it is a valid license key, then Netica starts in unlimited mode. If it is not a valid license key, the Netica will start in a limited mode which restricts the number of objects that can be created. All of the examples in the documentation should work in the limited mode; but people wanting to do serious work will need to purchase a license key.

As the LicenseKey is stored in the NeticaSession object, do not share dumps of the NeticaSession object with people who are not eligible to use your license.

The nets field of the NeticaSession object contains a collection (actually an environment) of all of the networks. They are referenced using their Netica names. In particular, the construct session$nets$netname will return the network named netname if it exists, or NULL. Similarly, the construct session$nets[[netname]] will attempt to return the network whose name is the value of netname. The method session$listNets() lists the names of all networks registered with the session. This collection is maintained by the CreateNetwork, DeleteNetwork, and ReadNetworks, so it is almost certainly an error to try and manually change it. Network objects should be renamed using NetworkName which will update the collection.

Note that if an R workspace containing a NeticaSession object is saved and restored, then the nets field will be a collection of inactive NeticaBN objects corresponding to the networks that were open when the session was saved. As these contain the pathnames where the networks were last saved, it can be used to reload the networks for a project.

It is unknown what would happen if more than one NeticaSession is active at the same time. Many possibilities are less than ideal.

Extends

All reference classes extend and inherit methods from "envRefClass". Note that because this is a reference class unlike traditional S3 and S4 classes it can be destructively modified. Also fields (slots) are accessed using the ‘$’ operator.

Methods

is.active

signature(x = "NeticaSession"): Returns true if the link to Netica is currently active and available and false if not.

startSession

signature(session = "NeticaSession"): Starts the Netica session and makes it available.

stopSession

signature(session = "NeticaSession"): Stops the Netica session and makes all NeticaBN and NeticaNode objects inactive.

restartSession

signature(session = "NeticaSession"): Stops and restarts the session.

Fields

Note these should be regarded as read-only from user code.

LicenseKey:

Object of class character giving the license key obtained from Norsys (http://www.norsys.com/. Leaving this field as character(0) will result in the limited version of Netica being used.

SessionName:

Object of class character giving an identifier for the session. This is just used for printing.

NeticaHandle:

Object of class externalptr giving the C memory location of the Netica API workspace. This should not be manipulated by users. If the session is inactive, this pointer will be nil.

Checking:

Object of class character one of the keywords: "NO_CHECK", "QUICK_CHECK", "REGULAR_CHECK", "COMPLETE_CHECK", or "QUERY_CHECK", which controls how rigorous Netica is about checking errors. A value of character() uses the Netica default which is "REGULAR_CHECK".

maxmem:

Object of class numeric containing an integer indicating the maximum amount of memory to be used by the Netica shared library in bytes. If supplied, this should be at least 200,000.

nets:

Object of class environment used to store NeticaBN objects opened by this session. This should be regarded as read-only by user code.

Class-Based Methods

neticaVersion():

Returns the netica version associated with this session.

show():

Provides information about the session.

isActive():

Returns a logical value indicating whether Netica is currently started.

listNets(pattern=""):

Lists the names of all of the networks registered with this session. If pattern is supplied it should be a regular expression, only nets whose name contains the regular expression will be listed.

initialize(..., SessionName, autostart):

Creates a new session. If autostart is true, then the session will be started after it is created.

findNet(netname):

Returns a NeticaBN object associated with a network, or NULL if no network with that name exists.

clearErrors(severity):

Clears errors of a given severity level or lower. Severity levels in order are: "NOTHING_ERR", "REPORT_ERR", "NOTICE_ERR", "WARNING_ERR", "ERROR_ERR", "XXX_ERR". The default is to report all errors.

reportErrors(maxreport, clear):

Reports errors. The maxreport value gives the maximum number of errors to report. The clear value (default true) asks if errors should be cleared after reporting. Note: errors are reported to standard output, not standard error.

Note

The session object is part of a fundamental redesign of the guts of the way RNetica works starting with version 0.5. There are three features of this redesign:

  1. The old NeticaBN and NeticaNode classes, which were implemented as S3 classes formed by adding attributes to strings, have been replaced with R6 reference classes, which should be more robust. In particular, the c() command strips attributes, which tended to destroy node and net objects.

  2. The session pointer used to be handled with a global variable in the RNetica source code. It is now a field in the new session object. This should allow more flexibility as well as not relying on a hidden mechanism.

  3. Instead of using back-pointers from the Netica objects, Sessions contain an environment where nets are registered and nets contain an environment where nodes are registered. This should fix a problem with the backpointers pointing to the wrong location.

In the earlier design, the session object was hidden. For that reason, the function getDefaultSession() has been added. This looks for an object called DefaultNeticaSession in the gobal environment. If this object does not exist, the user will be prompted to make one the first time getDefaultSession() is called. This is the default for most high level functions which take a section argument; hopefully, this will provide backwards compatability.

The error reporting mechanism now also works through the session object. The session$reportErrors() and session$clearErrors() methods are used to maintain this system. The NeticaBN object contains a back pointer to its session, and delegates error reporting to the session. In particular, net$Session returns the session object. Similarly, a NeticaNode contains a back pointer to the NeticaBN, so node$Net$Session accesses the session.

Author(s)

Russell Almond

References

https://pluto.coe.fsu.edu/RNetica/

See Also

CreateNetwork, GetNthNetwork, GetNamedNetworks, and ReadNetworks. It is also needed by some lower level functions which create Netica objects: CaseFileDelimiter, CaseFileMissingCode, CaseFileStream, CaseMemoryStream, OpenCaseStream and NewNeticaRNG.

NeticaBN

Examples


## Create a limited mode session
## Not run: 
## Create a fully licensed session, and save it as the default
DefaultNeticaSession <- NeticaSession(LicenseKey="License Key from Norsys")

## End(Not run)
sess <- NeticaSession()

startSession(sess)
NeticaVersion(sess)

myNet <- CreateNetwork("myNet",sess)

stopifnot(myNet==sess$nets$myNet)
stopifnot(myNet==sess$nets[["myNet"]])
stopifnot(myNet==sess$findNet("myNet"))
stopifnot(identical(sess$listNets(),c("myNet")))

sess$reportErrors()
sess$clearErrors()  ## Not necessary as the previous statement clears too.

stopSession(sess)

## Not run: 
## Shows how to restore networks from a default session
## Existing in the workspace
for (netname in DefaultNeticaSession$listNets()) {
  net <- DefaultNeticaSession$findNet(netname)
  ReadNetworks(GetNetworkFileName(net),DefaultNeticaSession)
}

## End(Not run)


[Package RNetica version 0.5-4 Index]