\name{twoway.entropy}
\alias{twoway.entropy}
\alias{print.twoway.entropy}
\alias{plot.twoway.entropy}
\title{Bivariate Informationtheoretic Measures}
\description{
  These functions calculate bivariate informationtheoretic measures, like \emph{joint entropy}, \emph{conditional entropy} and \emph{mutual information}.
}
\usage{
twoway.entropy(p, grain=c("Totals","Margins","Cells"))
print.twoway.entropy(x, ...)
plot.twoway.entropy(x, ...)
}
\arguments{
  \item{p}{ matrix of two-way probabilities (or frequencies) }
  \item{x}{ on object of class twoway.entropy }
  \item{grain}{ one of c("Totals","Margins","Cells") determining the granularity of the return value }
  \item{\dots}{ further arguments to plot,print }
}
\value{
  An object of class twoway.entropy with components
  \item{Totals}{always returned: a list with components \emph{H} joint entropy, \emph{Ha} row entropy, \emph{Hab}  row conditional entropy given columns, \emph{Hb} column entropy, \emph{Hba} column conditional entropy given rows, \emph{Im} mutual information }
  \item{Margins}{returned unless grain="Total": \emph{pa} row probabilities , \emph{ha} row entropie, \emph{hab} colwise conditional entropies, \emph{pb} column probabilities, \emph{hb} column entropy , \emph{hba} rowwise conditional entropies}
  \item{Cells}{returned if grain="Cells": \emph{p} joint probabilities, \emph{pab} columnwise conditional probabilities, \emph{pba} rowwise conditional probabilities, \emph{h} joint entropies, \emph{hab} columnwise conditional entropies, \emph{hba} rowwise conditional entropies }
}
\references{ MacKay, David J.C. (2003). \emph{Information Theory, Inference, and Learning Algorithms (chapter 8).} Cambridge University Press.}
\author{ Jens Oehlschlägel }
\seealso{ \code{\link{shannon.information}}, \code{\link[distutil]{dist.entropy}}, \code{\link{Kullback.Leibler}}, \code{\link[base]{log}} }
\examples{
 # Exercise 8.6 from MacKay
 p <- 1/matrix(c(8,16,16,4,16,8,16,Inf,32,32,16,Inf,32,32,16,Inf), 4)
 twoway.entropy(p)
 twoway.entropy(p, grain="Cells")
 str(twoway.entropy(p, grain="Cells"))
 plot(twoway.entropy(p), main="Plot from MacKay (2003), chapter 8.1")

 # Highly correlated data
 x <- rnorm(100)
 y <- x + rnorm(100, sd=0.1)
 a <- round(x)
 b <- round(y)
 p <- table(a, b)
 plot(twoway.entropy(p), main=paste("correlation=", round(cor(x,y), 2)))
}
\keyword{ multivariate }
