ReadFindings {RNetica} | R Documentation |
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.
ReadFindings(nodes, stream, pos = "NEXT", add = FALSE)
nodes |
The a list of active |
stream |
A |
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 |
add |
A logical scalar. If true, the findings from the case stream are added to the existing node. If false, they are ignored. |
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
.
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.
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).
Russell G. Almond
http://norsys.com/onLineAPIManual/index.html: ReadNetFindings2_bn()
CaseFileDelimiter
, CaseFileMissingCode
,
NodeFinding
, RetractNetFindings
ReadFindings
, CaseStream
,
WithOpenCaseStream
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)