Added circuit example to Readme

.Rbuildignore

@@ -1,2 +1,3 @@
 ^.*\.Rproj$
 ^\.Rproj\.user$
+^data-raw$

README.md

@@ -14,7 +14,6 @@ Given three random vectors `x1`, `x2` and `z`, the PID can be calculated from th
 
 ```r
 library(rPID)
-library(infotheo)
 
 z <- rnorm(100)
 x1 <- rnorm(100)
@@ -27,13 +26,79 @@ x2d <- discretize(x2)
 decomposition <- pid(zd, x1d, x2d)
 ```
 
+## Example: Genetic circuits
+
+![Genetic circuit](https://github.molgen.mpg.de/raw/loosolab/rPID/master/construct.png)
+
+Let's assume that the proteins AmtR (green) and SrpR (blue) can form a heterodimer to act on the YFP promoter (red) and drive YFP expression.
+They are connected in a AND gated genetic circuit, which means that either expression of AmtR or SrpR alone does not express YFP.
+
+The corresponding expression truth table looks like this:
+
+| AmtR expression | SrpR expression | YFP expression |
+| --------------- | --------------- | -------------- |
+| low  | low  | low |
+| high  | low  | low |
+| low  | high  | low |
+| high  | high  | high |
+
+Now assume we collected expression data for AmtR, SrpR and YFP from 400 cells, with all expression combinations present in 100 cells, respectively.
+
+```r
+data(circuit_data)
+head(circuit_data)
+```
+
+The correlation values alone do lead to the association of YFP with AmtR or SrpR:
+
+```r
+cor(circuit_data$YFP, circuit_data$AmtR, method="pearson")
+# [1] 0.3688194
+cor(circuit_data$YFP, circuit_data$SrpR, method="pearson")
+# [1] 0.3539511
+```
+
+However, using partial information decomposition, we can explore three way interactions and quantify unique, synergistic and redundant information between the target varibal (`z = YFP`) and the set of two source variables (`x1 = AmtR, x2 = SrpR`):
+
+```r
+# Use discretized expression data
+data(circuit_data_discrete)
+
+pid(z = circuit_data_discrete$YFP, x1 = circuit_data_discrete$AmtR, x2 = circuit_data_discrete$SrpR)
+# $unique_x1
+# [1] 0.0370862
+# 
+# $unique_x2
+# [1] 0.0368186
+# 
+# $synergy
+# [1] 0.597708
+# 
+# $redundancy
+# [1] 0.3251131
+```
+
+The very high value of synergy hints that only both source variables together are able to provide full information about the target variable.
+Please feel free to explore other combinations of source and target variables:
+
+```r
+# No unique or synergistic information, total redundancy:
+pid(z = circuit_data_discrete$YFP, x1 = circuit_data_discrete$AmtR, x2 = circuit_data_discrete$AmtR)
+
+# No synergistic information, most of the information is unique to x1:
+pid(z = circuit_data_discrete$YFP, x1 = circuit_data_discrete$YFP, x2 = circuit_data_discrete$SrpR)
+
+# High synergistic information and unique information from x2:
+pid(z = circuit_data_discrete$SrpR, x1 = circuit_data_discrete$AmtR, x2 = circuit_data_discrete$YFP)
+```
+
 ## Installation and prerequisites
 
 To install the package, use:
 
 ```r
 library(devtools)
-install.packages("infotheo")
+install.packages("entropy")
 install_github("loosolab/rPID", host="github.molgen.mpg.de")
 ```