StartNetica {RNetica}R Documentation

Starting and stopping the Netica shared library.

Description

This function creates (or destroys) a Netica environment. The StartNetica function also allows you to set various parameters associated with the Netica environment.

Usage

startSession(session)
stopSession(session)
restartSession(session)
StartNetica(license = LicenseKey, checking = NULL, maxmem = NULL,
           session=NeticaSession(LicenseKey=license, checking=checking,
                                 maxmem=maxmem))
StopNetica(session=getDefaultSession())

Arguments

session

An object of class NeticaSession which encapsulates the connection to Netica.

license

A string containing a license key from Norsys. If this is NULL the limited student/demonstration version of Netica is used rather than the full version. If the variable NeticaLicenseKey is set before RNetica is loaded, then the value of that variable at the time the package is loaded will become the default for license.

checking

A character string containing 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 NULL uses the Netica default which is "REGULAR_CHECK".

maxmem

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

Details

The generic functions startSession and stopSession start and stop the connection to Netica. Note that the session is active (is.active) if the session has been started, and inactive if it was stopped (or not yet started). The generic function restartSession stops the session and starts it again.

The functions StartNetica and StopNetica are depricated, but still included for backwards compatability. The function StartNetica will now create a new object of class NeticaSession passing its arguments to the constructor. It will also set a variable DefaultNeticaSession in the global environment to the new session. As this is the value returned by getDefaultSession() this will cause RNetica to behave like the previous versions where the session pointer was stored internally to the C code. The function StopNetica operates on the default session if no explicit argument is given.

Netica is commercial software. The RNetica package downloads and installs the demonstration version of Netica which is limited in its functionality (particularly in the size of the networks it handles). Unlocking the full version of Netica requires a license key which can be purchased from Norsys (http://www.Norsys.com/). They will send a license key which unlocks the full capabilities of the shared library. This can be passed as the first argument to StartNetica(). If the value of the first argument is NULL then the demonstration version is used instead of the licensed version (could be useful for testing).

Prior to RNetica version 0.5, RNetica looked for a variable called NeticaLicenseKey in the global workspace when RNetica is loaded. This then becomes the default value for both StartNetica and getDefaultSession(). If no value is set for NeticaLicenseKey, the default value for license is set to NULL, which loads the demo version of Netica.

In version 0.5 and later of RNetica, the recommended way to store the license is to create a default session and store it in the variable DefaultNeticaSession in the global environment. This session object then contains the license key.

The checking argument, if supplied, is used to call the Netica function ArgumentChecking_ns(). See the documentation of that function for the meaning of the codes. The default value, "REGULAR_CHECK" is appropriate for most development situations.

The maxmem argument, if supplied, is used to limit the amount of memory used by Netica. This is passed in a call to the Netica function LimitMemoryUsage_ns(). Netica will complain if this value is less than 200,000. Leaving this as NULL will not place limits on the size of Netica's memory for tables and things.

The function StopNetica() calls the Netica function CloseNetica_bn(). It is mainly used when one wants to stop Netica and restart it with other parameters.

As of RNetica 0.5, the function StartNetica is no longer called when the package is attached (in the .onAttach() function). Instead, users should start Netica scripts with startSession(DefaultNeticaSession). Note that the pathnames of recently loaded networks are stored in the session object, so that networks can be quickly re-read from a saved session.

Value

These functions now all return an object of class NeticaSession. Note that StartNetica sets the value of DefaultNeticaSession in the global environment to the value of the session argument.

License

The Netica API is not free-as-in-speech software, the use of the Netica shared library makes you subject to the Netica License agreement (which can be found in the RNetica folder in your R library. If you do not agree to the terms of that license, please uninstall RNetica.

The Netica API is also not free-as-in-beer software. The demonstration version of the Netica API, however, is. In order for you to make full use of the RNetica API, you must purchase a Netica API license from Norsys (http://norsys.com/).

RNetica itself (the glue layers between R and Netica) is free (in both the speech and beer senses) software. Suggestions for improvements and bug fixes are welcome.

Implementation Notes

Starting with RNetica 0.5, the Netica environment pointer, which is used by the Netica shared library is stored inside of the NeticaSession object instead of as a global object in the C code. The function is.active() checks to see whether that pointer is set (active) or null (inactive). Note that when a session object is saved, the session pointer is not saved and should be set to null.

The pre verison 0.5 method used a variable NeticaLicenseKey in the global environment to store the license key. The post 0.5 method uses a variable DefaultNeticaSession to store a session object instead, but for backwards compatability, it will try to create a session using the value of NeticaLicenseKey if no default session exists.

Author(s)

Russell Almond

References

http://norsys.com/onLineAPIManual/index.html: NewNeticaEnviron_ns(), InitNetica2_bn(), CloseNetica_bn(), LimitMemoryUsage_ns(), ArgumentChecking_ns()

See Also

NeticaSession, NeticaSession(), NeticaVersion(), CreateNetwork()

Examples

## Not run: 
## Recommended way of doing things
DefaultNeticaSession <- NeticaSession(LicenseKey="Code from Norsys")
startSession(DefaultNeticaSession)

## If DefaultNeticaSession was created in a previous R session
## Re-read the networks.
for (netname in DefaultNeticaSession$listNets()) {
  net <- DefaultNeticaSession$findNet(netname)
  ReadNetworks(GetNetworkFileName(net),DefaultNeticaSession)
}

restartSession(DefaultNeticaSession)
stopSession(DefaultNeticaSession)

## Depricated methods
StartNetica("License key from Norsys")                  
StopNetica()
## Get the version of Netica.


## End(Not run)

[Package RNetica version 0.8-2 Index]