MemoryCaseStream-class {RNetica}R Documentation

Class "MemoryCaseStream"

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 data frame containing the dase file information. The function CaseMemoryStream is the constructor. 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.

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 FileCaseStream, the MemoryCaseStream is a subclass of CaseStream and follows the same conventions.

The function CaseMemoryStream 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.

Extends

Class "CaseStream", 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.

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.

Fields

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

Name:

Object of class character identifier for stream. Default is the expression used to reference the data.

Session:

Object of class NeticaSession

Session:

Object of class NeticaSession a link to the session in which this case stream was created.

Netica_Case_Stream:

Object of class externalptr a pointer to the case stream in 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.

Case_Stream_DataFrameName:

Object of class character giving the expression used for the data frame.

Case_Stream_DataFrame:

Object of class data.frame or NULL the data object that is the contents of the buffer, or NULL if the stream was created for writing.

Case_Stream_Buffer:

Object of class externalptr used for an R-side string buffer, currently not used.

Methods

open():

Opens a connection too the file in Netica.

show():

Provides a description of the field

initialize(Name, Session, Case_Stream_Path, ...):

internal constructor; user code should use CaseFileStream.

The following methods are inherited (from CaseStream): close ("CaseStream"), isActive ("CaseStream"), isOpen ("CaseStream"), show ("CaseStream"), clearErrors ("CaseStream"), reportErrors ("CaseStream"), initialize ("CaseStream")

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 constructore had the same name). This matches the usage of FileCaseStream and its constructor CaseFileStream. This is not likely to be a problem as memory streams are not working well.

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

See CaseStream for the superclass and FileCaseStream for a sibling class. The function CaseMemoryStream is the constructor.

CaseFileDelimiter, CaseFileMissingCode, WriteFindings, ReadFindings, MemoryStreamContents

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 <- file.path(library(help="RNetica")$path,
                           "testData","abctestcases.cas")
                     
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)


[Package RNetica version 0.7-3 Index]