About RNetica

RNetica is best thought of as a "glue" layer between the open source statistical programming language R http://www.r-project.org/ and the proprietary Bayesian network engine Netica ® http://www.norsys.com/. Although there are some minor extensions to the Netica API, the primary purpose of RNetica is to provide a binding for the Netica API functions inside of R.

There are two big advantages to this. One is that while the Netica GUI is helpful for model development, entering evidence by point and click is cumbersome for real work. Embedding the Netica API within R means that R can be used for data preparation and cleaning, the data can be entered into a model developed with the Netica GUI and the results extracted and graphed using the graphical power of R. The second big advantage is that R is an interpreted language, which supports rapid improvisation of code. This make it substantially faster to work in RNetica than using the C or Java APIs.

Getting Started

I recently did a demonstration of RNetica for my Bayes net class and recorded it using Tegrity. I'm posting a few of those resources here as a way of getting started.

User Registration Survey

There is now an RNetica user survey. I want to count my users so I can tell the funding agencies they should give me more money to work on it. Click here to fill out the survey.

News

The 0.5 release is a major rewrite of the fundamental Network and Node objects. This should improve stability, but may cause problems. The changes in the 0.5 series include the following:
  1. Introduced a new NeticaSession object as a container for the link to the Netica session. This also serves as a container for all of the networks included in a session and a wrapper for the license key.
  2. The license key mechanism is now handled differently. Now the Netica License Key string is passed to the NeticaSession object when it is constructed. If no session is specified for a function that requires one, then the variable DefaultNeticaSession in the global environment is referenced.
  3. Several functions now require a NeticaSession as an argument. These include the high level functions CreateNetwork, GetNthNetwork, GetNamedNetworks, and ReadNetworks. A session argument is also needed by some lower level functions which create Netica objects: CaseFileDelimiter, CaseFileMissingCode, CaseFileStream, CaseMemoryStream, OpenCaseStream and NewNeticaRNG. In all cases, if no session argument is supplied the value of DefaultNeticaSession is used instead.
  4. Objects of type NeticaSession, NeticaBN, NeticaNode, CaseStream, and NeticaRNG are now R reference classes (a special case of S4 classes) instead of strings with with attributes including an S3 class string. This should prove more robust as certain R functions (in particular, c()) which stripped the attributes.
    1. The function as.character for networks and nodes now returns a string of the form <Type: Name> instead of the name of the object. Use the expression obj$Name to get the name of the object.
    2. The primitive R function as.character has unexpected results when applied to a list of nodes (or presumably nets). In stead of recursively applying the proper as.character method for the class, it applies a default method which returns <S4 object of type \"NeticaNode">. Use sapply(nodelist,NodeName) instead.
    3. One unintended consequence of this is that the expression match(node, nodelist) no longer works as expected. This appears to be a bug in R as match turns objects into strings before matching, but the bug in as.character when applied to a list produces unexpected results. Use match(node, sapply(nodelist,NodeName)) instead.
  5. The way that Netica to R back pointers work has been changed in this release. In version 0.4 and before back pointers to the R objects were stored inside of the Netica Net and Node objects (using a special field designed for that purpose). However, there were some occasions on which functions which needed to find an R object for a Netica object (e.g., NodeParent) would sometimes return a non-R object (e.g., FALSE). In the new system network objects are cached in the NeticaSession object and node objects are cached in the NeticaBN object.
    1. The network cache is an environment called $nets in the NeticaSession object. This can be used in a read-only way by RNetica users. In particular, session$nets$netname, where netname is the Netica name of the network, can be used to reference a network in a session.
    2. The node cache is an environment called $nodes in the NeticaBN object. Again, this can be used in a read-only way, e.g., net$nodes$nodename.
    3. R objects for networks are created and registered with the cache in the session when the network is created (CreateNetwork) or read into RNetica (ReadNetworks). R objects are only created and registered with the cache in the network when first accessed. Calling the function NetworkAllNodes on the network will create R objects for all nodes in the network and register them.
  6. The CaseStream object is now an abstract class, with two concrete subclasses: FileCaseStream and MemoryCaseStream. Again, these are now represented as reference class objects and not strings with attributes, so they should be more robust.
    1. The constructors, CaseFileStream() and CaseMemoryStream() (note that the name of the constructor is not the name of the class) require a session attribute.
    2. The class MemoryCaseStream has been renamed name from "CaseSMemorytreamm". The constructor is still CaseMemoryStream() (this now matches the pattern used for FileCaseStream).
    3. There are still problems using MemoryCaseStream objects with some RNetica functions (notably LearnCPTs). For the moment, it is safer to stick with the files which seem to work better.
    4. It should be the case that CaseStream objects are closed when the session is stopped, but it is safer to use WithOpenCaseStream to ensure closure.
  7. Sessions are no longer started automatically when RNetica is loaded, they now must be started manually. The new commands startSession(), stopSession() and restartSession() (which take a session object as an argument) handle this.
    1. Typical calling sequence is session <- NeticaSession(LicenseKey="keystring") followed by startSession(session). If session is an object stored in the R global workspace, the first step only needs to be executed the first time RNetica is used, the second will be available thereafter.
    2. The function StartNetica creates a new Netica session and starts it. The function StopNetica stops the default session (unless given an argument).
    3. The old behavior can be restored by setting the value of the global variable DefaultNeticaSession to the session object. The function getDefaultSession() provides the default for most functions where a session argument is required. This uses the value of DefaultNeticaSession, starting it if it is currently closed. If the value is unset, the user will be prompted (in an interactive session) to create a value for this variable (using the value of NeticaLicenseKey if it exists) to create one.
    4. The Netica license key is stored as a unencrypted string in the NeticaSession object. Do not share licensed session objects with people who are not authorized to use that license key.
    5. It is unknown what will happen if two sessions are started at the same time, but unexpected consequences are quite likely.
  8. Error handling is now handled by the NeticaSession object. NeticaBN objects (as well as case stream and rng objects) have back pointers to the session object (the field $Session). NeticaNode objects have back pointers to the network objects (field $Net). This should be mostly transparent to users.
  9. A long standing bug in which a Netica error or warning would be followed by a series of warnings about bad error code has been found and fixed, as has a problem with the internal R protection stack that was trigger by this bug. This should result in greater stability.
  10. The functions in Peanut and PNetica version 0.2 are almost certainly not compatible with this release. An updated version of these packages should be available shortly. CPTtools should not be affected.

