\name{NodeLikelihood}
\alias{NodeLikelihood}
\alias{NodeLikelihood<-}
\title{
  Returns or sets the virtual evidence associated with a Netica node.
}
\description{

  The findings associated with a node can be expressed as the
  probability of the evidence occurring in each of the states of the
  node.  This is the \emph{likelihood} associated with the node.  This
  function retrieves or sets the likelihood.

}
\usage{
NodeLikelihood(node)
NodeLikelihood(node) <- value
}
\arguments{
  \item{node}{
    An active \code{\linkS4class{NeticaNode}} whose evidence is to be
    queried or set.
  }
  \item{value}{
    A numeric vector of length \code{\link{NodeNumStates}(\var{node})}
    representing the new likelihood for the node.  All values must be
    between zero and one and there must be at least one positive value,
    but the sum does not need to equal 1.
  }
}
\details{

  This function retrieves or sets virtual evidence associated with each
  node.  Suppose that some set of evidence \eqn{e} is observed.  The
  each of the values in the likelihood represents the conditional
  probability \eqn{Pr(e|node==state)}.  Note that the likelihood can be
  thought of as the message that a new node \var{child} which was a
  child of \var{node} with no other parents would pass to \var{node}
  if its value was set.

  As the likelihood values are conditional probabilities, they do not
  need to add to 1, although they are still restricted to the range
  [0,1].  Also, at least one value must be non-zero (this represents an
  impossible case) or Netica will generpate an error.

  Entering findings through \code{\link{NodeFinding}(\var{node}) <-
  \var{state}} sets a special likelihood.  In this case, the likelihood value
  corresponding to \var{state} will be one, and all others will be zero.
  Similarly, the expression
  \code{\link{EnterNegativeFinding}(\var{node},\var{statelist})} sets a 
  special likelihood with 0's corresponding to the states in
  \var{statelist} and 1's elsewhere.

  Setting the likelihood calls \code{\link{RetractNodeFinding}()},
  clearing any previous finding, negative finding or likelihood.
  
}
\value{

  The function \code{NodeLikelihood(\var{node})} returns a vector of
  likelihoods of length \code{\link{NodeNumStates}(\var{node})}.  The names
  of the result are the state names.

  The expression \code{NodeLikelihood(\var{node})<-\var{value}} returns
  the modified node invisibly.

}
\references{
\newcommand{\nref}{\href{http://norsys.com/onLineAPIManual/functions/#1.html}{#1()}}
  \url{http://norsys.com/onLineAPIManual/index.html}:
  \nref{GetNodeLikelihood_bn}, \nref{EnterNodeLikelihood_bn}
}
\author{
  Russell Almond
}
\note{

  If \code{\link{SetNetworkAutoUpdate}()} has been set to \code{TRUE},
  then setting the likelihood could take some time as each finding is
  individually propagated.  Consider wrapping multiple calls setting
  \code{NodeLikelihood()} in \code{WithoutAutoUpdate(net, ...)}.

  Unlike the Netica function \code{EnterNodeLikelihood_bn()} the function
  \code{"NodeLikelihood<-"} internally calls \code{RetractFindings}.  So
  there is no need to do this manually.

}
\section{Warning}{

  The documentation for the Netica function \nref{MostProbableConfig_bn}
  states that likelihood findings are not
  properly taken into account in \code{\link{MostProbableConfig}()}.
  Some quick tests indicate that it is doing something sensible, but
  more extensive testing and/or clarification is needed.

  The documentation for the Netica function
  \nref{FindingsProbability_bn} also provides a warning about likelihood
  evidence.  The function \code{\link{FindingsProbability}(\var{net})} still
  gives a result, but it is the normalization constant for the network,
  and not necessarily a probability.

}
\seealso{
  \code{\linkS4class{NeticaBN}}, \code{\link{NodeBeliefs}()},
  \code{\link{EnterNegativeFinding}()},
  \code{\link{RetractNodeFinding}()}, \code{\link{NodeFinding}()}
  \code{\link{JointProbability}()},
  \code{\link{MostProbableConfig}()},
  \code{\link{FindingsProbability}()}
}
\examples{
sess <- NeticaSession()
startSession(sess)
irt5 <- ReadNetworks(file.path(library(help="RNetica")$path,
                           "sampleNets","IRT5.dne"), session=sess)

irt5.theta <- NetworkFindNode(irt5,"Theta")
irt5.x <- NetworkFindNode(irt5,paste("Item",1:5,sep="_"))

CompileNetwork(irt5) ## Ready to enter findings

## Simple finding
NodeFinding(irt5.x[[1]])<-"Wrong"
stopifnot(
  NodeLikelihood(irt5.x[[1]]) == c(0,1)
)

## Negative finding
EnterNegativeFinding(irt5.theta,c("neg1","neg2")) ## Rule out negatives.
stopifnot(
  NodeLikelihood(irt5.x[[1]]) == c(0,1),
  NodeLikelihood(irt5.theta) == c(1,1,1,0,0),
  NodeFinding(irt5.theta) == "@NEGATIVE FINDINGS"
)

## Clearing Findings
RetractNodeFinding(irt5.theta)
stopifnot(
  NodeLikelihood(irt5.theta) == c(1,1,1,1,1)
)

##Virtual findings for X3.  Assume judge has said right, but judge has
##  80\% accuracy rate.
NodeLikelihood(irt5.x[[3]]) <- c(.8,.2)
stopifnot(
  sum(abs(NodeLikelihood(irt5.x[[3]]) - c(.8,.2))) < 1e-6,
  NodeFinding(irt5.x[[3]]) == "@LIKELIHOOD"
)

## Add in virtual likelihood from a second judge
NodeLikelihood(irt5.x[[3]]) <- NodeLikelihood(irt5.x[[3]]) * c(.75,.25)
stopifnot(
  sum(abs(NodeLikelihood(irt5.x[[3]]) - c(.6,.05))) < 1e-6
)


DeleteNetwork(irt5)
stopSession(sess)

}
\keyword{ interface }
\keyword{ manip }