CaseStream-class {RNetica}R Documentation

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):

Calls reportErrors on the Session object.

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)


[Package RNetica version 0.5-4 Index]