The 0.4 series of releases includes the following improvements:

  1. Added the functions MutualInfo, NodeExpectedValue and VarianceOfReal (user request, plus close to the top of my personal list).
  2. Minimal support for equation. (I find the CPTtools easier to use for manipulating conditional probability tables.)
  3. Added more functions for decision nets, although these are not currently working (support request in to Norsys).
  4. A few other functions related to calculating values and interval and Gaussian findings. Again, these are not working in the 0.4-1 version and a help request to Norsys is pending.
  5. Added some random findings generation code.
  6. Cleaned up the behavior of as.IDname() so that it makes shorter names and is properly vectorized.
  7. Fixed some minor errors and problems with error handling.
  8. Added a new cc() function (and methods for c()) to keep c() from dropping attributes. (Update these were dropped in RNetica 0.5.)

The 0.3 series of releases includes a number of different improvements.

  1. I now how official permission to distribute binary versions from Norsys. (You may want to still download and compile from sources you need the latest version of the API.)
  2. RNetica now passes the self-test under gctorture(TRUE), which should mean that is it is much more robust to memory errors. This is still a beta version, caution is still advisable.
  3. It now has case file support and includes support for learning conditional probability tables
  4. I've moved my development and testing platform to R 3.0.1. Binaries are build for R version 3.x.
  5. The version 0.3 cycle is more or less complete, except that I'm waiting for API updates from Norsys in response to problems.

