Package 'RNetica'

R interface to Netica(R) Bayesian Network Engine

Description

This provides an R interface to the Netica (http://norsys.com/) Bayesian network library API.

Details

The DESCRIPTION file:

Package:	RNetica
Version:	0.10-3
Date:	2024/06/20
Title:	R interface to Netica(R) Bayesian Network Engine
Author:	Russell Almond
Maintainer:	Russell Almond <[email protected]>
Authors@R:	person(given = "Russell", family = "Almond", role = c("aut", "cre"), email = "[email protected]", comment = c(ORCID = "0000-0002-8876-9337"))
Depends:	R (>= 3.0), methods, utils, CPTtools (>= 0.5-3)
Imports:	grDevices, R.utils
Suggests:	knitr, rmarkdown, tidyr, futile.logger
VignetteBuilder:	knitr
Description:	This provides an R interface to the Netica (http://norsys.com/) Bayesian network library API.
License:	file LICENSE
URL:	https://pluto.coe.fsu.edu/RNetica
Collate:	Session.R Networks.R Node.R Edges.R Inference.R Cases.R Experience.R Continuous.R Random.R LoadFuns.R Tester.R
Biarch:	true
Support:	c( 'Bill & Melinda Gates Foundation grant "Games as Learning/Assessment: Stealth Assessment" (#0PP1035331, Val Shute, PI)', 'National Science Foundation grant "DIP: Game-based Assessment and Support of STEM-related Competencies" (#1628937, Val Shute, PI)', 'National Science Foundation grant "Mathematical Learning via Architectural Design and Modeling Using E-Rebuild." (\#1720533, Fengfeng Ke, PI)', 'Institute of Educational Statistics Grant: "Exploring adaptive cognitive and affective learning support for next-generation STEM learning games." (#R305A170376-20, Val Shute and Russell Almond, PIs')
Repository:	https://ralmond.r-universe.dev
RemoteUrl:	https://github.com/ralmond/RNetica
RemoteRef:	HEAD
RemoteSha:	e9c01577ff3f6104b5ace2129ef2bc9ca803381f

This package provides an R interface to the Netica, in particular, it binds many of the functions in the Netica C API into the R language. RNetica can create and modify networks, enter evidence and extract the conditional probabilities from a Netica network.

License

While RNetica (the combination of R and C code that connects R and Netica) is free software, as is R, Netica is a commercial product. Users of RNetica will need to purchase a Netica API license key (which is different from the GUI license key) from Norsys(R) (http://www.norsys.com/).

Once you have a license key, you can use it in one of three ways. The currently (RNetica 0.5 and later) recommended way of using it is to create a Netica Session object that contains it: DefaultNeticaSession <- NeticaSession(LicenseKey="License Key from Norsys"). This will store the key in a NeticaSession object. The special variable DefaultNeticaSession is used as a default for every function requiring a session argument, so can be used to skip the need for explicitly stating the session argument.

Two other mechanisms continue to be supported for backwards compatibility. First, the license key can be used as an argument to the function StartNetica(). This will create a session and store it in NeticaDefaultSession. If the variable NeticaLicenseKey in the R top-level environment is set before the call to library(RNetica), StartNetica() will pick up the license key from that location.

Without the license key, the Netica shared library will be restricted to a student/demonstration mode with limited functionality. Note that all of the example code (and hence R CMD check RNetica) can be run using the limited version.

Note that the NeticaSession object stores the complete Netica license key. Do not share dumps of the session object (including the .RData file containing DefaultNeticaSession) with any third-party.

Index

Index of help topics:

AbsorbNodes             Delete a Netica nodes in a way that maintains
                        the connectivity.
AddLink                 Adds or removes a link between two nodes in a
                        Netica network.
AdjoinNetwork           Links an evidence model network to a system
                        model network.
CalcNodeState           Calculates the state of a node based on logical
                        functions or formulae
CaseFileDelimiter       Gets or sets special characters for case files.
CaseFileStream          A stream of cases for reading/writing Netica
                        findings to a file
CaseMemoryStream        A stream of cases for reading/writing Netica
                        from memory
CaseStream-class        Class '"CaseStream"'
CliqueNode-class        Class '"CliqueNode"'
CompileNetwork          Builds the junction tree for a Netica Network
CopyNetworks            Makes copies of Netica networks.
CopyNodes               Copies or duplicates nodes in a Netica network.
CreateNetwork           Creates (destroys) a new Netica network.
DeleteNodeTable         Deletes the conditional probability table of a
                        Netica node.
EliminationOrder        Retrieves or sets the elimination order used in
                        compiling a Netica network.
EnterFindings           Enters findings for multiple nodes in a Netica
                        network.
EnterGaussianFinding    Enter a numeric finding with uncertainty
EnterIntervalFinding    Enter finding of value within an interval
EnterNegativeFinding    Sets findings for a Netica node to a list of
                        ruled out values.
Extract.NeticaNode      Extracts portions of the conditional
                        probability table of a Netica node.
FadeCPT                 Fades a Netica Conditional Probability Table
FileCaseStream-class    Class '"FileCaseStream"'
FindingsProbability     Finds the probability of the findings entered
                        into a Netica network.
GenerateRandomCase      Generates random cases for nodes in a Netica
                        network
GetNamedNetworks        Finds a Netica network (if it exists) for the
                        name.
GetNetworkAutoUpdate    Turns Netica automatic updating on or off for a
                        network.
GetNthNetwork           Fetch a Netica network by its position in the
                        Netica list.
HasNodeTable            Tests to see if a Netica node has a conditional
                        probability table.
IDname                  Tests to see if a string is a valid as a Netica
                        Identifier.
IsNodeDeterministic     Determines if a node in a Netica Network is
                        deterministic or not.
JointProbability        Calculates the joint probability over several
                        network nodes.
JunctionTreeReport      Produces a report about the junction tree from
                        a compiled Netica network.
LearnCPTs               Learn Conditional Probability Tables with
                        Missing Data.
LearnCases              Learn Conditional Probability Tables from a
                        Netica Case Stream
LearnFindings           Learn Netica conditional probabilities from
                        findings.
MakeCliqueNode          Forces a collection of nodes in a Netica
                        network to be in the same clique.
MemoryCaseStream-class
                        Class '"MemoryCaseStream"'
MemoryStreamContents    Access the contents of a MemoryCaseStream
MostProbableConfig      Finds the configuration of the nodes most
                        likely to have lead to observed findings.
MutualInfo              Calculates strength of relationship between two
                        nodes in a network
NeticaBN                An object referencing a Bayesian network in
                        Netica.
NeticaBN-class          Class '"NeticaBN"'
NeticaNode              An object referencing a node in a Netica
                        Bayesian network.
NeticaNode-class        Class '"NeticaNode"'
NeticaRNG-class         Class '"NeticaRNG"'
NeticaSession           Creates a connection between R and Netica
NeticaSession-class     Class '"NeticaSession"'
NeticaVersion           Fetches the version number of Netica.
NetworkFindNode         Finds nodes in a Netica network.
NetworkFootprint        Returns a list of names of unconnected edges.
NetworkName             Gets or Sets the name of a Netica network.
NetworkNodeSetColor     Returns or sets a display colour to use with a
                        Netica node.b
NetworkNodeSets         Returns a list of node sets associated with a
                        Netica network.
NetworkNodesInSet       Returns a list of node labeled with the given
                        node set in a Netica Network.
NetworkSetPriority      Changes the priority order of the node sets.
NetworkSetRNG           Sets a random number generator associates with
                        the network.
NetworkTester-class     Class '"NetworkTester"'
NetworkTitle            Gets the title or comments associated with a
                        Netica network.
NetworkUndo             Undoes (redoes) a Netica operation on a
                        network.
NetworkUserField        Gets user definable fields associated with a
                        Netica network.
NewDiscreteNode         Creates (or destroys) a node in a Netica
                        Bayesian network.
NewNeticaRNG            Creates a Netica Random Number Generator
NodeBeliefs             Returns the current marginal probability
                        distribution associated with a node in a Netica
                        network.
NodeChildren            Returns a list of the children of a node in a
                        Netica network.
NodeEquation            Gets or sets the equation Netica uses to
                        calculate the CPT for a node
NodeExpectedUtils       Calculates expected utility for each value of a
                        decision node
NodeExpectedValue       Calculates expected value for a numeric node
NodeExperience          Gets or sets the amount of experience
                        associated with a node.
NodeFinding             Returns of sets the observed value associated
                        with a Netica node.
NodeInputNames          Associates names with incoming edges on a
                        Netica node.
NodeKind                Gets or changes the kind of a node in a Netica
                        network.
NodeLevels              Accesses the levels associated with a Netica
                        node.
NodeLikelihood          Returns or sets the virtual evidence associated
                        with a Netica node.
NodeName                Gets or sets name of a Netica node.
NodeNet                 Finds which Netica network a node comes from.
NodeParents             Gets or sets the parents of a node in a Netica
                        network.
NodeProbs               Gets or sets the conditional probability table
                        associated with a Netica node.
NodeSets                Lists or changes the node sets associated with
                        a Netica node.
NodeStateTitles         Accessors for the titles and comments
                        associated with states of Netica nodes.
NodeStates              Accessor for states of a Netica node.
NodeTitle               Gets the title or Description associated with a
                        Netica node.
NodeUserField           Gets user definable fields associated with a
                        Netica node.
NodeValue               Sets the numeric value of a continuous node
NodeVisPos              Gets, sets the visual position of the node on
                        the Netica display.
NodeVisStyle            Gets/sets the nodes visual appearance in
                        Netica.
OpenCaseStream          Functions for manipulating Netica case streams
ParentStates            Returns a list of the names of the states of
                        the parents of a Netica node.
RNetica-package         R interface to Netica(R) Bayesian Network
                        Engine
ReadFindings            Retrieves a record from a Netica Case Stream
RetractNodeFinding      Clears any findings for a Netica node or
                        network.
ReverseLink             Reverses a link in a Netica network.
StartNetica             Starting and stopping the Netica shared
                        library.
WithOpenCaseStream      Evaluate an expression and then close the
                        Netica Case Stream.
WriteFindings           Appends the current findings to a Netica case
                        file.
WriteNetworks           Reads or writes a Netica network from a file.
dgetFromString          Serializes an R object to a string
is.NodeRelated          Computes topological proprieties of a 'Netica'
                        network.
is.active               Check to see if a Netica network or node object
                        is still valid.
is.discrete             Determines whether a Netica node is discrete or
                        continuous.
testNetwork             Performs a classification recovery test on a
                        network.
testerConfusion         Accessor methods for class '"NetworkTester"'
woe                     Calculates the weight of evidence for a
                        hypothesis
write.CaseFile          Read or write data frame in Netica Case File
                        format.

Further information is available in the following vignettes:

ConstructingNetworks	Constructing Networks (source)
Inference	Inference (source)
LicenseKeys	Netica License Keys (source)
RNeticaInternals	RNetica Internals (source)

RNetica Environment and Netica Objects

Netica exists in both as a stand alone graphical tool for building and manipulating Bayesian networks (the Netica GUI) and as a shared library for manipulating Bayesian networks (the Netica API). The RNetica package binds the API version of Netica to a series of R functions which do much of the work of manipulating the network. The file format for the GUI and API version of Netica is identical, so analysts can easily move back and forth between the two. Note that the RNetica environment is separate from other Netica environments that may be created using the Netica GUI (or API invoked from a different program); RNetica can only manipulate the networks that are currently loaded into its environment.

There are five objects which provide a handle for objects in the Netica session. These are:

NeticaSession

This is a container for the overall Netica session. It is referenced when creating other Netica objects (NeticaBNs, CaseStreams and NeticaRNG) and contains the license key needed to activate Netica. Its field $nets is an environment which contains references to all of the networks which have been associate with this session.

NeticaBN

This is a handle for a network object. NeticaNode objects are created within a network, and the $nodes field is an environment which contains node references, at least for those nodes which have been referenced in R code. Networks must have unique names within a session.

NeticaNode

This is a handle for a particular Netica node. Nodes must have unique names within a network. Many inference functions are done based on nodes.

CaseStream

This is a stream of Netica case data, values for particular nodes. There are two subclasses: FileCaseStream and MemoryCaseStream. As of version 5.04 of the Netica API, there are some issues with MemoryCaseStreams, so the FileCaseStreams should be used instead.

NeticaRNG

This a random number generator used by Netica for generating random cases.

All of these follow the envRefClass protocol. In particular, their fields are referenced using ‘$’. Also, all of them have a method $isActive (which is called from the generic function is.active) which determines whether or not the pointer to the Netica object currently exists or not. Calling stopSession will render all Netica objects inactive.

In particular, when quitting and restarting R, the pointers will all be initialised to null, and all of the session, node and network objects will become inactive. Some examples of how to restart an RNetica session are provided below.

To connect R to Netica, it is necessary to create and start a NeticaSession. This is done by first calling the constructor NeticaSession() and then calling the function startSession(session). If you have purchased a Netica license key from Norsys, this can be passed to the constructor with the argument LicenseKey given the value of the license key as a string. Note that the session object can be saved in the workspace, so that it can be used in future R session (it does not need to be recreated, but it must be restarted with a call to startSession). If it is saved to DefaultNeticaSession, this value will be used as a default by all of the functions that use the session as an argument.

Note that this is a change from how RNetica operated prior to version 0.5. In older versions of RNetica, the session pointer was held inside of the C code, and the function StartNetica() was invoked automatically when the RNetica package was attached. Nowt this needs to be done manually through a call to startSession.

The function getDefaultSession() emulates the behaviour of the previous version of RNetica. It is the default value for all of the functions which require a session argument. When invoked, it looks for an object call DefaultNeticaSession in the global environment. If that exists, it is used, if not, a new NeticaSession is created. If the new session is created, it looks for a variable NeticaLicenseKey in the global environment. If that is present, it will use this as a license key. Finally, if the DefaultNeticaSession is not active, it will start it.

Note that it is almost certainly a mistake to have two sessions open at the same time. Users should either set the DefaultNeticaSession, and use the default, or always explicitly pass the session argument to functions that need it.

The following functions take a session argument: CaseFileDelimiter, CaseFileMissingCode, CaseFileStream, CaseMemoryStream, ClearAllErrors, CreateNetwork, GetNthNetwork, GetNamedNetworks, NeticaVersion, ReadNetworks, ReportErrors, StartNetica, StopNetica, startSession, and stopSession.

Netica Networks

NeticaBN objects are created through one of three functions: CreateNetwork(), ReadNetworks() and CopyNetworks. The first two both require a session argument, while the third uses the session from its net argument. When a network is created it is added as a symbol (using its name) to the $nets field of the session. It can then be referenced using session$nets$netname or session$nets[["netname"]]. The field $Session of the NeticaBN points to the NeticaSession object in which the network was created.

Note that session$nets cache may contain inactive network objects for one of two reasons: (1) it is a deleted network object, or (2) this is a session which has been restored from a file, and the Netica pointers have not been reconnected. In particular, quitting R will always deactivate the network.

For networks, the simplest solution is to save each network to a file using WriteNetworks(). If a NeticaBN object net is used in either a net <- ReadNetworks() or WriteNetworks(net) call, then the R object will be badged with the name of the last used filename. Thus, after saving and restoring a R session, the expression net <- ReadNetworks(net) will recreate net as an object pointing to a new network that is identical to the last saved version.

Netica Nodes

NeticaNode objects are created through NewDiscreteNode() or NewContinuousNode(), or retrieved from the network using NetworkFindNode(), NetworkAllNodes(), NetworkNodesInSet(), or one of a variety of other functions that return nodes. When a node is created it is added as a symbol (using its name) to the $node field of the network. It can then be referenced using net$nodesnodename or net$nodes[["nodename"]].

Note that if more than one network is loaded they may have identically named nodes that are not identical. For example, net1 and net2 may both have a node named “Proficiency”. If the R variable Proficiency is bound to the NeticaNode object corresponding to the variable “Proficiency” in net1, it can only be used to access the instance of that variable in net1, not the one in net2.

Note that the NeticaNode object is created when then node is first references in R. In particular, this means when a network is loaded through a call to ReadNetworks, the R objects for the corresponding Netica nodes are not immediately created. The function NetworkAllNodes() returns a list of all nodes in the network, and as a side effect, creates NeticaNode object for all of the nodes found in the network. If the network has many nodes, it may be more efficient to just create R objects for the ones which are used. In this case the functions NetworkFindNode(), and NetworkNodesInSet are useful for finding (and creating R objects for) a subset of nodes.

The following procedure can be used to save and restore a Netica network across sessions. In the first session:

    DefaultNeticaSession <- NeticaSession()
    startSession(DefaultNeticaSession)
    net <- CreateNetwork("myNet",DefaultNeticaSession)
    # Work on the network.
    WriteNetworks(net,"myNet.dne")
    q("yes")
  

The variables DefaultNeticaSession and net will be saved in .Rdata. Then in the next R session

    startSession(DefaultNeticaSession)
    net <- ReadNetworks(net,DefaultNeticaSession)
    net.nodes <- NetworkAllNodes(net)
  

This will read net from the place it was last saved. It will also create R objects for all of the nodes in net. This can now be access through net$nodes or the variable net.nodes.

Creating and Editing Networks

Operations with Bayesian networks generally proceed in two phases: Building network, and conducting inference. This section describes the most commonly used options for building networks. The following section describes the most commonly used options for inference.

First, the function CreateNetwork() is used to create an empty network. Multiple networks can be open within the RNetica environment, but each must have a unique name. Names must conform to Netica's IDname rules.

Nodes can be added to a network with the functions NewDiscreteNode() and NewContinuousNode(). Note that Netica makes an internal distinction between these two types of nodes and a node cannot be changed from one type to another. Nodes must all have a unique (within the network) name which must conform to the IDname rules.

Edges between nodes are created using the AddLink(parent,child) function. This forms a directed graph which must be acyclic (that is it must not be possible to follow a path along the direction of the arrows and return to the starting place). The function NodeParents(child) returns the current set of parents for the node child (nodes which have edges pointing towards child). NodeParents(child) may be set, which serves several purposes. First, it allows connections to be added and removed. Second, setting one of the parent locations to NULL produces a special Stub node, which serves as a placeholder for a later connection. Third, it allows one to reorder the nodes, which determines the order of the dimensions of the conditional probability table.

A completed Bayesian network has a conditional probability table (CPT) associated with each node. The CPT provides the conditional probability distributions of the node given the states of its parents in the graph. RNetica provides two functions for accessing and setting this CPT. The function NodeProbs() returns (or sets) the conditional probability table as a multi-dimensional array. However, using the array extractor “[...]” (Extract.NeticaNode) allows the conditional probability table to be manipulated as a data frame, where the first several columns provide the states of the parent variables, and the remaining columns the probabilities of the the node being in each of those states given the parent configurations. This latter approach has a number of features for working with large tables and tables with complex structure. The double square bracket extractor “[[...]]” (Extract.NeticaNode) words with logical IsNodeDeterministic nodes where parent configuration maps to exactly one state of the child. So rather than returning a probability distribution, they return a value table.

Finally, when the network is complete, the function WriteNetworks() can be used to save it to a file, which can either be later read into RNetica, or can be used with the Netica GUI or other applications that use the Netica API.

Inference

The basic purpose for building a Bayesian network is to rapidly calculate conditional probabilities. In Netica language, one enters findings (conditions) on the known or hypothesised variables and then calculates beliefs (conditional probabilities) on certain variables of interest.

Netica, like most Bayesian network software, uses two different graphical representations, one for model construction and one for inference. The acyclic directed graph is use for model construction (previous section). The function CompileNetwork() builds the second graphical representation: the junction tree. The function JunctionTreeReport() provides information about the compiled representation.

While compiling can take a long time (depending on the size and connectivity of the network), repeated compilations appear to be harmless. There is an UncompileNetwork() function, but performing any editing operation (adding or removing nodes or edges) will automatically return the network to an uncompiled state. Netica tries to preserve finding information. In particular the function AbsorbNodes() provides a mechanism for removing nodes from a network without changing the joint probability (including influence of findings) of the remaining nodes. (The network must be recompiled after a call to AbsorbNodes() though.)

The principle way to enter observed evidence is setting NodeFinding(node) <- value. The function NodeLikelihood() can be used to enter virtual evidence, however, some care must be taken as it alters the meanings of several of the other functions.

The conditional (given the entered findings and likelihoods) probability distribution can be queried at any time using the function NodeBeliefs(node). If the states of a node have been given numeric values using NodeLevels(node), then NodeExpectedValue(node) will calculate the expected numeric value (and the standard deviation). The function JointProbability(nodelist) calculates the joint distribution over a collection of nodes, and the function FindingsProbability(net) calculates the prior probability of all the findings entered into the network. The function MostProbableConfig(nodelist) finds the mode of the joint probability distribution (given the current findings and likelihood).

Note that in the default state, when findings are entered, the beliefs about all other nodes in the network are then updated. This can be time consuming in large networks. The function SetNetworkAutoUpdate() can be used to change this to a lazy updating mode, when the evidence from the findings are only propagated when required for a call to NodeBeliefs() or a similar function. The function WithoutAutoUpdate(net,expr) is useful for setting findings in a large number of nodes in net without the overhead of belief updating.

Node Sets

The function NodeSets() allows the modeller to attach labels to the nodes in the network. For the most part, Netica ignores these labels, except that it will colour nodes from various sets different colours (NetworkNodeSetColor()). Aside from a few internal labels used by Netica, these node sets are reserved for user programming.

RNetica provides some functions that make node sets incredibly convenient ways to describe the intended usage of the nodes. In particular, the function NetworkNodesInSet() returns a list of all nodes which are tagged as being in a particular node set. For example, suppose that the modeller has marked a number of nodes as being in the node set "ReportingVar". Then the following code would generate a report about the network:

    net.ReportingVars <- NetworkNodesInSet(net, "ReportingVar")
    lapply(net.ReportingVars, NodeBeliefs)
  

Error Handling

After a call to a C function in the Netica API, an additional function must be called to check for errors. It can return messages at different levels of severity. The reportErrors method of the NeticaSession object calls this function and bundles it into an object of class link{NeticaConditon}. The class of the output of reportErros is determined by the messages with the highest severity.

Netica Error Priority	R condition class
“XXX_ERR”	"NeticaCondition" "fatal" "error" "condition"
“ERROR_ERR”	"NeticaCondition" "error" " condition"
“WARNING_ERR”	"NeticaCondition" "warning" "condition"
“NOTICE_ERR”	"NeticaCondition" "message" "condition"
“REPORT_ERR”	"NeticaCondition" "message" "condition"
no messages	"NULL"

Note that errors origininating from Netica have the type “NeticaCondition” so that error class can be separately tracked by error handlers. The types “error”, “warning”, “message”, and “condition” are all subclasses of the base R class condition, and all NeticaCondition objects have a message and a call field. The default argument for call, sets the call field to be the function or method from which reportErrors or signalErrors was called. In addition, NeticaCondition objects have fields of type Fatal, Error, Warning, Notice and Report which are all character vectors giving the text of the messages returned from Netica.

The NeticaSession object also has a signalErrors method. This calls reportErrors, and then if the result is a NeticaCondition signals the error using the appropriate method: stop for (fatal) errors, warning for warnings, and signalCondition for other conditions. The NeticaBN and NeticaNode objects (as well as some other persistant objects) also have reportErrors and signalErrors methods, which delegate this function to the session. One of these methods is called after any RNetica function which calls an internal Netica C API call, so that these errors will be properly captured.

Warning

The current status of RNetica is that of a beta release. The code base is stable enough to do useful work, but more testing is still required. Users are advised to work in such a way that they can easily recover from problems.

In particular, because RNetica calls C code, there is a possibility that it will crash R. There is also a possibility that pointers embedded in NeticaBN and NeticaNode objects will become corrupted. If such problems occur, it is best to restart R and reload the networks.

Please send information about both serious and not-so-serious problems to the maintainer.

Legal Stuff

Netica and Norsys are registered trademarks of Norsys, LLC, used by permission.

Although Norsys is generally supportive of the RNetica project, it does not officially support RNetica, and all questions should be sent to the package maintainers.

Acknowledgements

We are grateful to support from the following projects for supporting the work in the development and maintenance of this package.

• Bill \& Melinda Gates Foundation grant "Games as Learning/Assessment: Stealth Assessment" (\#0PP1035331, Val Shute, PI)

• National Science Foundation grant "DIP: Game-based Assessment and Support of STEM-related Competencies" (\#1628937, Val Shute, PI).

• National Scient Foundation grant "Mathematical Learning via Architectual Design and Modeling Using E-Rebuild." (\#1720533, Fengfeng Ke, PI).

I would also like to thank Brent Borlange @ Norsys for answering questions related to the API as well as making improvements to fix issues raised during the construction of RNetica. Although Norsys does not officially support RNetica, their unoffical support has been quite valuable.

Author(s)

Russell Almond
Maintainer: Russell Almond <[email protected]>

References

The general Netica manual can be found at: http://www.norsys.com/WebHelp/NETICA.htm

The Netica API documentation can be found at http://norsys.com/onLineAPIManual/index.html.

Almond, R. G. & Mislevy, R. J. (1999) Graphical models and computerized adaptive testing. Applied Psychological Measurement, 23, 223–238.

Almond, R. G., Mislevy, R. J., Steinberg, L. S., Yan, D. & Williamson, D. M. (2015) Bayesian Networks in Educational Assessment. Springer.

Examples

###########################################################
## Network Construction:
sess <- NeticaSession()
startSession(sess)

abc <- CreateNetwork("ABC", session=sess)
A <- NewDiscreteNode(abc,"A",c("A1","A2","A3","A4"))
B <- NewDiscreteNode(abc,"B",c("B1","B2","B3"))
C <- NewDiscreteNode(abc,"C",c("C1","C2"))

AddLink(A,B)
NodeParents(C) <- list(A,B)

NodeProbs(A)<-c(.1,.2,.3,.4)
NodeProbs(B) <- normalize(matrix(1:12,4,3))
NodeProbs(C) <- normalize(array(1:24,c(4,3,2)))
abcFile <- tempfile("peanut",fileext=".dne")
WriteNetworks(abc,abcFile)

DeleteNetwork(abc)

###################################################################
##  Inference using the EM-SM algorithm (Almond & Mislevy, 1999).  
## System/Student model
EMSMSystem <- ReadNetworks(system.file("sampleNets","System.dne",
                                       package="RNetica"),
                           session=sess)


## Evidence model for Task 1a
EMTask1a <- ReadNetworks(system.file("sampleNets","EMTask1a.dne",
                                     package="RNetica"),
                         session=sess)

## Evidence model for Task 2a
EMTask2a <- ReadNetworks(system.file("sampleNets","EMTask2a.dne",
                                     package="RNetica"),
                         session=sess)

## Task 1a has a footprint of Skill1 and Skill2 (those are the
## referenced student model nodes.  So we want joint the footprint into
## a single clique.
MakeCliqueNode(NetworkFindNode(EMSMSystem, NetworkFootprint(EMTask1a)))
## The footprint for Task2 a is already a clique, so no need to do
## anything. 

## Make a copy for student 1
student1 <- CopyNetworks(EMSMSystem,"student1")
## Monitor nodes for proficiency
student1.prof <- NetworkNodesInSet(student1,"Proficiency")

student1.t1a <- AdjoinNetwork(student1,EMTask1a)
## We are done with the original EMTask1a now
DeleteNetwork(EMTask1a)

## Now add findings
CompileNetwork(student1)
NodeFinding(student1.t1a$Obs1a1) <- "Right"
NodeFinding(student1.t1a$Obs1a2) <- "Right"

student1.probt1a <- JointProbability(student1.prof)

## Done with the observables, absorb them
AbsorbNodes(student1.t1a)
CompileNetwork(student1)
student1.probt1ax <- JointProbability(student1.prof)

## Now Task 2
student1.t2a <- AdjoinNetwork(student1,EMTask2a,"t2a")
DeleteNetwork(EMTask2a)

## Add findings
CompileNetwork(student1)
NodeFinding(student1.t2a$Obs2a) <- "Half"

AbsorbNodes(student1.t2a)
CompileNetwork(student1)
student1.probt1a2ax <- JointProbability(student1.prof)

DeleteNetwork(list(student1, EMSMSystem))
stopSession(sess)

---

Delete a Netica nodes in a way that maintains the connectivity.

Description

This function deletes NeticaNode connecting the parents of the deleted node to its children. If multiple nodes are passed as the argument, then all of the nodes are absorbed. The joint probability distribution over the remaining nodes should be the same as the marginal probability distribution over the remaining nodes before the nodes were deleted.

Usage

AbsorbNodes(nodes)

Arguments

nodes

A NeticaNode or list of NeticaNodes to be deleted.

Details

This function provides a way of removing a node without affecting the connectivity, or the joint probability of the remaining nodes. In particular, all of the relationship tested by is.NodeRelated() among the remaining nodes should remain true (or false) when we are done.

Value

Returns NULL.

Errors

There is a bug in version 5.04 (and 5.10) of the Netica API where AbsorbNodes can crash if some nodes have visual information and some do not. For the moment, it is recommended that you call ReadNetworks with loadVisual=FALSE to work around this problem.

Author(s)

Russell Almond

References

http://norsys.com/onLineAPIManual/index.html: AbsorbNodes_bn()

See Also

NeticaNode, AddLink(), NodeChildren(), NodeParents(), ReverseLink(), is.NodeRelated()

Examples

sess <- NeticaSession()
startSession(sess)
anet <- CreateNetwork("Absorbent",sess)

xnodes <- NewDiscreteNode(anet,paste("X",1:5,sep="_"))
AddLink(xnodes[[1]],xnodes[[2]])
AddLink(xnodes[[2]],xnodes[[3]])
AddLink(xnodes[[3]],xnodes[[4]])
AddLink(xnodes[[3]],xnodes[[5]])

stopifnot(
 all(match(xnodes[4:5],NodeChildren(xnodes[[3]]),nomatch=0)>0),
 is.NodeRelated(xnodes[[2]],xnodes[[3]],"parent"),
 is.NodeRelated(xnodes[[2]],xnodes[[1]],"child")
)

## These are leaf nodes, shouldn't change topology, except locally. 
if (NeticaVersion(sess)$number >600) {
AbsorbNodes(xnodes[4:5])
stopifnot(
  ## Nodes 4 and 5 are now deleted
  all(!is.active(xnodes[4:5])),
  all(anet$listNodes() == c("X_1","X_2","X_3")),
  length(NodeChildren(xnodes[[3]]))==0,
  is.NodeRelated(xnodes[[2]],xnodes[[3]],"parent"),
  is.NodeRelated(xnodes[[2]],xnodes[[1]],"child")
)

## This should connect X1->X3
AbsorbNodes(xnodes[[2]])
stopifnot(
  ## Node 2 is now deleted
  !is.active(xnodes[[2]]),
  length(NodeChildren(xnodes[[3]]))==0,
  is.NodeRelated(xnodes[[1]],xnodes[[3]],"parent"),
  is.NodeRelated(xnodes[[3]],xnodes[[1]],"child")
)
}
DeleteNetwork(anet)
stopSession(sess)

---

Adds or removes a link between two nodes in a Netica network.

Description

Add link adds an edge from Parent to Child. Delete Link removes that edge. This states that the distribution of child will be specified conditional on the value of parent. Consequently, adding or removing edges with affect the conditional probability tables associated with the Child node (see NodeProbs().)

Usage

AddLink(parent, child)
DeleteLink(parent, child)

Arguments

parent	A NeticaNode representing an independent variable to be added to the conditioning side of the relationship. The nodes parent and child must both be in the same network.
child	A NeticaNode representing dependent variable to be added to the conditioning side of the relationship.

Details

After adding a link parent --> child, it may be the case that parent is in NodeParents(child) and child is a member of NodeChildren(parent). If child already has other parents, then the new parent will be added to the end of the list. The order of the parents can be set by setting NodeParents(child).

In general, the Bayesian network must always be an acyclic directed graph. Therefore, if parent is a descendant of child (that is if is.NodeRelated(child), "descendant", child is TRUE), then Netica will generate an error.

The function DeleteLink() removes the relationship, and the parent and child nodes should no longer be in each other parent and child lists. The parent list of the child node is shortened (a stub node for later reconnection is not created as when NodeParents(child)[i] <- list(NULL)).

Value

The function AddLinK invisibly returns the index of the new parent in the parent list.

The function DeleteLink invisibly returns the child node.

Note

The Netica API specifies the first argument to DeleteLink_bn() as an index into the parent list. RNetica maps from the node to the index.

Author(s)

Russell Almond

References

http://norsys.com/onLineAPIManual/index.html: AddLink_bn(), DeleteLink_bn()

See Also

NeticaNode, NodeParents(), NodeChildren(), is.NodeRelated()

Examples

sess <- NeticaSession()
startSession(sess)

abnet <- CreateNetwork("AABB", session=sess)
A <- NewDiscreteNode(abnet, "A")
B <- NewDiscreteNode(abnet, "B")

AddLink(A,B)

stopifnot(
  is.element(list(A),NodeParents(B)),
  is.element(list(B),NodeChildren(A))
)

DeleteLink(A,B)

stopifnot(
  !is.element(list(A),NodeParents(B)),
  !is.element(list(B),NodeChildren(A))
)

DeleteNetwork(abnet)
stopSession(sess)

---

Links an evidence model network to a system model network.

Description

This function assumes that the two arguments are networks that were designed to be connected to one another. It copies the nodes from em into sm and then tries to resolve any stub links in the copied nodes by connecting them to nodes in sm.

Usage

AdjoinNetwork(sm, em, setname = character())

Arguments

sm	An active NeticaBN which contains the system state variables.
em	An active NeticaBN which contains variables that provide evidence about the system state.
setname	An optional character vector containing names of node sets (see NodeSets()). If supplied, all of the newly created nodes are added to the node sets. Note that all node set names must conform to the IDname rules.

Details

This follows the System Model–Evidence Model (or Hub-and-spoke) protocol laid out in Almond et al (1999) and Almond and Mislevy (1999). The idea is that the network sm is a complete network that encodes beliefs about the current status of a system. In particular, it often encodes the state of knowledge about a student and is then called a student model.

The second network em is an incomplete network: a fragment of a network, some of whose nodes could be stub nodes referring to nodes in the sm (see NodeInputNames() and NodeKind()). The idea is that the evidence model provides a set of observable values associated with some diagnostic procedure, in particular, a task on an assessment.

The function AdjoinNetwork(sm,em) copies all of the nodes from em to sm, modifying sm in the process (copy it first using CopyNetworks(sm) if this is not the intention). It then the parents of each node, emnode, in em looking for stub nodes (cases where NodeParents(emnode)[j] has been set to NULL for some parent. AdjoinNetworks(sm,em) then tries to find a matching parent by searching for a system model node, smnode named NodeInputNames(emnode)[j]. If it finds one, it sets NodeParents(emnode)[j] <- smnode; if not, it issues a warning.

The function AdjoinNetwork(sm,em) also copies node set information from the nodes in em to their copies in sm. The value of setname is concatenated with the current node sets of the nodes in em. This provides a handy way of identifying the evidence model from which the nodes came.

After findings are entered on the nodes in the evidence model, the can be eliminated using AbsorbNodes().

Value

A list containing the newly copied nodes (the instances of the em nodes now in sm).

Author(s)

Russell Almond

References

Almond, R. G. & Mislevy, R. J. (1999) Graphical models and computerized adaptive testing. Applied Psychological Measurement, 23, 223–238.

Almond, R., Herskovits, E., Mislevy, R. J., & Steinberg, L. S. (1999). Transfer of information between system and evidence models. In Artificial Intelligence and Statistics 99, Proceedings (pp. 181–186). Morgan-Kaufman

See Also

NeticaNode, AbsorbNodes(), JointProbability(), NodeSets(), CopyNodes(),NetworkFootprint()

Examples

sess <- NeticaSession()
startSession(sess)

## System/Student model
EMSMSystem <- ReadNetworks(system.file("sampleNets","System.dne",
                                       package="RNetica"),
                                       session=sess)


## Evidence model for Task 1a
EMTask1a <- ReadNetworks(system.file("sampleNets","EMTask1a.dne",
                                      package="RNetica"),
                                      session=sess)

## Evidence model for Task 2a
EMTask2a <- ReadNetworks(system.file("sampleNets","EMTask2a.dne",
                                      package="RNetica"),
                                      session=sess)

## Evidence model for Task 2b
EMTask2b <- ReadNetworks(system.file("sampleNets","EMTask2b.dne",
                                      package="RNetica"),
                                      session=sess)

## Task 1a has a footprint of Skill1 and Skill2 (those are the
## referenced student model nodes.  So we want joint the footprint into
## a single clique.
MakeCliqueNode(NetworkFindNode(EMSMSystem, NetworkFootprint(EMTask1a)))
## The footprint for Task2 a is already a clique, so no need to do
## anything. 

## Make a copy for student 1
student1 <- CopyNetworks(EMSMSystem,"student1")
## Monitor nodes for proficiency
student1.prof <- NetworkNodesInSet(student1,"Proficiency")

student1.t1a <- AdjoinNetwork(student1,EMTask1a)
stopifnot(setequal(student1$listNodes(),
 c("CliqueNode1", "Obs1a1", "Obs1a2", "Skill1", "Skill2", "Skill3")))

## We are done with the original EMTask1a now
DeleteNetwork(EMTask1a)

## Now add findings
CompileNetwork(student1)
NodeFinding(student1.t1a$Obs1a1) <- "Right"
NodeFinding(student1.t1a$Obs1a2) <- "Right"

student1.probt1a <- JointProbability(student1.prof)
## Done with the observables, absorb them
if (NeticaVersion(sess)$number >600) {
AbsorbNodes(student1.t1a)
stopifnot(setequal(student1$listNodes(),
 c("CliqueNode1", "Skill1", "Skill2", "Skill3")))
}

CompileNetwork(student1)
student1.probt1ax <- JointProbability(student1.prof)

## This should be the same
stopifnot(
  sum(abs(student1.probt1a-student1.probt1ax)) <.0001
)

## Now Task 2
student1.t2a <- AdjoinNetwork(student1,EMTask2a,as.IDname("t2a"))
if (NeticaVersion(sess)$number >600) {
stopifnot(
  setequal(names(student1.t2a),names(NetworkNodesInSet(student1,"t2a")))
)
stopifnot(setequal(student1$listNodes(),
 c("CliqueNode1", "Obs2a", "Skill1", "Skill2", "Skill3")))
}
DeleteNetwork(EMTask2a)

## Add findings
CompileNetwork(student1)
NodeFinding(student1.t2a$Obs2a) <- "Half"

student1.probt1a2a <- JointProbability(student1.prof)

if (NeticaVersion(sess)$number >600) {
AbsorbNodes(student1.t2a)
stopifnot(setequal(student1$listNodes(),
 c("CliqueNode1", "Skill1", "Skill2", "Skill3")))
}
CompileNetwork(student1)
student1.probt1a2ax <- JointProbability(student1.prof)

## This should be the same
stopifnot(
  sum(abs(student1.probt1a2a-student1.probt1a2ax)) <.0001
)

## Adjoining networks twice should result in copies with incremented
##   numbers.
AdjoinNetwork(student1,EMTask2b)
AdjoinNetwork(student1,EMTask2b)
if (NeticaVersion(sess)$number >600) {
stopifnot(setequal(student1$listNodes(),
 c("CliqueNode1", "Obs2b", "Obs2b1", "Skill1", "Skill2", "Skill3")))
}
DeleteNetwork(student1)
DeleteNetwork(EMTask2b)
DeleteNetwork(EMSMSystem)
stopSession(sess)

---

Calculates the state of a node based on logical functions or formulae

Description

The expression CalcNodeState(node) will return the state of node if it is known deterministically, and NA if the exact value is not known. The expression CalcNodeValue(node) will return the numeric value of the node (e.g., the value set with NodeLevels(node).

Usage

CalcNodeState(node)
CalcNodeValue(node)

Arguments

node	An active NeticaNode object that references the node.

Details

According to the Netica manual, the way that the value of node could be known absolutely is if it was set directly a call to NodeFinding(node) or NodeValue(node), or if the value can be calculated exactly through logical conditional probability tables (i.e., ones with just 0's and 1's) or formula (see NodeEquation().

The expression CalcNodeState(node) is appropriate when node is discrete, or has been discretized through a call to NodeLevels(node). Otherwise it will generate an error.

The expression CalcNodeValue(node) is appropriate when node is continuous, or the states have been assigned numeric values through a call to NodeLevels(node). Otherwise it will generate an error.

Value

The expression CalcNodeState(node) will return a character scalar giving the name of the current state of node if it can be determined, otherwise it will return NA.

The expression CalcNodeValue(node) will return a numeric scalar giving the name of the current value of node if it can be determined, otherwise it will return NA.

Warning

This function is not behaving at all like what I expected. In particular, it is returning NA in many cases where I expect it to produce a value. I've queried Norsys about this, but use with caution until I get a clarification.

Author(s)

Russell Almond

References

http://norsys.com/onLineAPIManual/index.html: CalcNodeState_bn(), CalcNodeValue_bn()

See Also

NodeFinding(), NodeLevels(), NodeValue(), IsNodeDeterministic(), NodeEquation(),is.continuous(), NodeExpectedValue()

Examples

sess <- NeticaSession()
startSession(sess)

lights <- CreateNetwork("lights", session=sess)
switchs <- NewDiscreteNode(lights,paste("Switch",1:2,sep=""),c("Up","Down"))
bulb <- NewDiscreteNode(lights,"Bulb",c("On","Off"))

## Set up a two-way switch (Xor) network
AddLink(switchs[[1]],bulb)
AddLink(switchs[[2]],bulb)
## This sets up a logical table, so that the light is on iff
## both switches are in the same orientation.
bulb[] <-"Off"
bulb[Switch1="Up",Switch2="Up"]<-"On"
bulb[Switch1="Down",Switch2="Down"]<-"On"
switchs[[1]][] <- .5
switchs[[2]][] <- .5


CompileNetwork(lights)

## Bulb is a deterministic node.
stopifnot(IsNodeDeterministic(bulb))

## value of node is unknown, returns NA
stopifnot(is.na(CalcNodeState(bulb)))

NodeFinding(switchs[[1]]) <- "Up"
NodeFinding(switchs[[2]]) <- "Up"

stopifnot(CalcNodeState(switchs[[1]])=="Up")

stopifnot(CalcNodeState(bulb)=="On")

NodeLevels(bulb) <-c(1,0)
NodeLevels(switchs[[1]]) <-c(1,0)
NodeLevels(switchs[[2]]) <-c(1,0)

## I expect both of these to return 1, but they return NA
CalcNodeValue(bulb)
CalcNodeValue(switchs[[1]])

DeleteNetwork(lights)

stopSession(sess)

---

Gets or sets special characters for case files.

Description

The function CaseFileDelimiter sets the field delimiter used when writing case files. The function CaseFileMissingCode sets the character code used for missing values in case files. If called with a null argument, then the current value is returned.

Usage

CaseFileDelimiter(newdelimiter = NULL, session=getDefaultSession())
CaseFileMissingCode(newcode = NULL, session=getDefaultSession())

Arguments

newdelimiter	A character scalar containing the new delimiter. It must be either a comma, a space, or a tab.
session	An object of type NeticaSession which defines the reference to the Netica workspace.
newcode	The character to be used as a delimiter. It must be either an asterisk ("*"), a question mark ("?"), a space, (" ") or the empty string ("").

Details

Case files are essentially a comma separated value files, although tab and space are allowed as alternative delimiters. The space and empty string are only allowed as missing value codes when the delimiter is a comma.

The value of the delimiter is global, and applies to all case files written from this point on.

When the argument is null (the default) the current value is returned without changing it.

Value

The value of the delimiter or missing code before the function call as a string.

Note

The default R missing code "NA" does not work with Netica.

Author(s)

Russell G. Almond

References

http://norsys.com/onLineAPIManual/index.html: SetCaseFileDelimChar_ns(), SetMissingDataChar_ns()

See Also

WriteFindings, WriteFindings, read.CaseFile, CaseStream

Examples

sess <- NeticaSession()
startSession(sess)

defaultDelim <- CaseFileDelimiter(session=sess) # Get default
d1 <- CaseFileDelimiter("\t", session=sess)
d2 <- CaseFileDelimiter(" ", session=sess)
d3 <- CaseFileDelimiter(",", session=sess)

defaultMiss <- CaseFileMissingCode(session=sess) # Get default
m1 <- CaseFileMissingCode("*", session=sess)
m2 <- CaseFileMissingCode("?", session=sess)
m3 <- CaseFileMissingCode(" ", session=sess)
m4 <- CaseFileMissingCode("", session=sess)
## Not run: 
 ## This should throw an error.
 CaseFileDelimiter(" ", session=sess)

## End(Not run)

m5 <- CaseFileMissingCode("?", session=sess)

d4<- CaseFileDelimiter(" ", session=sess)
## Not run: 
  ## This should throw an error
  CaseFileMissingCode(" ", session=sess)

## End(Not run)
## But this is okay
CaseFileMissingCode("*", session=sess)

stopifnot(d1==defaultDelim, d2=="\t", d3==" ", d4==",")
stopifnot(m1==defaultMiss, m2=="*", m3=="?", m4==" ", m5=="")

## restore defaults
CaseFileDelimiter(defaultDelim, session=sess)
CaseFileMissingCode(defaultMiss, session=sess)

stopSession(sess)

---

A stream of cases for reading/writing Netica findings to a file

Description

This is the constructor for FileCaseStream objects which provide a wrapper around a Netica stream which is used to read/write cases. In this subclass, the case stream is associated with a Netica case file (‘.cas’ extension). The function ReadFindings reads the findings from the stream and the function WriteFindings writes them out.

Usage

CaseFileStream(pathname, session=getDefaultSession())
is.CaseFileStream(x)
getCaseStreamPath(stream)

Arguments

pathname	A character scalar giving a path to the case file. Netica expects case files to end with the extension ".cas"
session	An object of type NeticaSession which defines the reference to the Netica workspace.
stream	A CaseFileStream object.
x	A object to be printed or whose type is to be determined.

Details

A FileCaseStream object is a subclass of the CaseStream object, which is an R wrapper around a Netica stream object, in this case one that reads or writes to a case file. Case files are tab (or comma, see CaseFileDelimiter) separated value files where columns represent variables and rows represent cases. Although the function WriteFindings always appends a new case to the end of a file (and hence does not need to keep the stream object open between calls), the function ReadFindings will read (by default) sequentially from the cases in the stream, and hence the stream needs to be kept open between calls.

The function CaseFileStream will open a stream in Netica and create a new FileCaseStream if necessary. The argument pathname should be the pathname of the case file in the file system. This file should be a file previously written by WriteFindings or be in the same format. The delimiter used should be the one given by CaseFileDelimiter, and the code used for missing values should be the value of CaseFileMissingCode.

The function CloseCaseStream closes an open case stream (and is harmless if the stream is already closed). Although RNetica tries to close open case streams when they are garbage collected, users should not count on this behavior and should close them manually. Also be aware that all case streams are automatically closed when R is closed or RNetica is unloaded. The function isCaseStreamOpen tests to see if the stream is open or closed, and the function OpenCaseStream reopens a previously closed case stream.

The functions getCaseStreamPath returns the path on which the FileCaseStream is focused.

Value

The function CaseFileStream returns a new, open FileCaseStream object.

The functions is.CaseFileStream returns a logical value indicating whether or not the argument is a CaseFileStream.

The function getCaseStreamPath returns a string giving the path of the file associated with stream, or NULL if the argument is not a CaseFileStream.

Note

Internally, a weak reference system is used to keep a list of Netica stream objects which need to be closed when RNetica is unloaded. Stream objects should also be forced closed when garbage collected. The weak reference system is somewhat experimental, so well designed code should manually close the streams when the program is through with it.

Stream objects are fragile, and will not survive saving and restoring an R session. However, the object retains information about itself, so that calling OpenCaseStream on the saved object, should reopen the stream. Note that any position information will be lost.

Author(s)

Russell Almond

References

http://norsys.com/onLineAPIManual/index.html: NewFileStream_ns(), http://homepage.stat.uiowa.edu/~luke/R/references/weakfinex.html

See Also

See FileCaseStream for properties of file case stream objects and CaseStream for general properties of Netica streams.

CaseFileDelimiter, CaseFileMissingCode, CaseMemoryStream, WriteFindings, ReadFindings,

Examples

sess <- NeticaSession()
startSession(sess)

abc <- CreateNetwork("ABC", sess)
A <- NewDiscreteNode(abc,"A",c("A1","A2","A3","A4"))
B <- NewDiscreteNode(abc,"B",c("B1","B2","B3"))
C <- NewDiscreteNode(abc,"C",c("C1","C2"))

AddLink(A,B)
AddLink(A,C)
AddLink(B,C)

## Outputfilename
casefile <- tempfile("testcase",fileext=".cas")

filestream <- CaseFileStream(casefile, session=sess)
stopifnot(is.CaseFileStream(filestream),
          isCaseStreamOpen(filestream))

## Case 1
NodeFinding(A) <- "A1"
NodeFinding(B) <- "B1"
NodeFinding(C) <- "C1"
filestream <- WriteFindings(list(A,B,C),filestream,1001,1.0)
stopifnot(getCaseStreamLastId(filestream)==1001,
          abs(getCaseStreamLastFreq(filestream)-1.0) <.0001)

## Close it
filestream <- CloseCaseStream(filestream)
stopifnot (is.CaseFileStream(filestream),
           !isCaseStreamOpen(filestream))

## Reopen it
filestream <- OpenCaseStream(filestream)
stopifnot (is.CaseFileStream(filestream),
           isCaseStreamOpen(filestream))

##Case 1
RetractNetFindings(abc)
filestream <- ReadFindings(list(A,B,C),filestream,"FIRST")
stopifnot(getCaseStreamLastId(filestream)==1001,
          abs(getCaseStreamLastFreq(filestream)-1.0) <.0001)

##Clean Up
CloseCaseStream(filestream)
DeleteNetwork(abc)
stopSession(sess)

---

A stream of cases for reading/writing Netica from memory

Description

This object is subclass of CaseStream so it is a wrapper around a Netica stream which is used to read/write cases. In this subclass, the case stream is associated with a memory buffer that corresponds to an R data.frame object. The function MemoryStreamContents accesses the contents as a data frame.

Usage

CaseMemoryStream(data.frame, label=deparse(substitute(data.frame)), session=getDefaultSession())
is.MemoryCaseStream(x)
getCaseStreamDataFrameName(stream)

Arguments

data.frame	A data frame in which columns correspond to Netica nodes, and rows correspond to cases. See details.
label	A name for the stream object.
session	An object of type NeticaSession which defines the reference to the Netica workspace.
stream	A CaseStream object.
x	A object whose type is to be determined.

Details

A Netica case file has a format that very much resembles the output of write.table. The first row is a header row, which contains the names of the variables, the second and subsequent rows contain a set of findings: an assignment of values to the nodes indicated in the columns. There are no row numbers, and the separator and missing value codes are the values of CaseFileDelimiter(), and CaseFileMissingCode() respectively.

In addition to columns representing variables, two special columns are allowed. The column named “IDnum”, if present should contain integers which correspond to ID numbers for the cases (this correspond to the id argument of WriteFindings). The column named “NumCases” should contain number values and this allows rows to be differentially weighted (this correspond to the freq argument of WriteFindings).

A simple way to convert a data frame into a set of cases for use with various Netica functions that use cases would be to write the data frame to a file of the proper format, and then create a CaseFileStream on the just written file. The MemoryCaseStream shortcuts that process by writing the data frame to a memory buffer and then creating a stream around the memory buffer. Like the CaseFileStream, the MemoryCaseStream is a subclass of CaseStream and follows the same conventions.

The function MemoryCaseStream opens a new memory stream using data.frame as the source. If data.frame is NULL a new memory stream for writing is created. The function CloseCaseStream closes an open case stream (and is harmless if the stream is already closed. Although RNetica tries to close open case streams when they are garbage collected, users should not count on this behavior and should close them manually. Also be aware that all case streams are automatically closed when R is closes or RNetica is unloaded. The function isCaseStreamOpen tests to see if the stream is open or closed. The function OpenCaseStream if called on a closed MemoryCaseStream will reopen the stream in Netica using the current value of MemoryStreamContents as the source. (If called on an open stream it will do nothing but issue a warning).

The function getCaseStreamDataFrameName provides the value of label when the stream was created.

Value

The function OpenMemoryCaseStream returns a new, open CaseFileStream object.

The functions is.MemoryCaseStream returns a logical value indicating whether or not the argument is a CaseFileStream.

The function getCaseStreamDataFrameName returns the value of label used when the stream was created, usually this is the name of the data.frame argument.

Netica Bugs

In version 5.04 of the Netica API, there is a problem with using Memory Streams that seems to affect the functions LearnCases and LearnCPTs. Until this problem is fixed, most uses of Memory Streams will require file streams instead. Write the case file using write.CaseFile, and then create a file stream using CaseFileStream.

Note

In version 0.5 of RNetica, this class was renamed. It is now called MemoryCaseStream and the constructor is called CaseMemoryStream (while previously the class and the filename had the same name). This matches the usage of FileCaseStream and its constructor CaseFileStream.

MemoryCaseStreams are most useful for small to medium size data frames. Larger data frames are probably better handled through case files.

Internally, a weak reference system is used to keep a list of Netica stream objects which need to be closed when RNetica is unloaded. Stream objects should also be forced closed when garbage collected. The weak reference system is somewhat experimental, so well designed code should manually close the streams when the program is through with it.

Stream objects are fragile, and will not survive saving and restoring an R session. However, the object retains information about itself, so that calling OpenCaseStream on the saved object, should reopen the stream. Note that any position information will be lost.

Author(s)

Russell Almond

References

http://norsys.com/onLineAPIManual/index.html: NewMemoryStream_ns(), http://homepage.stat.uiowa.edu/~luke/R/references/weakfinex.html

See Also

CaseFileDelimiter, CaseFileMissingCode, WriteFindings, ReadFindings, MemoryStreamContents,CaseStream

Examples

sess <- NeticaSession()
startSession(sess)

abc <- CreateNetwork("ABC", session=sess)
A <- NewDiscreteNode(abc,"A",c("A1","A2","A3","A4"))
B <- NewDiscreteNode(abc,"B",c("B1","B2","B3"))
C <- NewDiscreteNode(abc,"C",c("C1","C2"))

AddLink(A,B)
AddLink(A,C)
AddLink(B,C)

## This is the file written in CaseFileStream help.
casefile <- system.file("testData","abctestcases.cas", package="RNetica")
CaseFileDelimiter("\t", session=sess)
CaseFileMissingCode("*", session=sess)
cases <- read.CaseFile(casefile, session=sess)

memstream <- CaseMemoryStream(cases, session=sess)


##Case 1
memstream <- ReadFindings(list(A,B,C),memstream,"FIRST")
stopifnot(NodeFinding(A) == "A1",
          NodeFinding(B) == "B1",
          NodeFinding(C) == "C1",
          getCaseStreamLastId(memstream)==1001,
          abs(getCaseStreamLastFreq(memstream)-1.0) <.0001)

##Case 2
memstream <- ReadFindings(list(A,B,C),memstream,"NEXT")
stopifnot(NodeFinding(A) == "A2",
          NodeFinding(B) == "B2",
          NodeFinding(C) == "C2",
          getCaseStreamLastId(memstream)==1002,
          abs(getCaseStreamLastFreq(memstream)-2.0) <.0001)

##Case 3
memstream <- ReadFindings(list(A,B,C),memstream,"NEXT")
stopifnot(NodeFinding(A) == "A3",
          NodeFinding(B) == "B3",
          NodeFinding(C) == "@NO FINDING",
          getCaseStreamLastId(memstream)==1003,
          abs(getCaseStreamLastFreq(memstream)-1.0) <.0001)

## EOF
memstream <- ReadFindings(list(A,B,C),memstream,"NEXT")
stopifnot (is.na(getCaseStreamPos(memstream)))


##Clean Up
CloseCaseStream(memstream)
DeleteNetwork(abc)
stopSession(sess)

---

Class "CaseStream"

Description

This object is a wrapper around a Netica stream which is used to read/write cases—sets of findings entered into a Netica network. There are two subclasses: FileCaseStream and MemoryCaseStream. The function ReadFindings reads the findings from the stream and the function WriteFindings writes them out.

Details

A CaseStream object is an R wrapper around a Netica stream object. There are two subclasses: FileCaseStream objects are streams focused on a case file, and MemoryCaseStream objects are streams focused on a hunk of memory corresponding to an R data frame object.

Although the function WriteFindings always appends a new case to the end of a file (and hence does not need to keep the stream object open between calls), the function ReadFindings will read (by default) sequentially from the cases in the stream, and hence the stream needs to be kept open between calls.

The functions CaseFileStream and CaseMemoryStream create new streams and open them. The function OpenCaseStream will reopen a previously closed stream, and will issue a warning if the stream is already open. The function CloseCaseStream closes an open case stream (and is harmless if the stream is already closed). Although RNetica tries to close open case streams when they are garbage collected, users should not count on this behavior and should close them manually. Also be aware that all case streams are automatically closed when R is closes or RNetica is unloaded. The function isCaseStreamOpen tests to see if the stream is open or closed. The function WithOpenCaseStream executes an arbitrary R expression in a context where the stream is open, and then closed afterwards.

Netica internally keeps track of the current position of the stream when it is read or written. The functions getCaseStreamPos, getCaseStreamLastId and getCaseStreamLastFreq get information about the position in the file, the user generated id number and the frequency/weight assigned to the case at the time the stream was last read or written. In particular, the function ReadFindings returns a CaseStream object, which should be queried to find the ID and Frequencies read from the stream. When ReadFindings reaches the end of the stream, the value of getCaseStreamPos(stream) will be NA.

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.

Fields

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

Name:

Object of class character an identifier for the case stream, derived from the filename for FileCaseStream objects, and from the name of the R object for MemoryCaseStream

Session:

Object of class NeticaSession:: a back pointer to the NeticaSession object in which the stream was created.

Netica_Case_Stream:

Object of class externalptr a link to the stream in internal Netica memory.

Case_Stream_Position:

Object of class integer the number of the last read/writen record. This is NA if the end of the file has been reached.

Case_Stream_Lastid:

Object of class integer the ID number of the last read/written record.

Case_Stream_Lastfreq:

Object of class numeric giving the frequence of the last read/written record. This is used as a weight in learning applications.

Methods

show():

Provides a printed record.

close():

Closes the stream. Equivalent to CloseCaseStream(stream).

isOpen():

Checks to see if the stream is currently open. Equivalent to isCaseStreamOpen(stream).

isActive():

Equivalent to isOpen(), name is symmetric with other Netica reference objects.

clearErrors(severity):

Calls clearErrors on the Session object.

reportErrors(maxreport, clear, call):

Calls reportErrors on the Session object. Returns an object of class NeticaCondition if there was a message, or NULL if not.

signalErrors(maxreport, clear, call):

Calls signalErrors on the Session object. If there was a problem, the appropriate condition is signaled, see NeticaCondition.

initialize(Name, Session, ...):

Internal initializer. User code should not call.

Note

The functions ReadNetworks and WriteNetworks also use Netica streams internally. However, as it is almost certainly a mistake to keep the stream open after the network has been read or written, no NeticaCaseStream object is created.

Internally, a weak reference system is used to keep a list of Netica stream objects which need to be closed when RNetica is unloaded. Stream objects should also be forced closed when garbage collected. The weak reference system is somewhat experimental, so well designed code should manually close the streams when the program is through with them.

Stream objects are fragile, and will not survive saving and restoring an R session. However, the object retains information about itself, so that calling OpenCaseStream on the saved object, should reopen the stream. Note that any position information will be lost.

Author(s)

Russell Almond

References

http://norsys.com/onLineAPIManual/index.html: NewFileStream_ns(),NewMemoryStream_ns(), DeleteStream_ns() http://homepage.stat.uiowa.edu/~luke/R/references/weakfinex.html

See Also

See FileCaseStream and MemoryCaseStream for specific details about the two subtypes. CaseMemoryStream and CaseFileStream are the two constructors.

OpenCaseStream, CaseFileDelimiter, CaseFileMissingCode, WriteFindings, ReadFindings, WithOpenCaseStream

Examples

sess <- NeticaSession()
startSession(sess)

abc <- CreateNetwork("ABC",sess)
A <- NewDiscreteNode(abc,"A",c("A1","A2","A3","A4"))
B <- NewDiscreteNode(abc,"B",c("B1","B2","B3"))
C <- NewDiscreteNode(abc,"C",c("C1","C2"))

AddLink(A,B)
AddLink(A,C)
AddLink(B,C)

## Outputfilename
casefile <- tempfile("testcase",fileext=".cas")

filestream <- CaseFileStream(casefile,sess)
stopifnot(is.NeticaCaseStream(filestream),
          isCaseStreamOpen(filestream))

## Case 1
NodeFinding(A) <- "A1"
NodeFinding(B) <- "B1"
NodeFinding(C) <- "C1"
filestream <- WriteFindings(list(A,B,C),filestream,1001,1.0)
stopifnot(getCaseStreamLastId(filestream)==1001,
          abs(getCaseStreamLastFreq(filestream)-1.0) <.0001)
pos1 <- getCaseStreamPos(filestream)
RetractNetFindings(abc)

## Case 2
NodeFinding(A) <- "A2"
NodeFinding(B) <- "B2"
NodeFinding(C) <- "C2"
## Double weight this case
filestream <- WriteFindings(list(A,B,C),filestream,1002,2.0)
pos2 <- getCaseStreamPos(filestream)
stopifnot(pos2>pos1,getCaseStreamLastId(filestream)==1002,
          abs(getCaseStreamLastFreq(filestream)-2.0) <.0001)
RetractNetFindings(abc)

## Case 3
NodeFinding(A) <- "A3"
NodeFinding(B) <- "B3"
## C will be missing
filestream <- WriteFindings(list(A,B,C),filestream,1003,1.0)
stopifnot(getCaseStreamLastId(filestream)==1003,
          abs(getCaseStreamLastFreq(filestream)-1.0) <.0001)
RetractNetFindings(abc)

## Close it
filestream <- CloseCaseStream(filestream)
stopifnot (is.NeticaCaseStream(filestream),
           !isCaseStreamOpen(filestream))

## Reopen it
filestream <- OpenCaseStream(filestream)
stopifnot (is.NeticaCaseStream(filestream),
           isCaseStreamOpen(filestream))

##Case 1
RetractNetFindings(abc)
filestream <- ReadFindings(list(A,B,C),filestream,"FIRST")
pos1a <- getCaseStreamPos(filestream)
stopifnot(pos1a==pos1,
          getCaseStreamLastId(filestream)==1001,
          abs(getCaseStreamLastFreq(filestream)-1.0) <.0001)

##Case 2
RetractNetFindings(abc)
filestream <- ReadFindings(list(A,B,C),filestream,"NEXT")
stopifnot(getCaseStreamPos(filestream)==pos2,
          getCaseStreamLastId(filestream)==1002,
          abs(getCaseStreamLastFreq(filestream)-2.0) <.0001)


##Clean Up
CloseCaseStream(filestream)
CloseCaseStream(filestream) ## This should issue a warning but be
## harmless. 
DeleteNetwork(abc)
stopSession(sess)

---

Class "CliqueNode"

Description

A dummy node used to force it parents into the same clique in the junction tree. In particular, the node has a single state but its parents are listed in its clique field.

Extends

Class "NeticaNode", directly.

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

toString

signature(x = "CliqueNode"): Provides a pretited representation.

Fields

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

Name:

Object of class character giving the Netica name of the node. Must follow the IDname rules.

Netica_Node:

Object of class externalptr giving the address of the node in Netica's memory space.

Net:

Object of class NeticaBN, a back reference to the network in which this node resides.

discrete:

Always TRUE for clique nodes.

clique:

A list of NeticaNode objects which are the parents of the clique node.

Class-Based Methods

show():

Prints a description of the node.

initialize(..., clique):

Internal initializer, should not be called directly by user code. Use MakeCliqueNode instead.

The following methods are inherited (from the NeticaNode): deactivate ("NeticaNode"), isActive ("NeticaNode"), show ("NeticaNode"), clearErrors ("NeticaNode"), reportErrors ("NeticaNode"), initialize ("NeticaNode")

Note

Clique nodes only last for the R session that was used to create them. After that, they will appear like ordinary nodes. They will still be present in the network, but the special "clique" attribute will be lost.

Currently Netica only allows virtual evidence at the node level (NodeLikelihood()). I'm lobbying to get Netica to support it at the clique level as well. At which point, this function becomes extremely useful.

Author(s)

Russell Almond

References

Almond, R. G. & Mislevy, R. J. (1999) Graphical models and computerized adaptive testing. Applied Psychological Measurement, 23, 223-238.

Almond, R., Herskovits, E., Mislevy, R. J., & Steinberg, L. S. (1999). Transfer of information between system and evidence models. In Artificial Intelligence and Statistics 99, Proceedings (pp. 181–186). Morgan-Kaufmann

http://norsys.com/onLineAPIManual/index.html: See the NeticaEx function FormCliqueWith is the documentation for JointProbability_bn()

See Also

MakeCliqueNode(), NeticaNode, JointProbability(), AddLink(), JunctionTreeReport()

Examples

sess <- NeticaSession()
startSession(sess)

EMSMSystem <- ReadNetworks(system.file("sampleNets","System.dne",
                                       package="RNetica"),
                           session=sess)

CompileNetwork(EMSMSystem)
## Note that Skill1 and Skill2 are in different cliques
JunctionTreeReport(EMSMSystem)

Skills12 <- NetworkFindNode(EMSMSystem,c("Skill1","Skill2"))
cn <- MakeCliqueNode(Skills12)
cnclique <- GetClique(cn)

stopifnot(
  is.CliqueNode(cn),
  setequal(sapply(cnclique,NodeName),sapply(Skills12,NodeName))
)

CompileNetwork(EMSMSystem)
## Note that Skill1 and Skill2 are in different cliques
JunctionTreeReport(EMSMSystem)

DeleteNodes(cn) ## This clears the clique.

DeleteNetwork(EMSMSystem)
stopSession(sess)

---

Builds the junction tree for a Netica Network

Description

Before Netica performs inference in a network, it needs to compile the network. This process consists of building a junction tree and conditional probability tables for the nodes of that tree. The function CompileNetwork() compiles the network and UncompileNetwork() undoes the compilation and frees the associated memory.

Usage

CompileNetwork(net)
UncompileNetwork(net)
is.NetworkCompiled(net)

Arguments

net	An active NeticaBN which will be compiled.

Details

Usually Bayesian network projects operate in two phases. In the construction phase, new nodes are added to the network, new connections made and conditional probability tables are set.

In the inference phase, findings are added to nodes and other nodes are queried about their current conditional probability tables.

The functions CompileNetowrk() and UncompileNetwork() move the networks between the two phases. The documentation for EliminationOrder() and JunctionTreeReport() provide more details about the compilation process. The function NetworkCompiledSize() provides information about the amount of storage used by the compiled network, but only after the network is compiled.

The function is.NetworkCompiled() tests to see if a network is compiled or not.

Value

The NeticaBN object net is returned invisibly.

Warning

I'm currently observing a bug that occurs under Windows if not all of the nodes have their CPTs set. Under Linux the function exhibits the expected behavior: It generates a warning about the unset CPTs and enters a uniform distribution for each one. Under Windows it reports the warning, but then generates an error "GetError_ns: deleted or damage report_ns passed". It is unclear if this a problem in Netica or RNetica.

To work around, simply set all tables before compiling.

Note

Calling NetworkCompiledSize() on an uncompiled network produces, an error, but also the sensible value of -1. The function is.NetworkCompiled() calls the same internal function as NetworkCompiledSize, but clears the error. This means it also clears any other errors that might be lurking in the system (see ReportErrors()).

I think calling CompileNetwork() twice on the same network is harmless. Adding a node to a network will automatically uncompile it.

Author(s)

Russell Almond

References

http://norsys.com/onLineAPIManual/index.html: CompileNet_bn(), UncompileNet_bn(), SizeCompiledNet_bn(),

See Also

NeticaBN, HasNodeTable(), NodeFinding(), NodeBeliefs(), EliminationOrder(), JunctionTreeReport(), JointProbability(), MostProbableConfig(), FindingsProbability()

Examples

sess <- NeticaSession()
startSession(sess)

irt5 <- ReadNetworks(system.file("sampleNets","IRT5.dne",
                                 package="RNetica"),
                     session=sess)
stopifnot (!is.NetworkCompiled(irt5))

CompileNetwork(irt5) ## Ready to enter findings
stopifnot (is.NetworkCompiled(irt5))

UncompileNetwork(irt5) ## Ready to add more nodes
stopifnot (!is.NetworkCompiled(irt5))

DeleteNetwork(irt5)
stopSession(sess)

---

Makes copies of Netica networks.

Description

Makes a copy of the networks in the list nets giving them the names in newnamelist. The options argument controls how much information is copied.

Usage

CopyNetworks(nets, newnamelist, options = character(0))

Arguments

nets	A list of NeticaBN objects.
newnamelist	A character vector of the same length as nets which gives the names for the newly created copies.
options	A character vector containing information about what to copy. The elements should be one of the values "no_nodes", "no_links", "no_tables", "no_visual".

Details

Copies each of the networks in the nets lists, giving it a new name from the newnamelist. It returns a list of the new networks. If the specified net does not exist, then a warning is issued and a NULL is returned instead of the corresponding NeticaBN object.

The options argument is passed to the options argument of the Netica API function CopyNet_bn(). Meanings for the various arguments can be found in the documentation for that function. Note that Netica expects a list of comma separated values. RNetica will collapse the options argument into a comma separated list, so the argument can be given either as a character vector of length 1 containing a comma separated list, or the elements of that list in separate elements of a character vector.

Value

A list of NeticaBN objects corresponding to the new networks, or if the length of nets is one, a single NeticaBN object is returned instead. A NULL is returned instead of the NeticaBN object if the corresponding element of nets does not exit.

Author(s)

Russell Almond

References

http://norsys.com/onLineAPIManual/index.html: CopyNet_bn()

See Also

DeleteNetwork()

Examples

sess <- NeticaSession()
startSession(sess)

net1 <- CreateNetwork("Original", session=sess)
nets <- CreateNetwork(paste("Original",2:3,sep=""), session=sess)

copy1 <-CopyNetworks(net1,"Copy1")
stopifnot(is(copy1,"NeticaBN"))
stopifnot(copy1$Name == "Copy1")
stopifnot(copy1 != net1)

netc <- CopyNetworks(nets,paste("Copy",2:3,sep=""))
stopifnot(all(sapply(netc,is,"NeticaBN")))
stopifnot(netc$Name == c("Copy2","Copy3"))

DeleteNetwork(c(netc,nets,list(copy1,net1)))
stopSession(sess)

---

Copies or duplicates nodes in a Netica network.

Description

This function either copies nodes from one net to another or duplicates nodes within the same network.

Usage

CopyNodes(nodes, newnamelist = NULL, newnet = NULL, options = character(0))

Arguments

nodes	A list of active NeticaNode objects all from the same network.
newnamelist	If supplied, this should be character vector with the same length as nodes giving the new names for the nodes.
newnet	If supplied, it should be an active NeticaBN which is the destination for the new nodes. If this argument is NULL the nodes will be duplicated within the original network.
options	A character vector of options, with each element being one of the options. Currently, the only supported options are "no_tables" (do not copy the conditional probability tables for the nodes) and "no_links" (do not duplicate the links, which implies do not copy tables).

Details

The nodes in the first argument will be copied into a new network as specified by newnet. If newnet is not specified or if it the same as the network from which nodes come, then the nodes will be duplicated instead of copied.

If the nodes are duplicated, then will be given new names. The default Netica behavior for new names is to append a number to the end of the node name, or to increment an existing number. If newnamelist is supplied, these names will be used instead of the add a number convention. Supplying newnamelist will change the names of the nodes when copying from one network to another.

When nodes are copied links going into the node are copied as well. Thus if there is a link A -> B in the network and B is copied into the same network, then there will a link A -> B1 to the new node. If B is copied into a new network, the link will be there but not attached, as if NodeParents(B1)[A] <- NULL had been called.

The argument options allows control over what is copied. The currently supported options are:

• "no_tables" — The conditional probability tables of the nodes (see NodeProbs()) will not be copied, and new tables will need to be set in the new network.

• "no_links" — The links going into the nodes will not be copied. Note that the "no_links" option implies the "no_tables" option, so both do not need to be specified.

Value

A list containing the new nodes (or just the new node, if there is only one).

Note

There may be some information that is not copied. For example, the NodeSets() information is not copied.

Author(s)

Russell Almond

References

http://norsys.com/onLineAPIManual/index.html: CopyNodes_bn()

See Also

CopyNetworks(), NeticaNode, NeticaBN(), NodeProbs(), NodeParents(), AbsorbNodes(), DeleteNodes()

Examples

sess <- NeticaSession()
startSession(sess)
System <- ReadNetworks(system.file("sampleNets","System.dne",
                                   package="RNetica"),
                       session=sess)

EMTask1a <- ReadNetworks(system.file("sampleNets","EMTask1a.dne",
                                     package="RNetica"),
                         session=sess)

student1 <- CopyNetworks(System, "Student1")
student1.sysnodes <- NetworkAllNodes(student1)

student1.t1anodes <- CopyNodes(NetworkAllNodes(EMTask1a),newnet=student1)

## Copied, new nodes have the same names as the old nodes.
stopifnot(
  setequal(names(NetworkAllNodes(EMTask1a)),
           names(student1.t1anodes))
)

## The nodes in the evidence model have stub connections to the nodes in
## the system model.  Need to link them up.
stopifnot(
  any(sapply(NodeParents(student1.t1anodes[[1]]),NodeKind) == "Stub"),
  any(sapply(NodeParents(student1.t1anodes[[2]]),NodeKind) == "Stub")
)


student1.allnodes <- NetworkAllNodes(student1)
for (node in student1.t1anodes) {
  stubs <- sapply(NodeParents(node),NodeKind) == "Stub"
  NodeParents(node)[stubs] <- student1.allnodes[NodeInputNames(node)[stubs]]
}
stopifnot(
  sapply(NodeParents(student1.t1anodes[[1]]),NodeKind) != "Stub",
  sapply(NodeParents(student1.t1anodes[[2]]),NodeKind) !="Stub"
)

## Duplicate these nodes.
student1.t1xnodes <- CopyNodes(student1.t1anodes)

## Autonaming increments the numbers.  
stopifnot(
  setequal(names(student1.t1xnodes),c("Obs1a3","Obs1a4"))
)

## Duplicate and rename.
student1.t1cnodes <- CopyNodes(student1.t1anodes,c("Obs1c1","Obs1c2"))

stopifnot(
  setequal(names(student1.t1cnodes),c("Obs1c1","Obs1c2"))
)
## Duplicated nodes have real not stub connections.
stopifnot(
  sapply(NodeParents(student1.t1cnodes[[1]]),NodeKind) != "Stub",
  sapply(NodeParents(student1.t1cnodes[[2]]),NodeKind) !="Stub"
)


DeleteNetwork(list(System,student1,EMTask1a))
stopSession(sess)

---

Creates (destroys) a new Netica network.

Description

CreateNetwork() makes a new empty network in Netica, returning new NeticaBN objects. DeleteNetwork() frees the memory associated with the named network inside of Netica.

Usage

CreateNetwork(names, session=getDefaultSession())
DeleteNetwork(nets)

Arguments

names	A character vector giving the name or names of the network to be created.
session	An object of type NeticaSession which defines the reference to the Netica workspace.
nets	A list of NeticaBN objects to be destroyed.

Details

The CreateNetwork method creates a new network for each of the names. Names must follow the IDname rules. It returns a NeticaBN object, or a list of such objects if the argument names has length greater than 1.

The DeleteNetwork method frees the Netica memory associated with each net in its argument. Note that the network will not be available for use after it is deleted. It returns the NeticaBN objects, but modified so that they are no longer active.

The function is.active(), checks to see if the network associated with a NeticaBN object still corresponds to a network loaded into Netica's memory.

These functions wrap the Netica API functions NewNet_bn() and DeleteNet_bn().

Value

A single NeticaBN object if the length of the argument is 1, and a list of such objects if the argument has length greater than 1. For DeleteNets() if a specified network does not exist, the corresponding element in the return list will be NULL.

Implementation Note

In RNetica version 0.5 and later, the NeticaBN is used to store the refernce to the network. The enclosing NeticaSession object contains a table of network names to NeticaBN objects giving the pointer. It will signal an error if a network with the given name already exists and is active (not deleted).

In RNetica version 0.4 and prior, the NeticaBN object used the name of the networks to store the pointer into the network.

Note

The function DeleteNetwork() implicitly deletes any nodes associated with the network. Therefore, any nodes associated with this network will become inactive (see is.active()).

Author(s)

Russell Almond

References

http://norsys.com/onLineAPIManual/index.html: NewNet_bn(), DeleteNet_bn()

See Also

NeticaBN CopyNetworks(), is.active()

Examples

sess <- NeticaSession()
startSession(sess)

net1 <- CreateNetwork("EmptyNet", session=sess)
stopifnot(is(net1,"NeticaBN"))
stopifnot(net1$Name=="EmptyNet")
stopifnot(is.active(net1))

netd <- DeleteNetwork(net1)
stopifnot(!is.active(netd))
stopifnot(!is.active(net1))
stopifnot(netd$Name=="EmptyNet")

stopSession(sess)

---

Deletes the conditional probability table of a Netica node.

Description

This function completely removes the conditional probability table (CPT) associated with a node.

Usage

DeleteNodeTable(node)

Arguments

node	An active NeticaNode whose conditional probability table is to be tested.

Value

Returns the modified node invisibly.

Author(s)

Russell Almond

References

http://norsys.com/onLineAPIManual/index.html: DeleteNodeTables_bn()

See Also

NeticaNode, NodeParents(), NodeInputNames(), HasNodeTable()

Examples

sess <- NeticaSession()
startSession(sess)

a1 <- CreateNetwork("AB1", session=sess)
A <- NewDiscreteNode(a1,"A",c("A1","A2"))

NodeProbs(A) <- c(0,1)
stopifnot(
  all(HasNodeTable(A))==TRUE
)

DeleteNodeTable(A)
stopifnot(
  all(HasNodeTable(A))==FALSE
)

DeleteNetwork(a1)
stopSession(sess)

---

Serializes an R object to a string

Description

The function dputToString converts an R object to a string which can then be turned back into an R object using dgetFromString.

Usage

dgetFromString(str)
dputToString(obj)

Arguments

str	A string containing a serialized object
obj	An object to be serialized

Details

These functions call the base R functions dget and dput using a string buffer as the connection. Thus, they serialize the R object and return a string value which can be stored in a NeticaNode (see NodeUserObj) or or NeticaBN (see NetworkUserObj).

Note that the object must be self-contained.

Value

The function dputToString returns a character scalar containing the serialized object. Note: Sometimes R “helpfully” adds line breaks, returning a vector of strings. This can be fixed by using paste(dputToString(obj),collapse=" ").

The function dgetFromString returns an arbitrary R object depending on what was stored in str.

Author(s)

Russell Almond

See Also

NodeUserObj), NetworkUserObj

Examples

x <- sample(1L:10L)

x1 <- dgetFromString(dputToString(x))

stopifnot(all(x==x1))

---

Retrieves or sets the elimination order used in compiling a Netica network.

Description

The compilation process involves eliminating the nodes in the network one-by-one, different orders will produce junction trees of different sizes. The function EliminationOrder(net) returns the current elimination order associated with a network. The expression EliminationOrder(net) <- value sets the elimination order.

Usage

EliminationOrder(net)
EliminationOrder(net) <- value

Arguments

net	An active NeticaBN
value	Either NULL (to clear the elimination order) or a list of every node in net with no duplicates.

Details

Large cycles create problems for propagating probabilities in Bayesian networks. A solution to this problem is to fill-in chords (short cuts) in the cycles and then transform the network to a tree shape with the nodes of the tree representing cliques of the graph. This is commonly called a junction tree (although a junction tree additionally has nodes separating the cliques, called sepsets in Netica).

Finding the optimal pattern of fill-ins is an NP hard problem. A common way of approaching it is to eliminate the nodes from the network one-by-one and connect the neighbours of the eliminated node (if they were not already connected). In this case, the sequence of eliminated nodes will determine which edges are filled in, and hence the size of the final junction tree. Finding an optimal eliminator order is also NP hard, but simple heuristics (like the greedy algorithm) tend to do reasonably well in practice. (See Almond, 1995, for a complete description of the algorithm and heuristics solutions).

When Netica compiles a network (CompileNetwork(net)), it picks an elimination order, unless one has already been set. Unless the network has a particular difficult structure, then the Netica defaults should work pretty well. The function JunctionTreeReport(net) gives a report about the existing tree.

If the analyst has some clue about the structure of the network and wants to manually select the elimination order, this can be set through the form EliminationOrder(net)<-nodelist. Here nodelist should be a complete list of all of the nodes in net with no duplication. Alternatively, it can be set to NULL.

Setting the elimination order does not affect an already compiled network, it is only is applied when the network is next compiled.

Value

A list of all of the nodes in the network in elimination order if the elimination order is currently set, otherwise NULL.

The setter form returns net invisibly.

Note

The Netica documentation does not specify the heuristics for selecting the elimination order if no order is specified. I suspect it is some variation on the greedy algorithm, which works well in many cases.

Author(s)

Russell Almond

References

Almond, R.G. (1995) Graphical Belief Modeling. Chapman and Hall.

http://norsys.com/onLineAPIManual/index.html: GetNetElimOrder_bn(), SetNetElimOrder_bn(),

See Also

NeticaBN, NetworkAllNodes(), CompileNetwork(), JunctionTreeReport()

Examples

sess <- NeticaSession()
startSession(sess)

EMSMMotif <- ReadNetworks(system.file("sampleNets","EMSMMotif.dne",
                                       package="RNetica"),
                      session=sess)

## Should be null before we do anything.
stopifnot(
 is.null(EliminationOrder(EMSMMotif))
)

CompileNetwork(EMSMMotif)
## Now should have an elimination order.
stopifnot(
 length(EliminationOrder(EMSMMotif)) ==
 length(NetworkAllNodes(EMSMMotif)),
 NetworkCompiledSize(EMSMMotif) == 84
)
JunctionTreeReport(EMSMMotif)

## EMSMMotif is partitioned into observable and proficiency variables.
## Tell Netica to eliminate observable variables first.
EliminationOrder(EMSMMotif) <- c(NetworkNodesInSet(EMSMMotif,"Observable"),
                                 NetworkNodesInSet(EMSMMotif,"Proficiency"))
UncompileNetwork(EMSMMotif)
CompileNetwork(EMSMMotif)
stopifnot(
 length(EliminationOrder(EMSMMotif)) ==
 length(NetworkAllNodes(EMSMMotif)),
 NetworkCompiledSize(EMSMMotif) == 84
)
JunctionTreeReport(EMSMMotif)

## Clear elimination order.
EliminationOrder(EMSMMotif) <- NULL
stopifnot(
 is.null(EliminationOrder(EMSMMotif))
)

DeleteNetwork(EMSMMotif)
stopSession(sess)

---

Enters findings for multiple nodes in a Netica network.

Description

This function takes two arguments, a network and a list of nodes and the corresponding findings. It sets all of the findings at once.

Usage

EnterFindings(net, findings)

Arguments

net	An active and compiled NeticaBN.
findings	An integer or character vector giving the findings. The names(findings) should be names of nodes in net. The values of findings should be corresponding states either expressed as a character string or as an integer index into the list of states for that node. (See NodeFinding(node).

Details

This function enters findings for multiple nodes at the same time. It offers two improvements over repeated calls to NodeFinding(). First, it finds the nodes by name in the network, making it easier to work with data in the form of key–value pairs that might come from other systems. Second, it wraps the calls to NodeFinding() in a call to WithoutAutoUpdate() which should only propagate the new findings after all values have been entered.

Value

The value of net is returned invisibly.

Author(s)

Russell Almond

See Also

NeticaBN, NodeBeliefs(), EnterNegativeFinding(), NodeFinding(), RetractNodeFinding(), NodeLikelihood(), EnterGaussianFinding(), EnterIntervalFinding(), JointProbability(), NodeValue(), MostProbableConfig(), FindingsProbability()

Examples

sess <- NeticaSession()
startSession(sess)

Motif <- ReadNetworks(system.file("sampleNets","EMSMMotif.dne",
                                  package="RNetica"),
                      session=sess)

CompileNetwork(Motif)
obs <- c(Obs1a1="Right",Obs1a2="Wrong",
         Obs1b1="Right",Obs1b2="Wrong",
         Obs2a="Half", Obs2b="Half")

EnterFindings(Motif,obs)
JointProbability(NetworkNodesInSet(Motif,"Proficiency"))

DeleteNetwork(Motif)
stopSession(sess)

---

Enter a numeric finding with uncertainty

Description

This function a likelihood for a node that follows a Gaussian distribution with a given mean and standard deviation. This is entered as virtual evidence.

Usage

EnterGaussianFinding(node, mean, sem, retractFirst = TRUE)

Arguments

node	An active NeticaNode object that references the node. Node should be continuous, or have numeric value ranges assigned to it using NodeLevels(node).
mean	A numeric scalar giving the observed value (mean of the normal).
sem	A nonnegative numeric scalar giving the standard error of measurement for the observed finding (standard deviation of the normal).
retractFirst	A logical value. If true, any previous findings will be retracted first.

Details

The node must a continuous node that has been discretized using NodeLevels(node). The probabilities for each state are calculated based on a Gaussian distribution with the given mean and sem (SD).

Value

Return the node argument invisibly.

Warning

The Netica function EnterGaussianFinding_bn is not behaving at all like what I expected. In particular, I expect that it would behave like a normal likelihood, but instead it seems to be behaving as if I typed the expression NodeValue(node)<-mean. I've queried Norsys about this.

Meanwhile, I've worked around by calling NodeLikelihood instead of the internal Netica function.

Author(s)

Russell Almond

References

http://norsys.com/onLineAPIManual/index.html: EnterGaussianFinding_bn(),

See Also

EnterNegativeFinding(), EnterFindings(), RetractNodeFinding(), NodeLikelihood(), NodeFinding(), EnterIntervalFinding(), NodeValue()

Examples

sess <- NeticaSession()
startSession(sess)

cirt5 <- CreateNetwork("ContinuousIRT5", session=sess)

theta <- NewContinuousNode(cirt5,"Theta")
NodeLevels(theta) <- c(-5,-2.5,-1.5,-0.5,0.5,1.5,2.5,5)
NodeProbs(theta) <- rep(1/NodeNumStates(theta),NodeNumStates(theta))

CompileNetwork(cirt5) ## Ready to enter findings

EnterGaussianFinding(theta,0,1)
NodeBeliefs(theta)

stopifnot(all(abs(NodeBeliefs(theta) -
              diff(pnorm(NodeLevels(theta),0,1))) < .0001))

DeleteNetwork(cirt5)
stopSession(sess)

---

Enter finding of value within an interval

Description

Sets the finding associate with node to an interval.

Usage

EnterIntervalFinding(node, low, high, retractFirst = TRUE)

Arguments

node	An active NeticaNode object that references the node.
low	Lower bound of interval.
high	Upper bound of interval.
retractFirst	A logical value. If true, any previous findings will be retracted first.

Details

The node must a continuous node that has been discretized using NodeLevels(node). The probabilities for each state are calculated based on a uniform distribution with the given low and high endpoints.

Value

Return the node argument invisibly.

Note

The internal Netica function EnterIntervalFinding_bn is not behaving at all like what I expected. In particular, I expect that it would behave like a uniform likelihood, but instead it seems to be behaving as if I typed the expression NodeValue(node)<-low. I've queried Norsys about this.

Meanwhile, I've worked around by calling NodeLikelihood instead of the internal Netica function.

Author(s)

Russell Almond

References

http://norsys.com/onLineAPIManual/index.html: EnterIntervalFinding_bn()

See Also

EnterNegativeFinding(), EnterFindings(), RetractNodeFinding(), NodeLikelihood(), NodeFinding(), EnterGaussianFinding(), NodeValue()

Examples

sess <- NeticaSession()
startSession(sess)

cirt5 <- CreateNetwork("ContinuousIRT5", session=sess)

theta <- NewContinuousNode(cirt5,"Theta")
NodeLevels(theta) <- c(-5,-2.5,-1.5,-0.5,0.5,1.5,2.5,5)
NodeProbs(theta) <- rep(1/NodeNumStates(theta),NodeNumStates(theta))

CompileNetwork(cirt5) ## Ready to enter findings

EnterIntervalFinding(theta,-1,1)
NodeBeliefs(theta)

stopifnot(all(abs(NodeBeliefs(theta)*4-c(0,0,1,2,1,0,0))<.0001))


DeleteNetwork(cirt5)
stopSession(sess)

---

Sets findings for a Netica node to a list of ruled out values.

Description

This is conceptually equivalent to setting NodeFinding(node)<-not(eliminatedVals) (although this will not work as NodeFinding does not accept set values). It essentially eliminates any of the eliminatedVals as possible values (assigns them zero probability).

Usage

EnterNegativeFinding(node, eliminatedVals)

Arguments

node	An active NeticaNode whose value was observed or hypothesized.
eliminatedVals	A character or integer vector indicating the values to be ruled out. Character values should be one of the values in NodeStates(node). Integer values should be between 1 and NodeNumStates(node) inclusive.

Details

This function essentially asserts that $Pr(node \in eliminatedVals) = 0$. Thus, it rules out the values in the eliminatedVals set. Note that the length of this set should be less than the number of states, or all possibilities will have been eliminated.

Note calling EngerNegativeFining(node, ...) clears any previous findings (including virtual findings set through NodeLikelihood() or simple finding set through NodeFinding(node)<-value). The function RetractNodeFinding(node) will clear the current finding without setting it to a new value.

Value

This function returns node invisibly.

Note

If SetNetworkAutoUpdate() has been set to TRUE, then this function could take some time as each finding is individually propagated. Consider wrapping multiple calls setting NodeFinding() in WithoutAutoUpdate(net, ...).

Unlike the Netica function EnterFindingNot_bn() the function EnterNegativeFinding() internally calls RetractFindings. So there is no need to do this manually. Also, the internal Netica function multiplies multiple calls to EnterFindingNod_bn() add to the list of negative findings, while in the R version takes the entire list.

Author(s)

Russell Almond

References

http://norsys.com/onLineAPIManual/index.html: EnterFindingNot_bn()

See Also

NeticaBN, NodeBeliefs(), NodeFinding(), RetractNodeFinding(), NodeLikelihood()

Examples

sess <- NeticaSession()
startSession(sess)
irt5 <- ReadNetworks(system.file("sampleNets","IRT5.dne",
                                 package="RNetica"),
                     session=sess)

irt5.theta <- NetworkFindNode(irt5,"Theta")
irt5.x <- NetworkFindNode(irt5,paste("Item",1:5,sep="_"))

CompileNetwork(irt5) ## Ready to enter findings

## Calculated new expected beliefs
renormed <- NodeProbs(irt5.theta)
renormed[c("neg1","neg2")] <- 0
renormed <- renormed/sum(renormed)

## Negative finding
EnterNegativeFinding(irt5.theta,c("neg1","neg2")) ## Rule out negatives.
stopifnot(
  NodeFinding(irt5.theta) == "@NEGATIVE FINDINGS",
  sum(abs(NodeLikelihood(irt5.theta) - c(1,1,1,0,0))) < 1e-6,
  sum(abs(NodeBeliefs(irt5.theta) - renormed)) < 1.e-6
)


DeleteNetwork(irt5)
stopSession(sess)

---

Extracts portions of the conditional probability table of a Netica node.

Description

Provides an efficient mechanism for extracting or setting portions of large conditional probability tables. In particular, allows setting many rows a CPT to the same value. The node[] form is for chance (probabilistic) nodes, the node[[]] form is for deterministic (functional) nodes. See IsNodeDeterministic.

Usage

## S4 method for signature 'NeticaNode'
x[i, j,..., drop=FALSE] 
## S4 method for signature 'NeticaNode'
x[[i, j, ..., drop=FALSE]]  
## S4 replacement method for signature 'NeticaNode'
x[i, j, ...] <- value 
## S4 replacement method for signature 'NeticaNode'
x[[i, j, ...]] <- value 
EVERY_STATE

Arguments

x	An active, discrete NeticaNode whose conditional probability table is to be accessed.
i, j, ...	Indices specifying rows of the table to extract or replace. If a single index, i, is given, it should be a data frame selecting the parent states, or an integer pointing at a configuration. If multiple indexes are given, the number of indexes should correspond to the number of parent states of the variable. The values should either be character strings (corresponding to parent variable states), or numeric (indexes to parent states). In character strings, the special value "*" is allowed to select all values of that variable. In numeric indexes, the special value EVERY_STATE indicates that all states are selected. Leaving the index position blank is the same as specifying "*" or EVERY_STATE.
drop	If true and a single row is selected, that row will be returned as a numeric vector instead of a conditional probability frame (CPF).
value	Either a numeric vector with length NodeNumStates(x) giving the conditional probabilities for the specified rows in the table or a character scalar (discrete node) or numeric scalar (continuous node) giving the value that should be given probability 1.

Details

The function NodeProbs(node) allows one to access the entire conditional probability at once as a conditional probability array (CPA). Although the built-in R array replacement mechanisms allow one to make various kinds of edits, it is relatively inefficient. In particular, to set a single row of an array, the entire table is read into R and then written back to Netica.

This function allows the syntax node[...] to be used to access only a portion of the table. There are many different ways ... can be interpreted, which are described below.

In this access model the value EVERY_STATE or the character value "*" has a special meaning of match every level of that state variable. Netica supports this as a shortcut method for specifying conditional probability tables with many similar values. However, when reading the conditional probability tables from Netica they are expanded and no attempt is made to collapse over identical rows.

A second difference is that node[...] returns the conditional probability table in data frame (CPF) format. This is particularly convenient because that format does not need to cover every parent configuration, thus it is ideal for holding subset of the complete table.

A third difference is that if the last column of the conditional probabilities is not supplied, it will be computed. This is particularly handy for binary nodes.

Normally, the expression node[...] produces a data frame either in CPF format, or with the probabilities replaced by a single column of values. If drop==TRUE, only the matrix of probabilities or the vector of values will be returned. See also numericPart.

Deterministic nodes (see IsNodeDeterministic) should be accessed using the node[[...]] form. In this form, the node has a value table which maps a configuration of the parent values to a value of the node. That will be a numeric value for continuous nodes, and a factor for discrete variables. Note that Netica figures out whether or not a node is deterministic on the fly. For that reason, it is strongly recommended to use node[[...]] to access the value table, and node[...] to access the CPT.

In using the form node[[...]] <- value the value depends on whether the node is continuous or discrete. For continuous nodes, the node's value for a parent configuration (assuming all discrete or discretized parents) can be set directly if value is numeric. (If value is a factor or a string, it behaves like a discrete node.). For a discrete node, value can be a factor, string or integer, incidating the state. This creates a deterministic conditional probability table full of 1's and 0's.

The sections below describe the various indexing options.

Value

For the form node[...] the return value is a data frame in the CPF format giving the conditional probability table.

For the form node[[...]], if the node is deterministic (IsNodeDetermistic(node)==TRUE) then the probabilities will be replaced with a single column giving the value of the node. If the node is discrete, then the value will be a factor. If the node is continuous, then the value will be a real vector.

If drop==TRUE then the return value will be a matrix of probabilities (the last several columns of the data frame). If the node is deterministic, then the result will instead be either a factor (discrete node) or real vector (continuous node) giving the value of the node for each parent configuration.

The forms node[...]<-value and node[[...]]<-value return node invisibly.

Selecting Rows Using Data Frames

This selection uses the syntax node[df] or node[df]<-value, where df is a data frame or a matrix. It is assumed that the columns represent the variables, and the rows represent the selected configurations of the parent variables.

In this configuration, the number of rows of df and value should match (or the length of value should equal the number of rows if one of the special values is used). When the value is being queried rather than set, the number of rows in the result may be greater than the number of rows in df because of EVERY_STATE expansion.

There are three different ways that df could be represented:

1. It can be a data frame filled with factor variables whose levels correspond to the states of the corresponding parent node.

2. It can be a matrix or data frame of type character whose values correspond to the state names of the corresponding parent variables, or possibly the special value "*" meaning that all values of that parent should be matched.

3. It can be a matrix of data frame of integers whose values correspond to the state indexes of the parent variables. In this case the special value EVERY_STATE can be supplied indicating that all values should be matched. Otherwise, it should be a number between 1 and the number of states of that variable, inclusive.

The number of columns in df should be the same as the number of parent variables for node. If df has column names, then all columns should be named. In this case the parent variables will be match by the NodeInputNames(node) if they exist, or the names of the parent variables if they do not (see ParentStates(node) for more details). Otherwise, positional selection is used.

Selecting Rows Using Array-type Selection

The second way that rows from the conditional probability table can be selected is using an analogue of the selection mechanisms supported by R for selecting cells from an array. Essentially, the rows of the conditional probability table are treated as if they are the elements of an array whose dimnames correspond to ParentStates{node}. In particular the number of dimensions corresponds to the number of parent variables, and the extent of each dimension corresponds to the number of states of the corresponding parent variable.

In this selection mode, the length of ... should correspond to the number of parent variables (that is, there should be one fewer comma, than parent variables). Each element can be one of three things:

1. A character or factor vector selecting the appropriate states of the parent variable.

2. An integer vector selecting the appropriate states of the parent variable by position.

3. One of the special values EVERY_STATE, "*" or blank indicating that all values of the appropriate variable should be selected.

The order of the entries should be the same as the order of the parent variables in NodeParents{node}. The selection looks very similar to selection using a data frame, where the data frame consists of applying expand.grid(...).

Once again EVERY_STATE or "*" entries are treated specially inside of Netica, which allows every matching row of the table to be simultaneously set to the same probabilities.

Note that negative selections and logical selections are not currently supported.

Selecting Rows Using Named Parents

As with R array index selection, the dimensions of the selection in the ... argument can be specified using named arguments. If one of the elements of ... is named, they all should be named. The names should correspond to ParentNames(node), that is the NodeInputNames(node) are used if available, and the names of the parent nodes are used as a fallback.

As before the value for a parent variable can be set to a value or a vector of possible values as either an integer, factor or character value. The special values EVERY_STATE and "*" are interpreted as before. If the value of a parent variable is unspecified, this is equivalent to using the value EVERY_STATE.

Selecting Rows Using a Single Integer

If ... is a single integer, it is treated as an index into the possible configurations. These are defined by expand.grid(ParentStates(node). Each index refers to a row in that table. This is particularly meant for running through loops on all values, although working with value as a data frame or using NodeProbs may be faster in those cases.

There is some ambiguity when there is a single parent variable about whether the array-type selection or the index was intended, but both are identical, so there should be no conflict.

Special Meaning for NULL selection

If ... is NULL, that is if the calling expression looks like node[] then the intention is that all rows of the conditional probability table are to be selected. This is the only meaningful selection type if there are no parent variables. It also provides a fast and convenient way to set all rows of the conditional probability table to the same value (if value) has a single row, or to retrieve the complete conditional probability table in CPF format.

If value is a data frame with both factor and numeric variables, then it takes on a different meaning. In this case, the factor variables are used as if they were the selection argument (the ...) and the remaining numeric values the probabilities.

Setting Value to a Probability Matrix

In general the replacement value should be a matrix. The number of columns should match the number of states of node (see below for the behavior if the number of columns is one less than the number of states). It should have the same number of rows as the number of rows in the selection after any expansion has been applied for vector valued arguments, but not counting the special values EVERY_STATE or "*" (or blank entries in the list).

Netica has a special shortcut for EVERY_STATE and all matching rows are set to the same probability value. This means that the number of rows in the value must match the selection counting the special values as if they selected a single row. In particular, if node has one or more parent variables and value is a matrix with more than one row, node[] <- value will generate a error, because the selection has only one row (with every value set to EVERY_STATE).

When value is an undimensioned vector, the function will do its best to figure out if it should be treated as a row or a column vector. In the case of unusual behavior, expressing value as a matrix should make the programmer's intention clear.

Setting Deterministic Values

When a node is deterministic, that is all probabilities are $0$ or $1$, then it is meaningful to talk about the conditional value of a node instead of the conditional probability table. The expression node[[...]] displays the conditional probability table in a special way when the node is deterministic. In this case it displays the value as a single variable giving the state of the child variable given the configuration of the parents. In the case of discrete nodes, this is a factor variable giving the state. In the case of continuous nodes, this is a numeric vector giving the value.

The same conventions can be used in setting the conditional probability of a node. In the expression node[[...]] <- value if value is a factor or character vector then the selected configurations are set to deterministic probabilities with the indicated value given probability of $1$ and all others with probability $0$. It is possible to set some rows of a conditional probability table to be deterministic and others to have unrestricted probabilities, however, the deterministic rows will then print out as unconstrained probabilities with $0$ and $1$ values.

Continuous nodes (nodes for which is.continuous(node) == TRUE) use a variation of this system. Here the value is an arbitrary numeric value. For this to be meaningful, it is assumed that all of the parents of node are either discrete or have been discretized. The use of the node[[...]] <- value is particularly important for continuous nodes becuase it indicates that value is a potential value of the node rather than a probability.

Warning: Setting an unconditional discrete node to a constant value, that is executing an expression like node[[]] <- value is almost certainly a mistake. Probably what is intended by that expression is NodeFinding(node) <- value. In particular, if the former expression is used and the later someone attempts to set NodeFinding(node) <- value1, where value1 != value, this will produce a contradiction (probability zero event) and all kinds of error will follow.

Automatic normalization

If the number of columns in value is one less than the number of states in node, then is assumed that the probability values should be calculated for the last state via normalization, that is it is assigned all of the remaining probability not assigned in the first couple of columns. In particular, the value is internally translated via the expression: value <- cbind(value,1-apply(value,1,sum)).

This is particularly useful when the node is binary (has exactly 2 states). Then the replacement only needs to specify the probability for the first one. For example node[] <- .5 would set the probability distribution of node to the uniform distribution if node is binary.

There is some potential for confusion if value is not specified as a matrix. In particular, if the number of states of the child value is one more than the number of configurations of the parents, it is unclear whether this is an attempt to set the node value of a discrete node or an unnormalized probability. It should be possible by specifying value as a matrix or one row or one column to clarify the intent.

Backward Incompatable changes and Deprecated Uses

RNetica version 0.7 changed the ways that the node[...] and node[[...]] were handled, establishing that the former is for manipulating conditional probability tables, and the latter for manipulating value tables for deterministic nodes.

The return value of node[] for a deterministic node node has changed This now returns the conditional probability table. Use node[[]] to get the value table.

The use of node[[...]] as a synnonym for node[...,drop=TRUE] is deprecated. (I'm not sure it was working correctly).

The use of node[...]<- value to set rows in a function table for a discrete node is deprecated. Use node[[...]]<- value instead.

An error where node[...]<- value always treated continuous nodes as deterministic is fixed. (Note that continuous nodes cannot be treated as random unless they have been discretized.)

Note

I have tried to anticipate most of the ways that somebody might want to index the conditional probability table, not to mention all of the peculiar ways that R overloads the extraction operator. Negative selections are not allowed. I have almost certainly missed some combinations, and some untested combinations might preform rather strangely. Undoubtedly somebody will come to rely on that strangeness and it will never get fixed.

Factor variables do not easily handle the use of "*" as a wildcard. To make this work, a construction like factor(varstates, c(1:3,EVERY_STATE), labels=c("a1","a2","a3","*")).

Internally R uses 1-based indexing and Netica uses 0-based indexing. RNetica makes the translation inside of the C layer, so these function should be called with R-style 1-based indexing.

I'm having weird race conditions when trying to set the value of EVERY_STATE (I can't figure out how to call the C function to set its value after the C code is loaded but before the namespace is exported. So for now the exported EVERY_STATE is different from the internal Netica value (which is RNetica:::EVERY_STATE, at least in the current implementation). This should not be a visible change to the user.

This documentation file is longer than War and Peace.

Author(s)

Russell Almond

References

http://norsys.com/onLineAPIManual/index.html: GetNodeProbs_bn(), SetNodeProbs_bn(), GetNodeFuncState_bn(), SetNodeFuncState_bn(), GetNodeFuncReal_bn(), SetNodeFuncReal_bn(),

See Also

NeticaNode, NodeParents(), NodeInputNames(), NodeStates(), ParentStates(), CPF, CPA, IsNodeDeterministic

Examples

## Setup
sess <- NeticaSession()
startSession(sess)
xnet <- CreateNetwork("X", session=sess)

A <- NewDiscreteNode(xnet,"A",c("A1","A2","A3","A4"))
Aalt <- NewDiscreteNode(xnet,"Aalt",c("A1","A2","A3","A4"))
B <- NewDiscreteNode(xnet,"B",c("B1","B2","B3"))
B2 <- NewDiscreteNode(xnet,"B2",c("B1","B2"))
Balt <- NewDiscreteNode(xnet,"Balt",c("B1","B2","B3"))
C2 <- NewDiscreteNode(xnet,"C2",c("C1","C2"))
C3 <- NewDiscreteNode(xnet,"C3",c("C1","C2","C3"))
C4 <- NewDiscreteNode(xnet,"C4",c("C1","C2","C3","C4"))
Cont <- NewContinuousNode(xnet,"Cont")
CC <- NewContinuousNode(xnet,"CC")
CCC <- NewContinuousNode(xnet,"CCC")

### Tests for various setting modes.

## Null before we set any probabilities anything
stopifnot(
  all(is.na(C2[])), length(C2[]) == 2,
  all(is.na(Cont[])), length(Cont[])==1
)

NodeProbs(C2) <- c(1,0)
stopifnot(
  C2[[]]=="C1"
)
## This is just a demonstration of the syntax, in practice
## the expression NodeFinding(C2) <- "C2" is usually better.
C2[[]] <- "C2"
stopifnot(
  NodeProbs(C2)==c(0,1)
)
C3[[]] <- 3
stopifnot(
  C3[[]] == "C3"
)

## Setting value of continuous node
Cont[[]] <- 145.4
stopifnot( abs(Cont[[]] - 145.4) < .0001)

## Setting value with probabilities
C2[] <- c(.3,.7)
stopifnot( sum(abs(NodeProbs(C2)-c(.3,.7))) < .0001)
C3[] <- c(1,2,1)/4
stopifnot( sum(abs(NodeProbs(C3)-c(.25,.5,.25))) < .0001)

## Automatic normalization
C2[] <- .25
stopifnot( abs(sum(NodeProbs(C2)-c(.25,.75))) < .0001)
C3[] <- c(1,1)/3
stopifnot( abs(sum(NodeProbs(C3)-1/3)) < .0001)


### Now some one parent cases
AddLink(A,B)
AddLink(A,B2)

stopifnot(
  nrow(B[])==NodeNumStates(A),
  ncol(B[])==1+NodeNumStates(B),
  all(is.na(B[][,2:(1+NodeNumStates(B))]))
)

NodeProbs(B) <- normalize(matrix(1:12,4))
Brow1 <- B[1]
stopifnot(
  nrow(Brow1)==1,ncol(Brow1)==4,
  sum(abs(Brow1[,2:4]-c(1,5,9)/15))<.00001
)
Brow12 <- B[1:2]
stopifnot(
  nrow(Brow12)==2,ncol(Brow12)==4,
  sum(abs(Brow12[2,2:4]-c(2,6,10)/18))<.00001
)

Brow4 <- B["A4"]
stopifnot(
  nrow(Brow4)==1,ncol(Brow4)==4,
  sum(abs(Brow4[,2:4]-c(1,2,3)/6))<.00001
)
Brow34 <- B[c("A3","A4")]
stopifnot(
  nrow(Brow34)==2,ncol(Brow34)==4,
  abs(sum(Brow4[1,2:4]-c(3,7,11)/21))<.00001
)
Ball <- B["*"]
stopifnot(
  nrow(Ball)==4,ncol(Ball)==4
)
Ball <- B[EVERY_STATE]
stopifnot(
  nrow(Ball)==4,ncol(Ball)==4
)

Brow24 <- B[data.frame(A=factor(c("A2","A4"),NodeStates(A)))]
stopifnot(
  nrow(Brow24)==2,ncol(Brow24)==4,
  sum(abs(Brow24[2,2:4]-c(1,2,3)/6))<.00001
)

## Set all rows to the same value.
B[] <- matrix(c(1,1,1)/3,1)
stopifnot(
  abs(NodeProbs(B)-1/3)<.0001
)
B[EVERY_STATE] <- matrix(c(1,2,1)/4,1)
stopifnot(
  abs(NodeProbs(B)[3,]-c(.25,.5,.25))<.0001
)
B["*"] <- matrix(c(1,2,3)/6,1)
stopifnot(
  abs(NodeProbs(B)[2,]-c(1/6,1/3,.5))<.0001
)


## Setting to exact values
B2[[1:2]] <- "B1"
B2[[3]] <- "B2"
B2[[4]] <- "B2"
B2tab <- B2[[]]
stopifnot(
  IsNodeDeterministic(B2),
  nrow(B2tab)==4,ncol(B2tab)==2,
  B2tab[,2] == c("B1","B1","B2","B2"),
  as.integer(B2tab[,2]) == c(1,1,2,2)
)
## Setting one value to non-deterministic changes the way the table is
## displayed.
B2[2] <- c(.5,.5)
B2tab <- B2[]
stopifnot(
  !IsNodeDeterministic(B2),
  nrow(B2tab)==4,ncol(B2tab)==3,
  sum(abs(B2tab[2,2:3]- c(.5,.5))) < .001,
  B2tab[1,2:3] == c(1,0),
  B2[3,drop=TRUE] == c(0,1)
)

## Self-normalizing setting
## Not run: 
## This will generate an error because it is trying to set all four
## configurations to the same value but it is given four values.
B2[] <- c(.1,.2,.3,.4)

## End(Not run)

B2[1:4] <- c(.1,.2,.3,.4)
stopifnot(
  sum(abs(NodeProbs(B2)[,2]-c(.9,.8,.7,.6))) < .001
)
B2[1:2] <- .5  ## Set both values to the same thing
B2[3:4] <- c(.6,.7) ## set to normalizing probs
stopifnot(
  sum(abs(NodeProbs(B2)[,2]-c(.5,.5,.4,.3))) < .001
)
## Beware!  This next form assumes you are setting the rows to the same
## thing.
B2[3:4] <- c(.2,.8) ## Ambiguous instructions
stopifnot(
  sum(abs(NodeProbs(B2)[,2]-c(.5,.5,.8,.8))) < .001
)
## Using a matrix makes intent clear
B2[3:4] <- matrix(c(.2,.8),2) ## set to normalizing probs
stopifnot(
  sum(abs(NodeProbs(B2)[,2]-c(.5,.5,.8,.2))) < .001
)

## Data frame as value
## First do a blank extraction to get general shape.
B2frame <- B2[]
## Now manipulate it however
B2frame[,2:3] <- 1:8
## And set it back
B2[] <- normalize(B2frame)
stopifnot(
  sum(abs(NodeProbs(B2)[,1]-c(1/6,2/8,3/10,4/12))) <.001
)

B2frame1 <-B2frame[B2frame$A=="A3",]
B2frame1[,2:3] <- c(4,6)/10
B2[] <- B2frame1  ## Only row 3 affected
stopifnot(
  sum(abs(NodeProbs(B2)[,1]-c(1/6,2/8,4/10,4/12))) <.001
)

## Continuous node with one discrete parent
AddLink(A,Cont)  ##Notice how old value is replicated
stopifnot(
  nrow(Cont[[]]) ==4, ncol(Cont[[]]) == 2,
  abs(Cont[[]][,2]-145.4) <.0001,
  abs(Cont[[3,drop=TRUE]]-145.4) <.0001
)
AddLink(A,CC)
stopifnot(
  nrow(CC[]) ==4, ncol(CC[]) == 2,
  is.na(CC[][,2])
)

Cont[[]] <- 7
stopifnot(
  abs(Cont[[,drop=TRUE]]-7) <.0001
)
Cont[[2]] <- 3.2
stopifnot(
  abs(Cont[[,drop=TRUE]]-c(7,3.2,7,7)) <.0001
)

Cont[[1:2]] <- 0
Cont[[3:4]] <- c(8,1)
stopifnot(
  abs(Cont[[,drop=TRUE]]-c(0,0,8,1)) <.0001,
  abs(Cont[[3:4,drop=TRUE]]-c(8,1)) < .0001
)


## Two parent case
AddLink(A,C2)
AddLink(B,C2)

C2[] <- c(.5,.5)
stopifnot(
  nrow(C2[])==12, ncol(C2[])==4,
  sum(abs(numericPart(C2[])-.5)) < .0001
)
  

AddLink(A,C4)
AddLink(B,C4)
stopifnot(
  nrow(C4[])==12, ncol(C4[])==6,
  all(is.na(C4[,drop=TRUE]))
)

NodeProbs(C4) <- normalize(array(1:48,c(4,3,4)))


## Data Frame/matrix Selection

dfsel <- data.frame(A=factor(c("A2","A3"),levels=NodeStates(A)),
                    B=factor(c("B1","B3"),levels=NodeStates(B)))

C21.33 <- C4[dfsel]
stopifnot(
   nrow(C21.33)==2, ncol(C21.33)==6,
   C21.33[1,1] == "A2",
   C21.33[2,2] == "B3",
   abs(C21.33[1,3]-2/80) < .0001,
   abs(C21.33[2,4]-23/116) < .0001
)

dfselbak <- data.frame(B=factor(c("B3","B2"),levels=NodeStates(B)),
                       A=factor(c("A1","A4"),levels=NodeStates(A)))
C13.42 <- C4[dfselbak]
stopifnot(
   nrow(C13.42)==2, ncol(C13.42)==6,
   C13.42[1,1] == "A1",
   C13.42[2,2] == "B2",
   abs(C13.42[1,3]-9/108) < .0001,
   abs(C13.42[2,4]-20/104) < .0001
)

C2[dfsel] <- matrix(c(.7,.6,.3,.4),2)
C2[dfselbak] <- c(.9,.1)
stopifnot(
  sum(abs(numericPart(C2[])[,1] - c(.5,.7,.5,.5, .5,.5,.5,.9, .9,.5,.6,.5))) < .0001
)
## Test for error with using variables in selection inside of a
## function.
testSel <- function(node,sel1,sel2, val) {
 localselvar <- data.frame(sel1,sel2)
 names(localselvar) <- ParentNames(node)
 node[localselvar]
 node[localselvar]<-val
 invisible(node)
}
 
testSel(C2,factor(c("A2","A3"),levels=NodeStates(A)),
           factor(c("B1","B3"),levels=NodeStates(B)),
           matrix(c(.7,.6,.3,.4),2))


## Array-like selection
stopifnot(
  sum(abs(numericPart(C4[2,3])-c(10,22,34,46)/112))<.0001,
  sum(abs(numericPart(C4[B=2,A=4])-c(8,20,32,44)/104))<.0001
)

C1.23 <- C4[1,2:3]
stopifnot(
  nrow(C1.23)==2, ncol(C1.23)==6,
  sum(abs(C1.23[,3] - c(5/92 ,9/108))) <.0001
)
C2[] <- .5
C2[1,2:3] <- .99
stopifnot(
  sum(abs(numericPart(C2[])[,1] -
          c(.5,.5,.5,.5, .99,.5,.5,.5, .99,.5,.5,.5))) < .0001
)

C1.23 <- C4["A1",c("B2","B3")]
stopifnot(
  nrow(C1.23)==2, ncol(C1.23)==6,
  sum(abs(C1.23[,3] - c(5/92 ,9/108))) <.0001
)
C2[] <- .5
C2["A1",c("B2","B3")] <- .99
stopifnot(
  sum(abs(C2[,drop=TRUE][,1] - c(.5,.5,.5,.5, .99,.5,.5,.5, .99,.5,.5,.5))) < .0001
)

C34.12 <- C4[3:4,1:2]
stopifnot(
  nrow(C34.12)==4, ncol(C34.12)==6,
  sum(abs(C34.12[,3] - c(3/84,4/88, 7/100, 8/104))) <.0001
)
C2[] <- .5
C2[3:4,1:2] <- .99
stopifnot(
  sum(abs(C2[][,3] - c(.5,.5,.99,.99, .5,.5,.99,.99, .5,.5,.5,.5))) < .0001
)

## Wildcards

C1. <- C4[1,EVERY_STATE]
stopifnot(
  nrow(C1.) == 3, ncol(C1.)==6,
  sum(abs(C1.[,3] -c(1/76, 5/92, 9/108))) < .0001
)
C2[] <-.5
C2[1,EVERY_STATE] <- "C1"
stopifnot(
  sum(abs(C2[][,3] - c(1,.5,.5,.5, 1,.5,.5,.5, 1,.5,.5,.5))) < .0001
)

C.2 <- C4[EVERY_STATE,2]
stopifnot(
  nrow(C.2) == 4, ncol(C.2)==6,
  sum(abs(C.2[,3] -c(5/92, 6/96, 7/100, 8/104))) < .0001
)
C2[] <-.5
C2[[EVERY_STATE,2]] <- "C2"
stopifnot(
  sum(abs(C2[drop=TRUE][,1] - c(.5,.5,.5,.5, 0,0,0,0, .5,.5,.5,.5))) < .0001
)

C1. <- C4["A1","*"]
stopifnot(
  nrow(C1.) == 3, ncol(C1.)==6,
  sum(abs(C1.[,3] -c(1/76, 5/92, 9/108))) < .0001
)
C2[] <-.5
C2[["A1","*"]] <- "C1"
stopifnot(
  sum(abs(C2[drop=TRUE][,1] - c(1,.5,.5,.5, 1,.5,.5,.5, 1,.5,.5,.5))) < .0001
)

C.2 <- C4["*","B2"]
stopifnot(
  nrow(C.2) == 4, ncol(C.2)==6,
  sum(abs(C.2[,3] -c(5/92, 6/96, 7/100, 8/104))) < .0001
)
C2[] <-.5
C2[["*","B2"]] <- "C2"
stopifnot(
  sum(abs(C2[drop=TRUE][,1] - c(.5,.5,.5,.5, 0,0,0,0, .5,.5,.5,.5))) < .0001
)

## Missing parent values

C1. <- C4[1,]
stopifnot(
  nrow(C1.) == 3, ncol(C1.)==6,
  sum(abs(C1.[,3] -c(1/76, 5/92, 9/108))) < .0001
)
C2[] <-.5
C2[[1,]] <- "C1"
stopifnot(
  sum(abs(C2[drop=TRUE][,1] - c(1,.5,.5,.5, 1,.5,.5,.5, 1,.5,.5,.5))) < .0001
)

C.2 <- C4[,2]
stopifnot(
  nrow(C.2) == 4, ncol(C.2)==6,
  sum(abs(C.2[,3] -c(5/92, 6/96, 7/100, 8/104))) < .0001
)
C2[] <-.5
C2[[,2]] <- "C2"
stopifnot(
  sum(abs(C2[drop=TRUE][,1] - c(.5,.5,.5,.5, 0,0,0,0, .5,.5,.5,.5))) < .0001
)

C1. <- C4[A=1]
stopifnot(
  nrow(C1.) == 3, ncol(C1.)==6,
  sum(abs(C1.[,3] -c(1/76, 5/92, 9/108))) < .0001
)
C2[] <-.5
C2[[A=1]] <- "C1"
stopifnot(
  sum(abs(C2[drop=TRUE][,1] - c(1,.5,.5,.5, 1,.5,.5,.5, 1,.5,.5,.5))) < .0001
)

C.2 <- C4[B="B2"]
stopifnot(
  nrow(C.2) == 4, ncol(C.2)==6,
  sum(abs(C.2[,3] -c(5/92, 6/96, 7/100, 8/104))) < .0001
)
C2[] <-.5
C2[[B="B2"]] <- "C2"
stopifnot(
  sum(abs(C2[drop=TRUE][,1] - c(.5,.5,.5,.5, 0,0,0,0, .5,.5,.5,.5))) < .0001
)

## Data frame as value

dfset <- data.frame(A=factor(c("A2","A3"),levels=NodeStates(A)),
                    B=factor(c("B1","B3"),levels=NodeStates(B)),
                    C.C1=c(1,0), C.C2=c(0,1))
C2[] <- .5
C2[] <- dfset
stopifnot(
  sum(abs(C2[][,3] - c(.5,1,.5,.5, .5,.5,.5,.5, .5,.5,0,.5))) < .0001
)

## Continuous Child node
AddLink(B2,Cont)
stopifnot(
  nrow(Cont[[]])==8, ncol(Cont[[]])==3,
  sum(abs(Cont[[drop=TRUE]]-c(0,0,8,1))) < .0001
)

AddLink(A,CCC)
AddLink(B,CCC)
stopifnot(
  nrow(CCC[])==12, ncol(CCC[])==3,
  all(is.na(CCC[][,3]))
)

Cont[[]] <- 0
Cont[[1,1]] <- 1.1
Cont[[2:3,2]] <- c(2.2,3.2)
Cont[["A4","*"]] <- 4
## Not run: 
## Can't set to multiple values when using * selection.
Cont[["A4","*"]] <- c(4.1,4.2) ## Generates an error

## End(Not run)
stopifnot(
  sum(abs(Cont[[drop=TRUE]]-c(1.1,0,0,4,0,2.2,3.2,4))) < .0001,
  abs(Cont[["A1","B1",drop=TRUE]]-1.1) <.0001,
  sum(abs(Cont[[B=2,A=2:3,drop=TRUE]]-c(2.2,3.2))) < .0001,
  sum(abs(Cont[[A=4,drop=TRUE]] -4)) < .0001
)

## Set by integer count
## 12 rows in A*B combinations
for (i in 1:12) {
  CCC[[i]] <- i
  C2[i] <- i/100
}
stopifnot(
  sum(abs(CCC[[drop=TRUE]]-t(matrix(1:12,3,4)))) <.0001,
  sum(abs(C2[drop=TRUE][,1]-t(matrix(1:12/100,3,4)))) <.001
)
for (i in 1:12) {
  stopifnot(
    abs(CCC[[i,drop=TRUE]] - i) <.0001,
    abs(C2[i,drop=TRUE][1] - i/100) <.0001
  )
}

### Try some things with three parents, just to make sure that works
### too.
C2tab <- C2[drop=TRUE]
AddLink(C3,C2)
C2.1tab <- C2[,,"C1",drop=TRUE]
stopifnot(all.equal(C2tab,C2.1tab),
          all.equal(C2tab,C2[,,"C1",drop=TRUE]),
          all.equal(C2tab,C2[C="C3",drop=TRUE]))

stopifnot(all(abs(C2["A1","B1","C1",drop=TRUE]-NodeProbs(C2)[1,1,1,])<.0001),
          all.equal(C2["A1",,],C2[A="A1"]),
          all.equal(C2[,"B2",],C2[B="B2"]),
          all.equal(C2["A1","B2",],C2[B="B2",A="A1"]))


DeleteNetwork(xnet)
stopSession(sess)

---