ReadFindings {RNetica}R Documentation

Retrieves a record from a Netica Case Stream

Description

This function reads a row from a Netica case stream and instantiates the values of the listed nodes to the values found in that row of the case stream.

Usage

ReadFindings(nodes, stream, pos = "NEXT", add = FALSE)

Arguments

nodes

The a list of active NeticaNode objects to be read. The findings of these nodes will be modified by this call.

stream

A CaseStream object which references the file or string object to be read from.

pos

A character or integer scalar. This should almost certainly be one of the two string values “FIRST” or “NEXT”. It also can be an integer giving the position (in characters) where to start the machine. This is likely to produce surprising results unless the integer value is a value obtained from calling getCaseStreamPos on this stream earlier after a call to either ReadFindings or WriteFindings.

add

A logical scalar. If true, the findings from the case stream are added to the existing node. If false, they are ignored.

Details

A case file is a table where the rows represent cases, and the columns represent variables. ReadFindings reads a row out the table and instantiates (NodeFinding) the nodes in nodeset to those values. If a the value corresponding a node is the value of CaseFileMissingCode(), then it is not instantiated. The values in the columns are separated by the value of CaseFileDelimiter().

If add is false, it will first retract any findings associated with the nodes in nodeset. If a finding is associated with a node, the the case file would cause it to be set to an inconsistent value, then an error will be generated.

The argument pos determines which record will be read next. If the value is "NEXT" the next code will be read. If the value is "FIRST" the first code will be read. If the value is a positive integer, then the record which starts at that character will be read. On completion of the read, the value of getCaseStreamPos(stream) is set to the starting position of the last read stream. This is also true when WriteFindings is called. It is almost certainly an error to set the pos argument to anything but either one of the special string constants or a value which was previously cached after calling getCaseStreamPos. If the case stream is at the end, then getCaseStreamPos(stream) will be set to NA.

There are two special columns in the file. The column “IDnum” contains ID numbers for the cases. The value of getCaseStreamLastId(stream) is set to the value of this column if it is present in the case stream, otherwise it will be set to -1. The value of the column “NumCases” contains a weight to give to the current row. The value of getCaseStreamLastFreq(stream) is set to this value, if it is present. The returned stream object will have these updated properties, otherwise it will be set to -1.

Value

Returns the caseOrStream argument invisibly. Note that the values of getCaseStreamPos(stream) will return the position of the next record or NA if there are no records left in the stream. The values of getCaseStreamLastId(stream), and getCaseStreamLastFreq(stream) will be updated to reflect the values from the last read record, or will be -1 if these values are not provided in the stream.

Note

The first time that ReadFindings is called on a stream it must be called with pos="FIRST". Failing to do so produces a fatal error in Netica.

The value of case_posn returned by the Netica ReadNetFindings2_bn function (which is the value to which getCaseStreamPos(stream)) is undocumented. I confirmed with Brent that this is in fact the position in characters from the start of the stream to the record. It is not recommended, however, that program rely on that fact.

The fact that the case positions are difficult to compute makes random access difficult. If it is needed, programmers will need to save the values of getCaseStreamPos on previous calls to ReadFindings or WriteFindings. Fetching cases by the ID requires scanning through the case file (see WithOpenCaseStream for an example).

Author(s)

Russell G. Almond

References

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

See Also

CaseFileDelimiter, CaseFileMissingCode, NodeFinding, RetractNetFindings ReadFindings, CaseStream, WithOpenCaseStream

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)

## Input filename
## Note, this is a cached copy of the file written in the WriteFindings
## documentation. 
casefile <- file.path(library(help="RNetica")$path,
                           "testData","abctestcases.cas")
filestream <- CaseFileStream(casefile, session=sess)
## Case 1
filestream <- ReadFindings(list(A,B,C),filestream,"FIRST")
stopifnot( NodeFinding(A) == "A1",
           NodeFinding(B) == "B1",
           NodeFinding(C) == "C1",
           getCaseStreamLastId(filestream)==1001,
           abs(getCaseStreamLastFreq(filestream)-1.0) < .0001)

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

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


## At end of file
filestream <- ReadFindings(list(A,B,C),filestream,"NEXT")
stopifnot(is.na(getCaseStreamPos(filestream)))

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

## Test with memory stream
cases <- read.CaseFile(casefile, session=sess)
abcstream <- CaseMemoryStream(cases, session=sess)
MemoryStreamContents(abcstream)


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


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


[Package RNetica version 0.8-4 Index]