Known issues with this release.

  1. There is currently no way through the Netica API to check whether EM and Gradient decent learning converged or timed out due to the maximum number of iterations being reached.
  2. Currently, memory streams cannot be used with the LearnCPTs functions. This appears to be a Netica problem.
  3. The functions EnterIntervalFinding and EnterGaussianFinding seem to give probability 1 to a single state no matter the width of the interval or the SD.
  4. The functions CalcNodeValue and CalcNodeState return NA when I think they should return a non-missing value.
  5. The function NodeExpectedUtils is generating an internal Netica error.
  6. The functions CreateNetwork and ReadNetworks assume that startSession() has been called. They now should give sensible error messages when this occurs.
  7. If a node has a name which is too close to the 30 character limit, and that node is disconnected from a link, leaving a stub variable, then the stub variable will have a name that is longer than 30 characters, causing problems. To avoid make sure names are no more than 26 characters. UPDATE. Changed as.IDname() to make shorter names.

Approximately 4/5 of the API functionality is mapped. Things that are still not mapped:

  1. Testers
  2. DBN functionality
  3. Database support (I see no need to do this as better to use the DBI R package).

RNetica License Information

There are three layers to the complete RNetica environment, each with their own licensing terms.

  1. The R Programming Language is released under the GNU General Public License (GPL) version 2. See the R FAQ for more information.
  2. The Netica API is a commercial product. License terms can be found on the Norsys® web site.
  3. RNetica itself (the combination of R and C code that provides the glue between R and Netica) is made available under the Artistic License, version 2.0.
I am not a lawyer, and therefore this should not be considered formal legal advise, but my understanding is that for most uses the use of RNetica requires the purchase of a Netica API license (which is different from the Netica GUI license) from Norsys.

Updated! Once you have obtained a license key from Norsys, the license is used by executing the following lines of code:

session <- NeticaSession(LicenseKey="Code from Norsys")
startSession(session)
where session can be replaced with any legal R identifier. Note that if DefaultNeticaSession is used as the identifier, most functions that need session arguments will accept this value instead. See the help for StartNetica() for alternative ways of using the License key. (Backwards compatibility is currently there.) Note that the Netica license key is stored in plain text in the NeticaSession object. Do not share that object (e.g., through sharing R dump files) with somebody who is not authorized to use that license.

Without the license key, the Netica API operates in a limited mode. All of the functions in the test scripts will run, but the size of the networks is generally limited.

Current Version Status

The current version (0.5-1) incorporates approximately 75% of the Netica C API Version 5.04 (there is a newer version for Windows but not for MacOS or Linux since 2012). This is sufficient functionality to build, compile and carry out inferences with a Bayesian network. Some of the more advanced functionality, including support for databases, influence diagrams, and dynamic Bayesian networks is not yet developed.

Although an extensive test script exists for RNetica (most of this is exposed on the manual pages), the testing away from these simple tests has been particularly light. In particular, I have not yet used valgrind to test for memory leaks. It is currently a beta release. Note that because it uses calls to C code, it is possible for RNetica to crash R. Plan your work accordingly.

The development has been with R version 3.0.1–3.4.1 under Ubuntu 16.04 with Netica API 5.04. R CMD check RNetica runs under Mac OS X and Windows 7 without errors. Almost all of the testing has been with the 64 bit versions of R and Netica. There may be some problems that crop up under 32 bit versions.

Version 0.2-7 was developed and tested under R 2.15.2. The windows binary for that version is a R 2.15 binary.

RNetica Releases

The following releases are archived here:

