NeticaSession-class {RNetica} | R Documentation |
"NeticaSession"
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.
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.
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.
signature(x = "NeticaSession")
: Returns true
if the link to Netica is currently active and available and false if
not.
signature(session = "NeticaSession")
:
Starts the Netica session and makes it available.
signature(session = "NeticaSession")
:
Stops the Netica session and makes all NeticaBN
and
NeticaNode
objects inactive.
signature(session = "NeticaSession")
:
Stops and restarts the session.
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.
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.
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:
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.
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.
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.
Russell Almond
https://pluto.coe.fsu.edu/RNetica/
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
.
## 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)