\name{LearnCases}
\alias{LearnCases}
\title{Learn Conditional Probability Tables from a Netica Case Stream
}
\description{
This function updates the conditional probabilities associated with
the given list of nodes based on the findings associated with that
node and its parents found in the \code{caseStream} argument, which
should be a \code{\linkS4class{CaseStream}} object.
}
\usage{
LearnCases(caseStream, nodelist, weight = 1)
}
\arguments{
\item{caseStream}{This should be a \code{\linkS4class{CaseStream}}
object, or else an object which can be made into a case stream:
either a pathname for a case file, or a data frame of the format
described in \code{\linkS4class{MemoryCaseStream}}. The case stream can be
either opened or closed. If closed it is reopened before updating.
In either case, it is closed at the end of the function.
\bold{Warning}, due to a bug in Netica, memory streams are not
working and should not be used with Netica API 5.04 or earlier. See
below.
}
\item{nodelist}{
A list of active \code{\linkS4class{NeticaNode}} objects that reference the
conditional probability tables to be updated.
}
\item{weight}{
A multiplier for the weights of the cases in terms of number
of observations. Negative weights unlearn previously learned cases.
}
}
\details{
This is like calling the function \code{\link{LearnFindings}}
repeatedly with the values of the nodes set to each of the case rows
in turn. Thus, it updates the conditional probability tables for each
nodes based on observed counts in the case files, taking the current
probability and the \code{\link{NodeExperience}} as the prior
distribution.
If the case stream has a column \code{NumCases}, then the weight
assigned to Row \eqn{j} is \code{weight*NumCases[j]}. If the case
stream does not have such a column, then it is treated as if each
column has weight 1. (Among other purposes, this allows case data to
be stored in a compact format where all of the possible cases are
enumerated along with a count of repetitions.) Note that negative
weights will unlearn cases.
}
\value{
This function returns the \code{\linkS4class{CaseStream}} used in the
analysis. This might have either been passed directly as the
\code{caseStream} argument, or created from the value of the
\code{caseStream} argument. In either case, the stream is closed at
the end of the function.
}
\references{
\newcommand{\nref}{\href{http://norsys.com/onLineAPIManual/functions/#1.html}{#1()}}
\url{http://norsys.com/onLineAPIManual/index.html}:
\nref{ReviseCPTsByCaseFile_bn}
}
\author{Russell Almond}
\note{
To learn without using the current probabilities as priors, call
\code{\link{DeleteNodeTable}} first.
}
\section{Netica Bugs}{
In version 5.04 of the Netica API, there is a problem with using
Memory Streams that seems to affect the functions
\code{\link{LearnCases}} and \code{\link{LearnCPTs}}. Until this
problem is fixed, most uses of Memory Streams will require file
streams instead. Write the case file using
\code{\link{write.CaseFile}}, and then create a file stream using
\code{\link{CaseFileStream}}.
}
\seealso{
\code{\link{NodeExperience}}, \code{\link{NodeProbs}},
\code{\link{NodeFinding}}, \code{\link{FadeCPT}},
\code{\link{LearnFindings}}, \code{\link{DeleteNodeTable}},
\code{\link{LearnCPTs}}
}
\examples{
sess <- NeticaSession()
startSession(sess)
abb <- CreateNetwork("ABB", session=sess)
A <- NewDiscreteNode(abb,"A",c("A1","A2"))
B1 <- NewDiscreteNode(abb,"B1",c("B1","B2"))
B2 <- NewDiscreteNode(abb,"B2",c("B1","B2"))
AddLink(A,B1)
AddLink(A,B2)
A[] <- c(.5,.5)
NodeExperience(A) <- 10
B1["A1"] <- c(.8,.2)
B1["A2"] <- c(.2,.8)
B2["A1"] <- c(.8,.2)
B2["A2"] <- c(.2,.8)
NodeExperience(B1) <- c(10,10)
NodeExperience(B2) <- c(10,10)
casesabb <-
data.frame(A=c("A1","A1","A1","A1","A1","A2","A2","A2","A2","A2"),
B1=c("B1","B1","B1","B2","B2","B2","B2","B2","B1","B1"),
B2=c("B1","B1","B1","B1","B2","B2","B2","B2","B2","B1"))
## LearnCases(casesabb,list(A,B1))
## There is currently a bug in Netica, so that this function does not
## work with memory streams. As a work around, use proper file streams
## instead.
outfile <- tempfile("casesabb",fileext=".cas")
write.CaseFile(casesabb,outfile, session=sess)
LearnCases(outfile,list(A,B1))
## Probs for A & B1 modified, but B2 left alone
stopifnot(
NodeExperience(A)==20,
NodeExperience(B1)==c(15,15),
NodeExperience(B2)==c(10,10),
sum(abs(NodeProbs(A) - .5)) < .001,
sum(abs(B1[["A1"]] - c(11,4)/15)) < .001,
sum(abs(B1[["A2"]] - c(4,11)/15)) < .001,
sum(abs(B2[["A1"]] - c(8,2)/10)) < .001,
sum(abs(B2[["A2"]] - c(2,8)/10)) < .001
)
DeleteNetwork(abb)
stopSession(sess)
}
\keyword{ interface }
\keyword{ model }