\name{nem}
\alias{nem}
\alias{print.nem}

\title{Nested Effects Models - main function}
\description{The main function to infer a phenotypic hierarchy from data}
\usage{
nem(D,inference="nem.greedy",models=NULL,type="mLL",para=NULL,hyperpara=NULL,Pe=NULL,Pm=NULL,Pmlocal=NULL,local.prior.size=length(unique(colnames(D))),local.prior.bias=1,triples.thrsh=0.5,lambda=0,delta=1,selEGenes=FALSE,trans.close=TRUE,verbose=TRUE)

\method{print}{nem}(x, ...)
}

\arguments{
  \item{D}{data matrix with experiments in the columns (binary or continious)}
  \item{inference}{\code{search} to use exhaustive enumeration, \code{triples} for triple-based inference, \code{pairwise} for the pairwise heuristic, \code{ModuleNetwork} for the module based inference, \code{nem.greedy} for greedy hillclimbing, \code{nem.greedyMAP} for alternating MAP optimization using log odds or log p-value densities}
  \item{models}{a list of adjacency matrices for model search. If NULL, \code{enumerate.models} is used for exhaustive enumeration of all possible models.}
  \item{type}{\code{mLL} or \code{FULLmLL} or \code{CONTmLL} or \code{CONTmLLBayes} or \code{CONTmLLMAP}. \code{CONTmLLDens} and \code{CONTmLLRatio} are identical to \code{CONTmLLBayes} and \code{CONTmLLMAP} and are still supported for compatibility reasons. \code{mLL} and \code{FULLmLL} are used for binary data (see \code{BoutrosRNAiDiscrete}) and \code{CONTmLL} for a matrix of effect probabilities. \code{CONTmLLBayes} and \code{CONTmLLMAP} are used, if log-odds ratios, p-value densities or any other model specifies effect likelihoods. \code{CONTmLLBayes} refers to an inference scheme, were the linking positions of E-genes to S-Genes are integrated out, and \code{CONTmLLMAP} to an inference scheme, were a MAP estimate for the linking positions is calculated.}
  \item{para}{vector of length two: false positive rate and false negative rate for binary data. Used by \code{mLL}} 
  \item{hyperpara}{vector of length four: used by \code{FULLmLL()} for binary data}
  \item{Pe}{prior of effect reporter positions in the phenotypic hierarchy (same dimension as D)}
  \item{Pm}{prior over models (n x n matrix)}
  \item{Pmlocal}{local model prior for pairwise and triple learning. For pairwise learning generated by \code{local.model.prior} according to arguments \code{local.prior.size} and \code{local.prior.bias}}
  \item{local.prior.size}{prior expected number of edges in the graph (for pairwise learning)}
  \item{local.prior.bias}{bias towards double-headed edges. Default: 1 (no bias; for pairwise learning)}
  \item{triples.thrsh}{threshold for model averaging to combine triple models for each edge}
  \item{lambda}{regularization parameter to incorporate prior assumptions. Default: 0 (no regularization)}
  \item{delta}{regularization parameter for automated E-gene subset selection (CONTmLLMAP only)}
  \item{selEGenes}{automated E-gene subset selection (includes tuning of delta for CONTmLLMAP)}  
  \item{trans.close}{Should always transitive closed graphs be computed? Default: TRUE. NOTE: This has only an impact for the  \code{nem.greedyMAP} method.}
  \item{verbose}{do you want to see progression statements? Default: TRUE}

  \item{x}{nem object}
  \item{...}{other arguments to pass}
}
\details{
  \code{nem} is an interface to the functions \code{score}, \code{pairwise.posterior}, \code{triple.posterior}, \code{moduleNetwork}, \code{nem.greedy} and \code{nem.greedyMAP}. 
   If Pm != NULL and lambda == 0, a Bayesian approach to include prior knowledge is used. Alternatively, the regularization parameter lambda can be tuned in a model selection step via the function \code{nemModelSelection} using the BIC criterion. 
   If automated E-gene subset selection is used and type == CONTmLLMAP, the regularization parameter delta is tuned via the AIC model selection criterion. Otherwise, an iterative algorithm is executed, which in an alternating optimization scheme reconstructs a network given the current set of E-gene and then selects the E-genes having the highest likelihood under the given network. The procedure is run until convergence.

  The function \code{plot.nem} plots the inferred phenotypic hierarchy as a directed graph, the likelihood distribution of the models (only for exhaustive search) or the posterior position of the effected genes.  
}
\value{
  \item{graph}{the inferred directed graph (graphNEL object)}   
  \item{mLL}{log posterior marginal likelihood of final model} 
  \item{pos}{posterior over effect positions}
  \item{mappos}{MAP estimate of effect positions} 
  \item{type}{as used in function call}
  \item{para}{as used in function call}
  \item{hyperpara}{as used in function call}
  \item{lambda}{as in function call}
  \item{delta}{as in function call}
  \item{selected}{selected E-gene subset}
  \item{LLperGene}{likelihood per selected E-gene}
}

\author{Florian Markowetz <URL: http://genomics.princeton.edu/~florian>, Holger Froehlich <URL: http:/www.dkfz.de/mga2/people/froehlich>}


\seealso{\code{\link{nemModelSelection}}, \code{\link{nem.jackknife}}, \code{\link{nem.bootstrap}}, \code{\link{nem.consensus}}, \code{\link{score}}, \code{\link{moduleNetwork}}, \code{\link{nem.greedy}}, \code{\link{triples.posterior}}, \code{\link{pairwise.posterior}}, \code{\link{nem.greedyMAP}},  \code{\link{local.model.prior}}, \code{\link{enumerate.models}}, \code{\link{plot.nem}}}
\examples{
   data("BoutrosRNAi2002")
   D <- BoutrosRNAiDiscrete[,9:16]
   p <- c(.13,.05)
   res1 <- nem(D,para=p,inference="search")
   res2 <- nem(D,para=p,inference="pairwise")
   res3 <- nem(D,para=p,inference="triples")
   res4 <- nem(D,para=p,inference="ModuleNetwork")
   res5 <- nem(D,para=p,inference="nem.greedy")  
   res6 = nem(BoutrosRNAiLods, inference="nem.greedyMAP")
   

   par(mfrow=c(2,3))
   plot(res1,main="exhaustive search")
   plot(res2,main="pairs")
   plot(res3,main="triples")
   plot(res4,main="module network")
   plot(res5,main="greedy hillclimber")      
   plot(res6,main="alternating MAP optimization")
}
\keyword{graphs}
\keyword{models}