ReleaseSourceWindowsMacOSManualNotes
0.1-8RNetica_0.1-8.tar.gz First reasonably functional version.
0.2-5RNetica_0.2-5.tar.gz Initial version used for Newton's Playground
0.2-6RNetica_0.2-6.tar.gz RNetica-manual_0.2-6.pdfFixed Windows installation.
0.2-7RNetica_0.2-7.tar.gz RNetica_0.2-7.zip RNetica_0.2-7.tgz RNetica-manual_0.2-7.pdf Last Version for R 2.15
0.3-1RNetica_0.3-1.tar.gz RNetica-manual_0.3-1.pdf R 3.0: Added NodeExperience and Case Writing (not Reading)
0.3-3RNetica_0.3-3.tar.gz RNetica_0.3-3.zip RNetica_0.3-3.tgzRNetica-manual_0.3-3.pdf R 3.0: Support for Case Streams (file and memory)
0.3-4RNetica_0.3-4.tar.gz RNetica_0.3-4.zip RNetica_0.3-4.tgzRNetica-manual_0.3-4.pdf Learning CPTs
0.4-1RNetica_0.4-1.tar.gz RNetica_0.4-1.zip RNetica_0.4-1.tgzRNetica-manual_0.4-1.pdf Equations, Decisions, Continuous Nodes and Mutual Information
0.4-2RNetica_0.4-2.tar.gz RNetica_0.4-2.zip RNetica_0.4-2.tgzRNetica-manual_0.4-2.pdfRandom Findings Generation, as.IDname() cleanup, bug fixes
0.4-4RNetica_0.4-4.tar.gz RNetica_0.4-4.zip RNetica_0.4-4.tgzRNetica-manual_0.4-4.pdfPeanut compatibility, User Object support
0.4-5RNetica_0.4-5.tar.gz RNetica_0.4-5.zip RNetica_0.4-5.tgz RNetica-manual_0.4-5.pdf Peanut compatibility, User Object support
0.4-6RNetica_0.4-6.tar.gz RNetica_0.4-6.zip RNetica_0.4-6.tgz RNetica-manual_0.4-6.pdf Added cc() function and c() methods.
0.5-1RNetica_0.5-1.tar.gz RNetica_0.5-1.zip RNetica_0.5-1.tgz RNetica-manual_0.5-1.pdf New Object model; new Session objects.

Note the source versions have been compiled and tested under Linux/Unix, Mac OS X and Windows. Note that for Windows and Mac OS X, compiling source packages requires the R development kit to be installed. See the appropriate R FAQ for your operating system. You should also be familiar with building R packages, see the Writing R Extensions manual.

Compiling from sources requires that you have already downloaded and unpacked the Netica C API from Norsys. Under *nix (including Mac OS X) the location of the library can be passed to the configure command, e.g.:

R CMD INSTALL RNetica --configure-args='--with-netica=/Users/ralmond/software/Netica_API_504/'

Under Windows (or as an alternative to the --with-netica switch), the environmental variable NETICA_HOME can be set to the location in which the Netica API was unpacked. I have only tested with the API version 5.04, not with earlier (or later) versions.

Although I am now supplying Windows and Mac OS X binaries, which include the Netica API (currently version 5.04). As this is still an early test release, it will help you to have a local R guru to ask support questions, and help file bug reports if needed. NOTE: this is an unlicensed version of the API: you still need to purchase a license (although the unlicensed version will run the sample code in the man pages).

A recent (not so recent anymore) communication with Brent indicated that a new Netica API will be out soon. When that comes out, there will likely be a big update.

Development Version

The latest development version is available as a subversion repository at: https://pluto.coe.fsu.edu/svn/common/RNetica/. There is also a branch corresponding to the old object model at: https://pluto.coe.fsu.edu/svn/common/RNetica/branches/RNeticaS3.

If you have patches or other correspondence about RNetica you can contact me at almond@acm.org. If you are filing a bug report, please be sure to include the following information:

  1. The version number of RNetica and R that you are using.
  2. Your operating system and whether it is 64 or 32 bit.
  3. The exact text of any error message that is generated.
  4. A small script that reproduces the problem (if at all possible).

Legal Notices

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

Although Norsys has been generally supportive of the RNetica project, they do not offer formal support in any way. (In particular, the do not currently have anybody on staff who knows R.) All support requests should be sent to the package maintainers.

The software is offered AS IS, without any warranty of any kind. Support is provided on a volunteer basis, and may not be immediately forthcoming.


Site last updated on 2017-03-30. Site last updated on 2017-09-18.