---
title: "How to use codalm"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{How to use codalm}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

We will start by loading the `codalm` R package, in addition to the `future` and `future.apply` packages,
which we will use for bootstrapping.

```{r setup}
library(codalm)
require('future')
require('future.apply')
```

We will be analyzing how the percentages of mothers and fathers with low, medium, and high education levels relate to each other, across 31 countries in Europe. The format that we need is for both compositions to be in matrices, with one row per observation. We will also normalize the rows of these matrices to ensure that they sum to 1, although the `codalm` function would also take care of this for us.

```{r load_data}
data("educFM")
father <- as.matrix(educFM[,2:4])
father <- father / rowSums(father)
mother <- as.matrix(educFM[,5:7] )
mother <- mother/rowSums(mother)
```

To estimate the coefficient matrix B, we can use the `codalm` function.

```{r estimate_B}
B_est <- codalm(y = father, x = mother)
B_est
```

To see the interpretation of this matrix, please see [Fiksel et al. (2021)](https://onlinelibrary.wiley.com/doi/full/10.1111/biom.13465). If all the rows of B_est are exactly the same, it is recommended to set `accelerate = FALSE` as a sensitivity check.

We can also use the bootstrap to estimate 95% confidence intervals. We will
only use 50 bootstrap iterations as an example (nboot = 50), but is recommended to do more.

```{r bootstrap}
B_ci <- codalm_ci(y = father, x = mother, nboot = 50,
                   conf = .95)
B_ci$ci_L
B_ci$ci_U
```

These matrices given the lower and upper bounds for the confidence interval for each
element of the coefficient matrix.

You can also take advantage of parallelization, if you have multiple cores available.

```{r bootstrap_parallel}
ncores <- 2
B_ci_parallel <- codalm_ci(y = father, x = mother, nboot = 50,
                   conf = .95, parallel = TRUE, ncpus = ncores, strategy = 'multisession')
identical(B_ci$ci_L, B_ci_parallel$ci_L)
identical(B_ci$ci_U, B_ci_parallel$ci_U)
```

Finally, we will do a permutation test for linear independence. Again, we will only do 50
permutations as an example, but in practice this number should be higher. For demonstration purposes,
we will generate the compositional outcome independently of the  compositional predictor

```{r independence_test}
set.seed(123)
x <- gtools::rdirichlet(100, rep(1, 3))
y <- gtools::rdirichlet(100, rep(1, 3))
indep_test_pval <- codalm_indep_test(y = y, x = x,
                                     nperms = 100, init.seed = 123)
indep_test_pval
```

This function can also be parallelized. Unlike the bootstrapping, there is no need
to differentiate between whether the user is using a Windows or Unix system.

```{r independence_test_parallel}
indep_test_pval_parallel <- codalm_indep_test(y = y, x = x,
                                              nperms = 100, init.seed = 123,
                                              parallel = TRUE, ncpus = ncores,
                                              strategy = 'multisession')
indep_test_pval_parallel
```