First version of vignette based on examples rom Kling et al. (2021)

vignettes/.gitignore

@@ -0,0 +1,2 @@
+*.html
+*.R

vignettes/Examples.Rmd

@@ -0,0 +1,176 @@
+---
+title: "Examples"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Examples}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>",
+  dpi = 4*72
+)
+```
+
+Some examples are discussed based on the following data from
+Kling et al (2021): `KETPch4`, `KETPex481`, `KETPex497`, and `KETPex497`.
+All references are to the mentioned book. All examples, except the one based on `KETPex497`, have in common that there are multiple missing families and therefore a joint approach is particularly well suited.
+We assume equal mutation rates females and males for all markers
+in all examples involving mutation. 
+
+```{r setup, echo = F}
+library(dvir, quietly = T)
+```
+
+
+## Example 4.8.1 (data: KETPex481)
+A summary of the data is provided by
+```{r}
+KETPex481
+```
+
+The problem is shown in the figure below:
+```{r, fig.height = 4, fig.width = 6.5, out.width = "85%"}
+#| fig.cap = "Example 4.8.1, Figure 4.13."
+plotDVI(KETPex481)
+```
+In this case there are 21 markers, but mutations are not modelled.
+From
+```{r}
+exclusionMatrix(KETPex481)
+```
+we see that it is reasonable to exclude V2 as being MP1.
+The pairwise LR approach, similar to what is implemented in e.g., Familias, does not give a clear conclusion:
+```{r}
+pairwiseLR(KETPex481)$LRmatrix
+```
+However,  a convincing solution emerges from the joint approach
+```{r}
+res2 = jointDVI(KETPex481, verbose = F)
+res2
+```
+The solution can be plotted as follows
+```{r, fig.height = 4, fig.width = 4, out.width = "50%", fig.cap = " Solution of joint approach in Example 2."}
+plotSolution(KETPex481, res2)
+```
+The posterior pairing and non-pairing probabilities are 
+```{r}
+Bmarginal(res2, missing = KETPex481$missing)
+```
+
+
+## Example 4.8.4 (data: KETPch4 )
+
+This example considers several reference families, see below figure. There are 21 markers and we use an equal mutation model with mutation rate 0.005. 
+Here's a summary of the data:
+```{r}
+KETPch4
+```
+and here's the plot describing the problem:
+```{r fig1, fig.height = 3, fig.width = 7, out.width = "100%"}
+#| fig.cap = "Example 4.8.4, Figure 4.15, with genotypes for the two first markers."
+plotDVI(KETPch4, nrowPM = 2, marker = 1:2)
+```
+There are 49 possible solutions as we find from
+`ncomb(2,2,2,2)` = `r ncomb(2,2,2,2)`.
+
+
+The pairwise LR approach gives
+```{r}
+pairwiseLR(KETPch4)$LRmatrix
+```
+There is some, albeit not strong, indication that (V1 = MP1, V2 = MP2, V3 = MP3, V4 = MP4). However,  a convincing solution emerges from the joint approach
+```{r}
+res1 = jointDVI(KETPch4, disableMutation = F, verbose = F)
+res1[1:3,]
+```
+The solution can be plotted as follows
+```{r, fig.height = 3, fig.width = 7, out.width = "100%"}
+#| fig.cap = "Figure 2. Solution of joint approach in Example 1."
+plotSolution(KETPch4, res1)
+```
+
+We can also compute posterior pairing and non-pairing probabilities
+```{r}
+Bmarginal(res1, KETPch4$missing)
+```
+
+
+## Exercise 4.9.7 (data: KETPex497)
+
+Here's the summary of the data:
+```{r}
+KETPex497
+```
+
+
+The problem is shown in the figure below:
+```{r, fig.height = 3, fig.width = 7, out.width = "100%", fig.cap = "Exercise 4.9.7, Figure 4.22."}
+plotDVI(KETPex497, nrowPM = 3,   cex = 1.1)
+```
+There are 23 markers, and an equal mutation model with rate 0.001.
+Part (a) of the exercise asks for a list of possible assignments. 
+There are `ncomb(3, 3, 0, 0)` = `r ncomb(3, 3, 0, 0)` assignments.
+
+The list of assignments (not shown) can be generated by
+```{r, eval = F}
+lst = generatePairings(KETPex497)
+expand.grid.nodup(lst)
+```
+Then, the joint solution is required
+```{r}
+res3 = jointDVI(KETPex497, disableMutations = FALSE,  verbose = F)
+res3
+```
+
+The solution can be plotted as follows
+```{r, fig.height = 3, fig.width = 6.5, out.width = "100%"}
+#| fig.cap = "Solution of joint approach in Exercise497."
+plotSolution(KETPex497, res3)
+```
+
+## Exercise 4.9.8 (data: KETPex498)
+
+Data from Exercise 4.9.8 is exemplified . There are 2 female victims and 1 male. There is one reference family with 2 missing females and one missing male. There are 16 markers, equal mutation model, rate 0.001.
+
+```{r fig498, fig.height = 4, fig.width = 7, out.width = "90%"}
+#| fig.cap = "Example 4.9.8, with genotypes for the two first markers."
+plotDVI(KETPex498, nrowPM = 3)
+```
+
+The result of a pairwise search is again not conclusive
+```{r}
+pairwiseLR(KETPex498)$LRmatrix
+```
+whereas a joint search is convincing
+```{r}
+res = jointDVI(KETPex498, verbose = F)
+res
+```
+Here's the solution plot
+```{r, fig.height = 3, fig.width = 4.5, out.width = "60%"} 
+#| fig.cap = "Solution of joint approach in Exercise498."
+plotSolution(KETPex498, res)
+```
+
+Genotype data is simulated N = 100 times for the missing, transferred to the victims, and the fraction of times the assignment from which the simulation was generated
+is found to be 0.93.
+```{r, eval = F}
+set.seed(1729)
+N = 100
+missing = KETPex497$missing
+am = forrel::profileSim(KETPex497$am, N = N, ids = missing)
+
+res = lapply(am, function(x){
+  KETPex497$pm = transferMarkers(x, KETPex497$pm, 
+                                 idsFrom = missing, 
+                                 idsTo = c("V1", "V2", "V3"))
+  jointDVI(KETPex497, verbose = FALSE)
+})
+
+correct = sapply(res, function(x) all(x[1, 1:3] == missing))
+mean(correct)
+```