From 01c24e724013bb3c1131377e2fa82d3ded791099 Mon Sep 17 00:00:00 2001
From: Giulio Benedetti <giuliobene2000@gmail.com>
Date: Thu, 16 Jan 2025 13:51:46 +0200
Subject: [PATCH 01/11] Initialise mediation chapter

---
 inst/assets/_book.yml    |   1 +
 inst/pages/mediation.qmd | 162 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 163 insertions(+)
 create mode 100644 inst/pages/mediation.qmd

diff --git a/inst/assets/_book.yml b/inst/assets/_book.yml
index f86ffd39..f1758864 100644
--- a/inst/assets/_book.yml
+++ b/inst/assets/_book.yml
@@ -50,6 +50,7 @@ book:
       chapters:
         - pages/differential_abundance.qmd
         - pages/correlation.qmd
+        - pages/mediation.qmd
     - part: "Networks"
       chapters:
         - pages/network_learning.qmd
diff --git a/inst/pages/mediation.qmd b/inst/pages/mediation.qmd
new file mode 100644
index 00000000..30d7749f
--- /dev/null
+++ b/inst/pages/mediation.qmd
@@ -0,0 +1,162 @@
+# Mediation {#sec-mediation}
+
+what is the goal of mediation analysis?
+
+```{r}
+library(mia)
+library(scater)
+
+# Load dataset
+data(hitchip1006, package = "miaTime")
+tse <- hitchip1006
+```
+
+```{r}
+# Agglomerate features by family (merely to speed up execution)
+tse <- agglomerateByRank(tse, rank = "Phylum")
+# Convert BMI variable to numeric
+tse$bmi_group <- as.numeric(tse$bmi_group)
+```
+
+## Feature mediation
+
+```{r}
+# Analyse mediated effect of nationality on BMI via alpha diversity
+# 100 permutations were done to speed up execution, but ~1000 are recommended 
+med_df <- getMediation(tse,
+                       outcome = "bmi_group",
+                       treatment = "nationality",
+                       mediator = "diversity",
+                       covariates = c("sex", "age"),
+                       treat.value = "Scandinavia",
+                       control.value = "CentralEurope",
+                       boot = TRUE, sims = 100,
+                       add.metadata = TRUE)
+ 
+# Visualise model statistics for 1st mediator
+plot(attr(med_df, "metadata")[[1]])
+```
+
+what is the meaning of ACME, ADE and total effect?
+
+## Assay mediation
+
+```{r}
+# Apply clr transformation to counts assay
+tse <- transformAssay(tse,
+                      method = "clr",
+                      pseudocount = 1)
+
+# Analyse mediated effect of nationality on BMI via clr-transformed features
+# 100 permutations were done to speed up execution, but ~1000 are recommended     
+tse <- addMediation(tse, name = "assay_mediation",
+                    outcome = "bmi_group",
+                    treatment = "nationality",
+                    assay.type = "clr",
+                    covariates = c("sex", "age"),
+                    treat.value = "Scandinavia",
+                    control.value = "CentralEurope",
+                    boot = TRUE, sims = 100,
+                    p.adj.method = "fdr")
+
+# Show results for first 5 mediators
+head(metadata(tse)$assay_mediation, 5)
+```
+
+```{r}
+my_df <- metadata(tse)$assay_mediation
+
+coef_mat <-  as.matrix(my_df[ , c("ACME_estimate", "ADE_estimate")])
+p_mat <-  as.matrix(my_df[ , c("ACME_pval", "ADE_pval")])
+
+rownames(coef_mat) <- my_df[["Mediator"]]
+colnames(coef_mat) <- gsub("_estimate", "", colnames(coef_mat))
+
+p_mat <- t(p_mat)
+
+Heatmap(t(coef_mat),
+        name = "Effect",
+        cluster_rows = FALSE,
+        cluster_columns = FALSE,
+        row_names_side = "left",
+        column_names_rot = 45,
+        rect_gp = gpar(col = "white", lwd = 2),
+        cell_fun = function(j, i, x, y, w, h, fill) {
+          if(p_mat[i, j] < 0.001) {
+            grid.text("***", x, y)
+          } else if(p_mat[i, j] < 0.01) {
+            grid.text("**", x, y)
+          } else if(p_mat[i, j] < 0.05) {
+            grid.text("*", x, y)
+          }
+        })
+```
+
+
+## Mediation of reduced dimensions
+
+```{r}
+# Perform ordination
+tse <- runMDS(tse, name = "MDS",
+              method = "euclidean",
+              assay.type = "clr",
+              ncomponents = 5)
+
+# Analyse mediated effect of nationality on BMI via MDS components 
+# 100 permutations were done to speed up execution, but ~1000 are recommended       
+tse <- addMediation(tse, name = "reddim_mediation",
+                    outcome = "bmi_group",
+                    treatment = "nationality",
+                    dimred = "MDS",
+                    covariates = c("sex", "age"),
+                    treat.value = "Scandinavia",
+                    control.value = "CentralEurope",
+                    boot = TRUE, sims = 100,
+                    p.adj.method = "fdr")
+
+# Show results for first 5 mediators
+head(metadata(tse)$reddim_mediation, 5)
+```
+```{r}
+my_df <- metadata(tse)$reddim_mediation
+
+coef_mat <-  as.matrix(my_df[ , c("ACME_estimate", "ADE_estimate")])
+p_mat <-  as.matrix(my_df[ , c("ACME_pval", "ADE_pval")])
+
+rownames(coef_mat) <- my_df[["Mediator"]]
+colnames(coef_mat) <- gsub("_estimate", "", colnames(coef_mat))
+
+p_mat <- t(p_mat)
+
+Heatmap(t(coef_mat),
+        name = "Effect",
+        cluster_rows = FALSE,
+        cluster_columns = FALSE,
+        row_names_side = "left",
+        column_names_rot = 45,
+        rect_gp = gpar(col = "white", lwd = 2),
+        cell_fun = function(j, i, x, y, w, h, fill) {
+          if(p_mat[i, j] < 0.001) {
+            grid.text("***", x, y)
+          } else if(p_mat[i, j] < 0.01) {
+            grid.text("**", x, y)
+          } else if(p_mat[i, j] < 0.05) {
+            grid.text("*", x, y)
+          }
+        })
+```
+
+```{r}
+reddim_mediation <- attr(metadata(tse)$reddim_mediation, "metadata")
+
+plots <- lapply(reddim_mediation, plot)
+
+#entries <- c("d.avg", "d.avg.p", "z.avg", "z.avg.p", "tau.coef", "tau.p")
+
+#my_ls <- lapply(reddim_mediation, function(x) x[names(x) %in% entries])
+
+#my_df <- data.frame(do.call(rbind, my_ls))
+
+
+```
+

From 834b01132d1edb534ece8d04b0d5a6143378b098 Mon Sep 17 00:00:00 2001
From: Giulio Benedetti <giuliobene2000@gmail.com>
Date: Fri, 7 Feb 2025 22:20:53 +0200
Subject: [PATCH 02/11] Start writing text in mediation chapter

---
 inst/pages/mediation.qmd | 126 +++++++++++++++------------------------
 1 file changed, 47 insertions(+), 79 deletions(-)

diff --git a/inst/pages/mediation.qmd b/inst/pages/mediation.qmd
index 30d7749f..f9d895db 100644
--- a/inst/pages/mediation.qmd
+++ b/inst/pages/mediation.qmd
@@ -1,10 +1,37 @@
 # Mediation {#sec-mediation}
 
-what is the goal of mediation analysis?
+```{r setup, echo=FALSE, results="asis"}
+library(rebook)
+chapterPreamble()
+```
+
+Mediation analysis is used to study the effect of an independent variable (X) on
+the outcome variable (Y) through a third variable, known as mediator (M). Mathematically, this relationship is described as follows:
+
+Y ~ X * M
+
+The significance of a mediator is typically quantified in terms of the mediated
+effect, that is, the portion of the association between X and Y that can be
+explained through M. This corresponds to the difference between the total effect
+and the direct effect and is called Average Causal Mediated Effect (ACME):
+
+ACME = Total Effect - Average Direct Effect
+
+Put nice illustration of mediation, use a DAG.
+
+The microbiome has the potential to mediate the effects of multiple environmental
+stimuli on human health. For example, the impact of antibiotics on humour largely
+depends on microbiome depletion. In this case, we talk about complete mediation.
+On the other hand, diet affects the organism directly via nutrition and
+metabolism, but in part also delivered through the microbiome. In this case, we
+talk about partial mediation.
+
+We demonstrate a basic mediation analysis and visualisation with the hitchip1006
+dataset from miaTime package.
 
 ```{r}
 library(mia)
-library(scater)
+library(miaViz)
 
 # Load dataset
 data(hitchip1006, package = "miaTime")
@@ -12,10 +39,16 @@ tse <- hitchip1006
 ```
 
 ```{r}
-# Agglomerate features by family (merely to speed up execution)
-tse <- agglomerateByRank(tse, rank = "Phylum")
 # Convert BMI variable to numeric
 tse$bmi_group <- as.numeric(tse$bmi_group)
+
+# Agglomerate features by family (merely to speed up execution)
+tse <- agglomerateByRank(tse, rank = "Phylum")
+
+# Apply clr transformation to counts assay
+tse <- transformAssay(tse,
+                      method = "clr",
+                      pseudocount = 1)
 ```
 
 ## Feature mediation
@@ -30,11 +63,10 @@ med_df <- getMediation(tse,
                        covariates = c("sex", "age"),
                        treat.value = "Scandinavia",
                        control.value = "CentralEurope",
-                       boot = TRUE, sims = 100,
-                       add.metadata = TRUE)
+                       boot = TRUE, sims = 100)
  
 # Visualise model statistics for 1st mediator
-plot(attr(med_df, "metadata")[[1]])
+plotMediation(med_df, layout = "forest")
 ```
 
 what is the meaning of ACME, ADE and total effect?
@@ -42,11 +74,6 @@ what is the meaning of ACME, ADE and total effect?
 ## Assay mediation
 
 ```{r}
-# Apply clr transformation to counts assay
-tse <- transformAssay(tse,
-                      method = "clr",
-                      pseudocount = 1)
-
 # Analyse mediated effect of nationality on BMI via clr-transformed features
 # 100 permutations were done to speed up execution, but ~1000 are recommended     
 tse <- addMediation(tse, name = "assay_mediation",
@@ -64,32 +91,7 @@ head(metadata(tse)$assay_mediation, 5)
 ```
 
 ```{r}
-my_df <- metadata(tse)$assay_mediation
-
-coef_mat <-  as.matrix(my_df[ , c("ACME_estimate", "ADE_estimate")])
-p_mat <-  as.matrix(my_df[ , c("ACME_pval", "ADE_pval")])
-
-rownames(coef_mat) <- my_df[["Mediator"]]
-colnames(coef_mat) <- gsub("_estimate", "", colnames(coef_mat))
-
-p_mat <- t(p_mat)
-
-Heatmap(t(coef_mat),
-        name = "Effect",
-        cluster_rows = FALSE,
-        cluster_columns = FALSE,
-        row_names_side = "left",
-        column_names_rot = 45,
-        rect_gp = gpar(col = "white", lwd = 2),
-        cell_fun = function(j, i, x, y, w, h, fill) {
-          if(p_mat[i, j] < 0.001) {
-            grid.text("***", x, y)
-          } else if(p_mat[i, j] < 0.01) {
-            grid.text("**", x, y)
-          } else if(p_mat[i, j] < 0.05) {
-            grid.text("*", x, y)
-          }
-        })
+plotMediation(tse, "assay_mediation", layout = "heatmap")
 ```
 
 
@@ -97,17 +99,16 @@ Heatmap(t(coef_mat),
 
 ```{r}
 # Perform ordination
-tse <- runMDS(tse, name = "MDS",
-              method = "euclidean",
+tse <- runPCA(tse, name = "PCA",
               assay.type = "clr",
-              ncomponents = 5)
+              ncomponents = 3)
 
 # Analyse mediated effect of nationality on BMI via MDS components 
 # 100 permutations were done to speed up execution, but ~1000 are recommended       
 tse <- addMediation(tse, name = "reddim_mediation",
                     outcome = "bmi_group",
                     treatment = "nationality",
-                    dimred = "MDS",
+                    dimred = "PCA",
                     covariates = c("sex", "age"),
                     treat.value = "Scandinavia",
                     control.value = "CentralEurope",
@@ -117,46 +118,13 @@ tse <- addMediation(tse, name = "reddim_mediation",
 # Show results for first 5 mediators
 head(metadata(tse)$reddim_mediation, 5)
 ```
-```{r}
-my_df <- metadata(tse)$reddim_mediation
-
-coef_mat <-  as.matrix(my_df[ , c("ACME_estimate", "ADE_estimate")])
-p_mat <-  as.matrix(my_df[ , c("ACME_pval", "ADE_pval")])
-
-rownames(coef_mat) <- my_df[["Mediator"]]
-colnames(coef_mat) <- gsub("_estimate", "", colnames(coef_mat))
-
-p_mat <- t(p_mat)
-
-Heatmap(t(coef_mat),
-        name = "Effect",
-        cluster_rows = FALSE,
-        cluster_columns = FALSE,
-        row_names_side = "left",
-        column_names_rot = 45,
-        rect_gp = gpar(col = "white", lwd = 2),
-        cell_fun = function(j, i, x, y, w, h, fill) {
-          if(p_mat[i, j] < 0.001) {
-            grid.text("***", x, y)
-          } else if(p_mat[i, j] < 0.01) {
-            grid.text("**", x, y)
-          } else if(p_mat[i, j] < 0.05) {
-            grid.text("*", x, y)
-          }
-        })
-```
 
 ```{r}
-reddim_mediation <- attr(metadata(tse)$reddim_mediation, "metadata")
-
-plots <- lapply(reddim_mediation, plot)
-
-#entries <- c("d.avg", "d.avg.p", "z.avg", "z.avg.p", "tau.coef", "tau.p")
-
-#my_ls <- lapply(reddim_mediation, function(x) x[names(x) %in% entries])
-
-#my_df <- data.frame(do.call(rbind, my_ls))
+p1 <- plotMediation(tse, "reddim_mediation", layout = "forest")
+p2 <- plotLoadings(tse, "PCA", ncomponents = 3, n = 8, layout = "heatmap")
 
+library(patchwork)
 
+p1 / p2
 ```
 

From a80be6b49aa9b0ab5e685567033d30affdfe8bdd Mon Sep 17 00:00:00 2001
From: Giulio Benedetti <giuliobene2000@gmail.com>
Date: Sat, 8 Feb 2025 14:21:00 +0200
Subject: [PATCH 03/11] Finalise draft of mediation chapter

---
 inst/assets/bibliography.bib |  40 ++++++++++
 inst/pages/mediation.qmd     | 146 ++++++++++++++++++++++++++++-------
 2 files changed, 159 insertions(+), 27 deletions(-)

diff --git a/inst/assets/bibliography.bib b/inst/assets/bibliography.bib
index 62b1b07a..92782e58 100644
--- a/inst/assets/bibliography.bib
+++ b/inst/assets/bibliography.bib
@@ -2321,3 +2321,43 @@ @article{mangiola2023
     eprint = {https://www.pnas.org/doi/pdf/10.1073/pnas.2203828120},
     }
 
+@Article{Tingley2014mediation,
+    title = {{mediation}: {R} Package for Causal Mediation Analysis},
+    author = {Dustin Tingley and Teppei Yamamoto and Kentaro Hirose and Luke Keele and Kosuke Imai},
+    journal = {Journal of Statistical Software},
+    year = {2014},
+    volume = {59},
+    number = {5},
+    pages = {1--38},
+    url = {http://www.jstatsoft.org/v59/i05/},
+  }
+
+@article{Xia2021mediation,
+  title={Mediation Analysis of Microbiome Data and Detection of Causality in Microbiome Studies},
+  author={Xia, Yinglin},
+  journal={Inflammation, Infection, and Microbiome in Cancers: Evidence, Mechanisms, and Implications},
+  pages={457--509},
+  year={2021},
+  publisher={Springer}
+}
+
+@article{Dinan2022antibiotics,
+  title={Antibiotics and mental health: The good, the bad and the ugly},
+  author={Dinan, Katherine and Dinan, Timothy},
+  journal={Journal of Internal Medicine},
+  volume={292},
+  number={6},
+  pages={858--869},
+  year={2022},
+  publisher={Wiley Online Library}
+}
+
+@article{Logan2014nutritional,
+  title={Nutritional psychiatry research: an emerging discipline and its intersection with global urbanization, environmental challenges and the evolutionary mismatch},
+  author={Logan, Alan C and Jacka, Felice N},
+  journal={Journal of Physiological Anthropology},
+  volume={33},
+  pages={1--16},
+  year={2014},
+  publisher={Springer}
+}
\ No newline at end of file
diff --git a/inst/pages/mediation.qmd b/inst/pages/mediation.qmd
index f9d895db..dc36e628 100644
--- a/inst/pages/mediation.qmd
+++ b/inst/pages/mediation.qmd
@@ -6,43 +6,64 @@ chapterPreamble()
 ```
 
 Mediation analysis is used to study the effect of an independent variable (X) on
-the outcome variable (Y) through a third variable, known as mediator (M). Mathematically, this relationship is described as follows:
+the outcome (Y) through a third factor, known as mediator (M). Mathematically,
+this relationship can be described as follows:
 
-Y ~ X * M
+$$
+Y \thicksim X * M
+$$
 
-The significance of a mediator is typically quantified in terms of the mediated
-effect, that is, the portion of the association between X and Y that can be
-explained through M. This corresponds to the difference between the total effect
-and the direct effect and is called Average Causal Mediated Effect (ACME):
+The contribution of a mediator is typically quantified in terms of Average
+Causal Mediated Effect (ACME), that is, the portion of the association between X
+and Y that is explained by M. In practice, this corresponds to the difference
+between the Total Effect (TE) and the Average Direct Effect (ADE):
 
-ACME = Total Effect - Average Direct Effect
+$$
+ACME = TE - ADE
+$$
 
-Put nice illustration of mediation, use a DAG.
+The microbiome can mediate the effects of multiple environmental stimuli on
+human health. However, the importance of its role as a mediator depends on the
+nature of the stimulus. For example, the effect of dietary fiber intake on host behaviour is largely mediated by the gut microbiome [@Logan2014nutritional]. On
+the other hand, the indirect impact of antibiotic use on mental health through
+an altered microbiome represents a more subtle phenomenon [@Dinan2022antibiotics].
 
-The microbiome has the potential to mediate the effects of multiple environmental
-stimuli on human health. For example, the impact of antibiotics on humour largely
-depends on microbiome depletion. In this case, we talk about complete mediation.
-On the other hand, diet affects the organism directly via nutrition and
-metabolism, but in part also delivered through the microbiome. In this case, we
-talk about partial mediation.
+In general, the wide range of mediation effects can be divided into two classes:
+- complete mediation, where the mediator conveys the full effect of the the
+  treatment variable on the outcome
+- partial mediation, where the mediator only assists the treatment variable in
+  conveying the effect on the outcome
 
-We demonstrate a basic mediation analysis and visualisation with the hitchip1006
-dataset from miaTime package.
+Put nice illustration of mediation as a DAG.
+
+We demonstrate a standard mediation analysis with the `hitchip1006` dataset
+from the `miaTime` package, which contains a genus-level assay for 1006 western
+adults of 6 different nationalities.
 
 ```{r}
+#| label: mediation1
+#| message: false
+# Import libraries
 library(mia)
 library(miaViz)
+library(scater)
+library(patchwork)
 
 # Load dataset
 data(hitchip1006, package = "miaTime")
 tse <- hitchip1006
 ```
 
+In our analyses, nationality and BMI group will represent the independent (X)
+and outcome (Y) variables, respectively. We make the broad assumption that
+nationality reflects differences in the living environment between subjects.
+
 ```{r}
+#| label: mediation2
 # Convert BMI variable to numeric
 tse$bmi_group <- as.numeric(tse$bmi_group)
 
-# Agglomerate features by family (merely to speed up execution)
+# Agglomerate features by phylum
 tse <- agglomerateByRank(tse, rank = "Phylum")
 
 # Apply clr transformation to counts assay
@@ -51,14 +72,29 @@ tse <- transformAssay(tse,
                       pseudocount = 1)
 ```
 
-## Feature mediation
+In the following examples, the effect of living environment on BMI mediated
+by the microbiome is investigated in 3 different steps:
+
+1. global contribution by alpha diversity
+2. individual contributions by assay features
+3. combined contributions by reduced dimensions
+
+## Alpha diversity as mediator
+
+First, we ask whether alpha diversity mediates the effect of living environment
+on BMI. Using the `getMediation` function, the variables X, Y and M are
+specified with the arguments `treatment`, `outcome` and `mediator`, respectively.
+We control for sex and age and limit comparisons to two nationality groups,
+Central Europeans (control) vs. Scandinavians (treatment).
 
 ```{r}
+#| label: mediation3
+#| message: false
 # Analyse mediated effect of nationality on BMI via alpha diversity
 # 100 permutations were done to speed up execution, but ~1000 are recommended 
 med_df <- getMediation(tse,
-                       outcome = "bmi_group",
                        treatment = "nationality",
+                       outcome = "bmi_group",
                        mediator = "diversity",
                        covariates = c("sex", "age"),
                        treat.value = "Scandinavia",
@@ -69,11 +105,21 @@ med_df <- getMediation(tse,
 plotMediation(med_df, layout = "forest")
 ```
 
-what is the meaning of ACME, ADE and total effect?
+The forest plot above shows significance for both ACME and ADE, which suggests
+that alpha diversity is a partial mediator of living environment on BMI. In
+contrast, if ACME but not ADE were significant, complete mediation would be
+inferred.
 
-## Assay mediation
+## Assay features as mediators
+
+If we suspect that only certain features of the microbiome act as mediators,
+we can estimate their individual contributions by fitting one model for each
+feature in a selected assay. As multiple tests are performed, it is good
+practice to correct the significance of the findings with a method of choice.
 
 ```{r}
+#| label: mediation4
+#| message: false
 # Analyse mediated effect of nationality on BMI via clr-transformed features
 # 100 permutations were done to speed up execution, but ~1000 are recommended     
 tse <- addMediation(tse, name = "assay_mediation",
@@ -87,17 +133,39 @@ tse <- addMediation(tse, name = "assay_mediation",
                     p.adj.method = "fdr")
 
 # Show results for first 5 mediators
-head(metadata(tse)$assay_mediation, 5)
+knitr::kable(metadata(tse)$assay_mediation)
 ```
 
+For convenience, results can be visualized with a heatmap, where rows represent
+features and columns correspond to the coefficients for TE, ADE and ACME.
+Significant findings can be marked with p-values or stars.
+
 ```{r}
-plotMediation(tse, "assay_mediation", layout = "heatmap")
+#| label: mediation5
+plotMediation(tse, "assay_mediation", layout = "heatmap",
+              add.significance = "symbol")
 ```
 
+Results suggest that only four out of eight features (Bacteroidetes, Firmicutes,
+Proteobacteria and Verrucomicrobia) partially mediate the effect of living
+environment on BMI.
+
+While analyses were conducted at the phylum level to simplify results, using
+original assays without agglomeration also represents a valid option. However,
+the increase in phylogenetic resolution also implies a higher probability of
+spurious findings, which in turn necessitates a stronger correction for multiple
+comparisons. A solution to this issue is proposed in the following section.
+
+## Reduced dimensions as mediators
 
-## Mediation of reduced dimensions
+Performing mediation analysis for each feature provides insight into individual
+contributions. However, this approach greatly increases the number of drawn comparisons and thus it reduces statistical power. To overcome this issue, it is
+possible to assess the combined contributions of subset of features by means of
+dimensionality reduction.
 
 ```{r}
+#| label: mediation6
+#| message: false
 # Perform ordination
 tse <- runPCA(tse, name = "PCA",
               assay.type = "clr",
@@ -116,15 +184,39 @@ tse <- addMediation(tse, name = "reddim_mediation",
                     p.adj.method = "fdr")
 
 # Show results for first 5 mediators
-head(metadata(tse)$reddim_mediation, 5)
+knitr::kable(metadata(tse)$reddim_mediation)
 ```
 
+Results can be displayed as one forest plot for each reduced dimension. When
+combined with a heatmap of the feature loadings for each dimension, we can
+deduce whether certain groups of features act as mediators.
+
 ```{r}
+#| label: mediation7
 p1 <- plotMediation(tse, "reddim_mediation", layout = "forest")
 p2 <- plotLoadings(tse, "PCA", ncomponents = 3, n = 8, layout = "heatmap")
 
-library(patchwork)
-
 p1 / p2
 ```
 
+The plot above suggests that only PC1 partially mediates the effect of living
+environment on BMI. Within this dimension, Bacteroidetes and Actinobacteria are
+the largest contributors.
+
+## Final remarks
+
+This chapter introduced the concept of mediation and demonstrated a standard
+analysis of the microbiome as mediator at 3 different levels (global, individual
+and combined contributions). Importantly, the provided method is based on the `mediation` package and is limited to univariate comparisons and binary
+treatment conditions [@Tingley2014mediation]. Therefore, it is recommended to
+reduce the number of mediators under study by means of a knowledge-based
+strategy to preserve statistical power.
+
+A few methods for multivariate mediation analysis of high-dimensional omic
+data also exist [@Xia2021mediation]. However, no one solution has emerged to
+become the golden standard in microbiome data analysis, mainly because the
+available approaches can only partially accommodate for the specific properties
+of microbiome data, such as compositionality, sparsity and its hierarchical
+structure. While this chapter proposed a standard approach to mediation analysis,
+in the future fine-tuned solutions for the microbiome may also become common.
+

From 3bcf74b81add80784e6c4151f7e8668d73e258f9 Mon Sep 17 00:00:00 2001
From: Giulio Benedetti <giuliobene2000@gmail.com>
Date: Sun, 9 Feb 2025 09:19:01 +0200
Subject: [PATCH 04/11] Minor fixes

---
 inst/pages/mediation.qmd | 44 +++++++++++++++++++++++-----------------
 1 file changed, 25 insertions(+), 19 deletions(-)

diff --git a/inst/pages/mediation.qmd b/inst/pages/mediation.qmd
index dc36e628..9666bcb3 100644
--- a/inst/pages/mediation.qmd
+++ b/inst/pages/mediation.qmd
@@ -24,7 +24,8 @@ $$
 
 The microbiome can mediate the effects of multiple environmental stimuli on
 human health. However, the importance of its role as a mediator depends on the
-nature of the stimulus. For example, the effect of dietary fiber intake on host behaviour is largely mediated by the gut microbiome [@Logan2014nutritional]. On
+nature of the stimulus. For example, the effect of dietary fiber intake on host
+behaviour is largely mediated by the gut microbiome [@Logan2014nutritional]. On
 the other hand, the indirect impact of antibiotic use on mental health through
 an altered microbiome represents a more subtle phenomenon [@Dinan2022antibiotics].
 
@@ -101,7 +102,7 @@ med_df <- getMediation(tse,
                        control.value = "CentralEurope",
                        boot = TRUE, sims = 100)
  
-# Visualise model statistics for 1st mediator
+# Plot results as a forest plot
 plotMediation(med_df, layout = "forest")
 ```
 
@@ -123,8 +124,8 @@ practice to correct the significance of the findings with a method of choice.
 # Analyse mediated effect of nationality on BMI via clr-transformed features
 # 100 permutations were done to speed up execution, but ~1000 are recommended     
 tse <- addMediation(tse, name = "assay_mediation",
-                    outcome = "bmi_group",
                     treatment = "nationality",
+                    outcome = "bmi_group",
                     assay.type = "clr",
                     covariates = c("sex", "age"),
                     treat.value = "Scandinavia",
@@ -132,7 +133,7 @@ tse <- addMediation(tse, name = "assay_mediation",
                     boot = TRUE, sims = 100,
                     p.adj.method = "fdr")
 
-# Show results for first 5 mediators
+# View results
 knitr::kable(metadata(tse)$assay_mediation)
 ```
 
@@ -142,6 +143,7 @@ Significant findings can be marked with p-values or stars.
 
 ```{r}
 #| label: mediation5
+# Plot results as a heatmap
 plotMediation(tse, "assay_mediation", layout = "heatmap",
               add.significance = "symbol")
 ```
@@ -159,23 +161,24 @@ comparisons. A solution to this issue is proposed in the following section.
 ## Reduced dimensions as mediators
 
 Performing mediation analysis for each feature provides insight into individual
-contributions. However, this approach greatly increases the number of drawn comparisons and thus it reduces statistical power. To overcome this issue, it is
-possible to assess the combined contributions of subset of features by means of
+contributions. However, this approach greatly increases the number of drawn
+comparisons and thus it reduces statistical power. To overcome this issue, it is
+possible to assess the combined contributions of groups of features by means of
 dimensionality reduction.
 
 ```{r}
 #| label: mediation6
 #| message: false
-# Perform ordination
+# Reduce dimensions with PCA
 tse <- runPCA(tse, name = "PCA",
               assay.type = "clr",
               ncomponents = 3)
 
-# Analyse mediated effect of nationality on BMI via MDS components 
+# Analyse mediated effect of nationality on BMI via principal components 
 # 100 permutations were done to speed up execution, but ~1000 are recommended       
 tse <- addMediation(tse, name = "reddim_mediation",
-                    outcome = "bmi_group",
                     treatment = "nationality",
+                    outcome = "bmi_group",
                     dimred = "PCA",
                     covariates = c("sex", "age"),
                     treat.value = "Scandinavia",
@@ -183,19 +186,22 @@ tse <- addMediation(tse, name = "reddim_mediation",
                     boot = TRUE, sims = 100,
                     p.adj.method = "fdr")
 
-# Show results for first 5 mediators
+# View results
 knitr::kable(metadata(tse)$reddim_mediation)
 ```
 
 Results can be displayed as one forest plot for each reduced dimension. When
-combined with a heatmap of the feature loadings for each dimension, we can
-deduce whether certain groups of features act as mediators.
+combined with a heatmap of the feature loadings by dimension, we can deduce
+whether certain groups of features act as mediators.
 
 ```{r}
 #| label: mediation7
+# Plot results as multiple forest plots
 p1 <- plotMediation(tse, "reddim_mediation", layout = "forest")
+# Plot loadings by principal component
 p2 <- plotLoadings(tse, "PCA", ncomponents = 3, n = 8, layout = "heatmap")
 
+# Combine plots
 p1 / p2
 ```
 
@@ -206,17 +212,17 @@ the largest contributors.
 ## Final remarks
 
 This chapter introduced the concept of mediation and demonstrated a standard
-analysis of the microbiome as mediator at 3 different levels (global, individual
-and combined contributions). Importantly, the provided method is based on the `mediation` package and is limited to univariate comparisons and binary
-treatment conditions [@Tingley2014mediation]. Therefore, it is recommended to
-reduce the number of mediators under study by means of a knowledge-based
-strategy to preserve statistical power.
+analysis of the microbiome as mediator at three different levels (global,
+individual and combined contributions). Importantly, the provided method is
+based on the `mediation` package and is limited to univariate comparisons and
+binary conditions for the independent variable [@Tingley2014mediation].
+Therefore, it is recommended to reduce the number of mediators under study by
+means of a knowledge-based strategy to preserve statistical power.
 
 A few methods for multivariate mediation analysis of high-dimensional omic
-data also exist [@Xia2021mediation]. However, no one solution has emerged to
+data also exist [@Xia2021mediation]. However, no one solution has emerged yet to
 become the golden standard in microbiome data analysis, mainly because the
 available approaches can only partially accommodate for the specific properties
 of microbiome data, such as compositionality, sparsity and its hierarchical
 structure. While this chapter proposed a standard approach to mediation analysis,
 in the future fine-tuned solutions for the microbiome may also become common.
-

From 2dc916139d35efd2a30107dbe6570423c764597f Mon Sep 17 00:00:00 2001
From: Giulio Benedetti <giuliobene2000@gmail.com>
Date: Sun, 9 Feb 2025 22:03:54 +0200
Subject: [PATCH 05/11] Implement feedback on mediation chapter

---
 inst/pages/mediation.qmd | 139 +++++++++++++++++++++++++++------------
 1 file changed, 97 insertions(+), 42 deletions(-)

diff --git a/inst/pages/mediation.qmd b/inst/pages/mediation.qmd
index 9666bcb3..1d87fd2f 100644
--- a/inst/pages/mediation.qmd
+++ b/inst/pages/mediation.qmd
@@ -25,17 +25,43 @@ $$
 The microbiome can mediate the effects of multiple environmental stimuli on
 human health. However, the importance of its role as a mediator depends on the
 nature of the stimulus. For example, the effect of dietary fiber intake on host
-behaviour is largely mediated by the gut microbiome [@Logan2014nutritional]. On
-the other hand, the indirect impact of antibiotic use on mental health through
-an altered microbiome represents a more subtle phenomenon [@Dinan2022antibiotics].
+behaviour is largely mediated by the gut microbiome [@Logan2014nutritional]. In
+contrast, the indirect impact of antibiotic use on mental health through an
+altered microbiome represents a more subtle process [@Dinan2022antibiotics].
 
 In general, the wide range of mediation effects can be divided into two classes:
+
 - complete mediation, where the mediator conveys the full effect of the the
   treatment variable on the outcome
 - partial mediation, where the mediator only assists the treatment variable in
   conveying the effect on the outcome
 
-Put nice illustration of mediation as a DAG.
+```{r}
+#| label: fig-mediation
+#| fig-cap: Directed Acyclic Graphs of two possible relationships involving
+#|   mediation. A. The effect of x on y is completely mediated by m. B. The
+#|   effect of x on y is direct, and only a portion is mediated by m.
+#| message: false
+#| echo: false
+
+# Import libraries
+library(ggdag)
+library(ggplot2)
+library(patchwork)
+
+# Plot triangle for complete mediation
+p1 <- ggdag_mediation_triangle(x_y_associated = TRUE, stylized = TRUE) +
+    ggtitle("A: Complete mediation") +
+    theme_dag()
+  
+# Plot triangle for partial mediation
+p2 <- ggdag_mediation_triangle(stylized = TRUE) +
+    ggtitle("B: Partial mediation") +
+    theme_dag()
+
+# Combine plots
+p1 | p2
+```
 
 We demonstrate a standard mediation analysis with the `hitchip1006` dataset
 from the `miaTime` package, which contains a genus-level assay for 1006 western
@@ -44,11 +70,13 @@ adults of 6 different nationalities.
 ```{r}
 #| label: mediation1
 #| message: false
+
 # Import libraries
 library(mia)
 library(miaViz)
 library(scater)
 library(patchwork)
+library(knitr)
 
 # Load dataset
 data(hitchip1006, package = "miaTime")
@@ -61,6 +89,7 @@ nationality reflects differences in the living environment between subjects.
 
 ```{r}
 #| label: mediation2
+
 # Convert BMI variable to numeric
 tse$bmi_group <- as.numeric(tse$bmi_group)
 
@@ -68,9 +97,11 @@ tse$bmi_group <- as.numeric(tse$bmi_group)
 tse <- agglomerateByRank(tse, rank = "Phylum")
 
 # Apply clr transformation to counts assay
-tse <- transformAssay(tse,
-                      method = "clr",
-                      pseudocount = 1)
+tse <- transformAssay(
+    tse,
+    method = "clr",
+    pseudocount = 1
+)
 ```
 
 In the following examples, the effect of living environment on BMI mediated
@@ -91,16 +122,19 @@ Central Europeans (control) vs. Scandinavians (treatment).
 ```{r}
 #| label: mediation3
 #| message: false
+
 # Analyse mediated effect of nationality on BMI via alpha diversity
 # 100 permutations were done to speed up execution, but ~1000 are recommended 
-med_df <- getMediation(tse,
-                       treatment = "nationality",
-                       outcome = "bmi_group",
-                       mediator = "diversity",
-                       covariates = c("sex", "age"),
-                       treat.value = "Scandinavia",
-                       control.value = "CentralEurope",
-                       boot = TRUE, sims = 100)
+med_df <- getMediation(
+    tse,
+    treatment = "nationality",
+    outcome = "bmi_group",
+    mediator = "diversity",
+    covariates = c("sex", "age"),
+    treat.value = "Scandinavia",
+    control.value = "CentralEurope",
+    boot = TRUE, sims = 100
+)
  
 # Plot results as a forest plot
 plotMediation(med_df, layout = "forest")
@@ -121,20 +155,23 @@ practice to correct the significance of the findings with a method of choice.
 ```{r}
 #| label: mediation4
 #| message: false
+
 # Analyse mediated effect of nationality on BMI via clr-transformed features
 # 100 permutations were done to speed up execution, but ~1000 are recommended     
-tse <- addMediation(tse, name = "assay_mediation",
-                    treatment = "nationality",
-                    outcome = "bmi_group",
-                    assay.type = "clr",
-                    covariates = c("sex", "age"),
-                    treat.value = "Scandinavia",
-                    control.value = "CentralEurope",
-                    boot = TRUE, sims = 100,
-                    p.adj.method = "fdr")
+tse <- addMediation(
+    tse, name = "assay_mediation",
+    treatment = "nationality",
+    outcome = "bmi_group",
+    assay.type = "clr",
+    covariates = c("sex", "age"),
+    treat.value = "Scandinavia",
+    control.value = "CentralEurope",
+    boot = TRUE, sims = 100,
+    p.adj.method = "fdr"
+)
 
 # View results
-knitr::kable(metadata(tse)$assay_mediation)
+kable(metadata(tse)$assay_mediation)
 ```
 
 For convenience, results can be visualized with a heatmap, where rows represent
@@ -143,9 +180,13 @@ Significant findings can be marked with p-values or stars.
 
 ```{r}
 #| label: mediation5
+
 # Plot results as a heatmap
-plotMediation(tse, "assay_mediation", layout = "heatmap",
-              add.significance = "symbol")
+plotMediation(
+    tse, "assay_mediation",
+    layout = "heatmap",
+    add.significance = "symbol"
+)
 ```
 
 Results suggest that only four out of eight features (Bacteroidetes, Firmicutes,
@@ -169,25 +210,30 @@ dimensionality reduction.
 ```{r}
 #| label: mediation6
 #| message: false
+
 # Reduce dimensions with PCA
-tse <- runPCA(tse, name = "PCA",
-              assay.type = "clr",
-              ncomponents = 3)
+tse <- runPCA(
+    tse, name = "PCA",
+    assay.type = "clr",
+    ncomponents = 3
+)
 
 # Analyse mediated effect of nationality on BMI via principal components 
 # 100 permutations were done to speed up execution, but ~1000 are recommended       
-tse <- addMediation(tse, name = "reddim_mediation",
-                    treatment = "nationality",
-                    outcome = "bmi_group",
-                    dimred = "PCA",
-                    covariates = c("sex", "age"),
-                    treat.value = "Scandinavia",
-                    control.value = "CentralEurope",
-                    boot = TRUE, sims = 100,
-                    p.adj.method = "fdr")
+tse <- addMediation(
+    tse, name = "reddim_mediation",
+    treatment = "nationality",
+    outcome = "bmi_group",
+    dimred = "PCA",
+    covariates = c("sex", "age"),
+    treat.value = "Scandinavia",
+    control.value = "CentralEurope",
+    boot = TRUE, sims = 100,
+    p.adj.method = "fdr"
+)
 
 # View results
-knitr::kable(metadata(tse)$reddim_mediation)
+kable(metadata(tse)$reddim_mediation)
 ```
 
 Results can be displayed as one forest plot for each reduced dimension. When
@@ -196,10 +242,19 @@ whether certain groups of features act as mediators.
 
 ```{r}
 #| label: mediation7
+
 # Plot results as multiple forest plots
-p1 <- plotMediation(tse, "reddim_mediation", layout = "forest")
+p1 <- plotMediation(
+    tse, "reddim_mediation",
+    layout = "forest"
+)
+
 # Plot loadings by principal component
-p2 <- plotLoadings(tse, "PCA", ncomponents = 3, n = 8, layout = "heatmap")
+p2 <- plotLoadings(
+    tse, "PCA",
+    ncomponents = 3, n = 8,
+    layout = "heatmap"
+)
 
 # Combine plots
 p1 / p2

From 12ee16af1732a7bc0ae6977dde8a4c5e98d84dda Mon Sep 17 00:00:00 2001
From: Giulio Benedetti <giuliobene2000@gmail.com>
Date: Sun, 9 Feb 2025 22:08:43 +0200
Subject: [PATCH 06/11] Minor fixes

---
 inst/pages/mediation.qmd | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/inst/pages/mediation.qmd b/inst/pages/mediation.qmd
index 1d87fd2f..87cc5e7f 100644
--- a/inst/pages/mediation.qmd
+++ b/inst/pages/mediation.qmd
@@ -38,9 +38,9 @@ In general, the wide range of mediation effects can be divided into two classes:
 
 ```{r}
 #| label: fig-mediation
-#| fig-cap: Directed Acyclic Graphs of two possible relationships involving
+#| fig-cap: Directed acyclic graphs for two possible relationships involving
 #|   mediation. A. The effect of x on y is completely mediated by m. B. The
-#|   effect of x on y is direct, and only a portion is mediated by m.
+#|   effect of x on y is direct, and only a portion thereof is mediated by m.
 #| message: false
 #| echo: false
 

From d3db658f3ec4c529052fe572e4bd2f9c32424ad5 Mon Sep 17 00:00:00 2001
From: TuomasBorman <tvborm@utu.fi>
Date: Mon, 10 Feb 2025 09:53:58 +0200
Subject: [PATCH 07/11] up

---
 DESCRIPTION              |  6 ++++--
 inst/pages/mediation.qmd | 11 ++++++-----
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/DESCRIPTION b/DESCRIPTION
index 6365492d..56b9ddb1 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,7 +1,7 @@
 Package: OMA
 Title: Orchestrating Microbiome Analysis with Bioconductor
-Version: 0.98.35
-Date: 2025-02-05
+Version: 0.98.36
+Date: 2025-02-10
 Authors@R:
     c(
   person(given = "Tuomas", family = "Borman", role = c("aut", "cre"), email = "tuomas.v.borman@utu.fi", comment = c(ORCID = "0000-0002-8563-8884")),
@@ -49,6 +49,7 @@ Suggests:
     factoextra,
     fido,
     forcats,
+    ggdag,
     ggplot2,
     ggpubr,
     ggtree,
@@ -62,6 +63,7 @@ Suggests:
     IntegratedLearner,
     knitr,
     maaslin3,
+    mediation,
     mia,
     miaTime,
     miaViz,
diff --git a/inst/pages/mediation.qmd b/inst/pages/mediation.qmd
index 87cc5e7f..b49cd5c0 100644
--- a/inst/pages/mediation.qmd
+++ b/inst/pages/mediation.qmd
@@ -115,9 +115,9 @@ by the microbiome is investigated in 3 different steps:
 
 First, we ask whether alpha diversity mediates the effect of living environment
 on BMI. Using the `getMediation` function, the variables X, Y and M are
-specified with the arguments `treatment`, `outcome` and `mediator`, respectively.
-We control for sex and age and limit comparisons to two nationality groups,
-Central Europeans (control) vs. Scandinavians (treatment).
+specified with the arguments `treatment`, `outcome` and `mediator`,
+respectively. We control for sex and age and limit comparisons to two
+nationality groups, Central Europeans (control) vs. Scandinavians (treatment).
 
 ```{r}
 #| label: mediation3
@@ -279,5 +279,6 @@ data also exist [@Xia2021mediation]. However, no one solution has emerged yet to
 become the golden standard in microbiome data analysis, mainly because the
 available approaches can only partially accommodate for the specific properties
 of microbiome data, such as compositionality, sparsity and its hierarchical
-structure. While this chapter proposed a standard approach to mediation analysis,
-in the future fine-tuned solutions for the microbiome may also become common.
+structure. While this chapter proposed a standard approach to mediation
+analysis, in the future fine-tuned solutions for the microbiome may also become
+common.

From 9264a19430dce76196f846826bb6c51b833a4a3a Mon Sep 17 00:00:00 2001
From: Giulio Benedetti <giuliobene2000@gmail.com>
Date: Mon, 10 Feb 2025 18:14:48 +0200
Subject: [PATCH 08/11] Add more interpretation and refine wording in mediation
 chapter

---
 inst/pages/mediation.qmd | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/inst/pages/mediation.qmd b/inst/pages/mediation.qmd
index b49cd5c0..a703c93e 100644
--- a/inst/pages/mediation.qmd
+++ b/inst/pages/mediation.qmd
@@ -105,11 +105,11 @@ tse <- transformAssay(
 ```
 
 In the following examples, the effect of living environment on BMI mediated
-by the microbiome is investigated in 3 different steps:
+by the microbiome is investigated in three different steps:
 
 1. global contribution by alpha diversity
 2. individual contributions by assay features
-3. combined contributions by reduced dimensions
+3. joint contributions by reduced dimensions
 
 ## Alpha diversity as mediator
 
@@ -143,7 +143,8 @@ plotMediation(med_df, layout = "forest")
 The forest plot above shows significance for both ACME and ADE, which suggests
 that alpha diversity is a partial mediator of living environment on BMI. In
 contrast, if ACME but not ADE were significant, complete mediation would be
-inferred.
+inferred. The negative sign of the effect means that a lower BMI and alpha
+diversity are associated with the control group (Scandinavians).
 
 ## Assay features as mediators
 
@@ -191,7 +192,9 @@ plotMediation(
 
 Results suggest that only four out of eight features (Bacteroidetes, Firmicutes,
 Proteobacteria and Verrucomicrobia) partially mediate the effect of living
-environment on BMI.
+environment on BMI. As the sign is negative, a smaller abundance of these
+mediators is found in Scandinavians compared to Central Europeans, which matches
+the negative trend of alpha diversity.
 
 While analyses were conducted at the phylum level to simplify results, using
 original assays without agglomeration also represents a valid option. However,
@@ -202,10 +205,10 @@ comparisons. A solution to this issue is proposed in the following section.
 ## Reduced dimensions as mediators
 
 Performing mediation analysis for each feature provides insight into individual
-contributions. However, this approach greatly increases the number of drawn
-comparisons and thus it reduces statistical power. To overcome this issue, it is
-possible to assess the combined contributions of groups of features by means of
-dimensionality reduction.
+contributions. However, this approach greatly increases the number of multiple
+tests to correct for and thus it reduces statistical power. To overcome this
+issue, it is possible to assess the joint contributions of groups of features
+by means of dimensionality reduction.
 
 ```{r}
 #| label: mediation6
@@ -262,13 +265,15 @@ p1 / p2
 
 The plot above suggests that only PC1 partially mediates the effect of living
 environment on BMI. Within this dimension, Bacteroidetes and Actinobacteria are
-the largest contributors.
+the largest contributors in opposite directions. Interestingly, in the previous
+section the former but not the latter appeared significant individually, which
+might imply that mediation emerges from their joint contribution.
 
 ## Final remarks
 
 This chapter introduced the concept of mediation and demonstrated a standard
 analysis of the microbiome as mediator at three different levels (global,
-individual and combined contributions). Importantly, the provided method is
+individual and joint contributions). Importantly, the provided method is
 based on the `mediation` package and is limited to univariate comparisons and
 binary conditions for the independent variable [@Tingley2014mediation].
 Therefore, it is recommended to reduce the number of mediators under study by

From cbc3850ddcc0ea1c7e270eb6592face6f2cff903 Mon Sep 17 00:00:00 2001
From: Giulio Benedetti <giuliobene2000@gmail.com>
Date: Mon, 10 Feb 2025 18:18:25 +0200
Subject: [PATCH 09/11] Minor change to mediation chapter

---
 inst/pages/mediation.qmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/inst/pages/mediation.qmd b/inst/pages/mediation.qmd
index a703c93e..ea9b0ce6 100644
--- a/inst/pages/mediation.qmd
+++ b/inst/pages/mediation.qmd
@@ -267,7 +267,7 @@ The plot above suggests that only PC1 partially mediates the effect of living
 environment on BMI. Within this dimension, Bacteroidetes and Actinobacteria are
 the largest contributors in opposite directions. Interestingly, in the previous
 section the former but not the latter appeared significant individually, which
-might imply that mediation emerges from their joint contribution.
+implies that mediation might emerge from their joint contribution.
 
 ## Final remarks
 

From 760b08a9a22554f4709103f37a56ae2653b5bfb0 Mon Sep 17 00:00:00 2001
From: Giulio Benedetti <giuliobene2000@gmail.com>
Date: Mon, 10 Feb 2025 19:51:54 +0200
Subject: [PATCH 10/11] Fix mediation DAGs

---
 inst/pages/mediation.qmd | 29 +++++++++++++++--------------
 1 file changed, 15 insertions(+), 14 deletions(-)

diff --git a/inst/pages/mediation.qmd b/inst/pages/mediation.qmd
index ea9b0ce6..8d4d788d 100644
--- a/inst/pages/mediation.qmd
+++ b/inst/pages/mediation.qmd
@@ -31,16 +31,16 @@ altered microbiome represents a more subtle process [@Dinan2022antibiotics].
 
 In general, the wide range of mediation effects can be divided into two classes:
 
+- partial mediation, where the mediator assists the independent variable in
+  conveying only part of the effect on the outcome
 - complete mediation, where the mediator conveys the full effect of the the
-  treatment variable on the outcome
-- partial mediation, where the mediator only assists the treatment variable in
-  conveying the effect on the outcome
+  independent variable on the outcome
 
 ```{r}
 #| label: fig-mediation
 #| fig-cap: Directed acyclic graphs for two possible relationships involving
-#|   mediation. A. The effect of x on y is completely mediated by m. B. The
-#|   effect of x on y is direct, and only a portion thereof is mediated by m.
+#|   mediation. A. The effect of x on y is mostly direct, and only a portion
+#|   thereof is mediated by m. B. The effect of x on y is completely mediated by m.
 #| message: false
 #| echo: false
 
@@ -51,12 +51,12 @@ library(patchwork)
 
 # Plot triangle for complete mediation
 p1 <- ggdag_mediation_triangle(x_y_associated = TRUE, stylized = TRUE) +
-    ggtitle("A: Complete mediation") +
+    ggtitle("A: Partial mediation") +
     theme_dag()
   
 # Plot triangle for partial mediation
 p2 <- ggdag_mediation_triangle(stylized = TRUE) +
-    ggtitle("B: Partial mediation") +
+    ggtitle("B: Complete mediation") +
     theme_dag()
 
 # Combine plots
@@ -64,7 +64,7 @@ p1 | p2
 ```
 
 We demonstrate a standard mediation analysis with the `hitchip1006` dataset
-from the `miaTime` package, which contains a genus-level assay for 1006 western
+from the `miaTime` package, which contains a genus-level assay for 1006 Western
 adults of 6 different nationalities.
 
 ```{r}
@@ -114,10 +114,10 @@ by the microbiome is investigated in three different steps:
 ## Alpha diversity as mediator
 
 First, we ask whether alpha diversity mediates the effect of living environment
-on BMI. Using the `getMediation` function, the variables X, Y and M are
-specified with the arguments `treatment`, `outcome` and `mediator`,
-respectively. We control for sex and age and limit comparisons to two
-nationality groups, Central Europeans (control) vs. Scandinavians (treatment).
+on BMI. Using the `getMediation` function, the variables X, Y and M are specified
+with the arguments `treatment`, `outcome` and `mediator`, respectively. We
+control for sex and age and limit comparisons to two nationality groups, Central
+Europeans (control) vs. Scandinavians (treatment).
 
 ```{r}
 #| label: mediation3
@@ -151,7 +151,8 @@ diversity are associated with the control group (Scandinavians).
 If we suspect that only certain features of the microbiome act as mediators,
 we can estimate their individual contributions by fitting one model for each
 feature in a selected assay. As multiple tests are performed, it is good
-practice to correct the significance of the findings with a method of choice.
+practice to correct the significance of the findings with a method of choice to
+adjust p-values.
 
 ```{r}
 #| label: mediation4
@@ -240,7 +241,7 @@ kable(metadata(tse)$reddim_mediation)
 ```
 
 Results can be displayed as one forest plot for each reduced dimension. When
-combined with a heatmap of the feature loadings by dimension, we can deduce
+combined with a heatmap of the feature loadings by dimension, it helps deduce
 whether certain groups of features act as mediators.
 
 ```{r}

From 73d3d544b2ab462b770eaf8727bd36de1a6ae17d Mon Sep 17 00:00:00 2001
From: Giulio Benedetti <giuliobene2000@gmail.com>
Date: Mon, 10 Feb 2025 20:19:46 +0200
Subject: [PATCH 11/11] Add temporal assumption of mediation analysis

---
 inst/assets/bibliography.bib | 12 ++++++++++++
 inst/pages/mediation.qmd     | 19 ++++++++++++-------
 2 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/inst/assets/bibliography.bib b/inst/assets/bibliography.bib
index 8f1f3e66..e99b8600 100644
--- a/inst/assets/bibliography.bib
+++ b/inst/assets/bibliography.bib
@@ -2424,6 +2424,18 @@ @article{Logan2014nutritional
   year={2014},
   publisher={Springer}
 }
+
+@article{Fairchild2017best,
+  title={Best (but oft-forgotten) practices: mediation analysis},
+  author={Fairchild, Amanda J and McDaniel, Heather L},
+  journal={The American journal of clinical nutrition},
+  volume={105},
+  number={6},
+  pages={1259--1271},
+  year={2017},
+  publisher={Elsevier}
+}
+
 @article{Marchesi2015,
   title = {The vocabulary of microbiome research: a proposal},
   volume = {3},
diff --git a/inst/pages/mediation.qmd b/inst/pages/mediation.qmd
index 8d4d788d..e3db6c85 100644
--- a/inst/pages/mediation.qmd
+++ b/inst/pages/mediation.qmd
@@ -5,7 +5,7 @@ library(rebook)
 chapterPreamble()
 ```
 
-Mediation analysis is used to study the effect of an independent variable (X) on
+Mediation analysis is used to study the effect of an exposure variable (X) on
 the outcome (Y) through a third factor, known as mediator (M). Mathematically,
 this relationship can be described as follows:
 
@@ -31,10 +31,10 @@ altered microbiome represents a more subtle process [@Dinan2022antibiotics].
 
 In general, the wide range of mediation effects can be divided into two classes:
 
-- partial mediation, where the mediator assists the independent variable in
+- partial mediation, where the mediator assists the exposure variable in
   conveying only part of the effect on the outcome
 - complete mediation, where the mediator conveys the full effect of the the
-  independent variable on the outcome
+  exposure variable on the outcome
 
 ```{r}
 #| label: fig-mediation
@@ -63,6 +63,11 @@ p2 <- ggdag_mediation_triangle(stylized = TRUE) +
 p1 | p2
 ```
 
+Mediation analysis is based on the assumption that the exposure variable, the
+mediator and the outcome follow one another in this temporal sequence. Therefore,
+investigating mediation is a suitable analytical choice in longitudinal studies,
+whereas it is discouraged in cross-sectional ones [@Fairchild2017best].
+
 We demonstrate a standard mediation analysis with the `hitchip1006` dataset
 from the `miaTime` package, which contains a genus-level assay for 1006 Western
 adults of 6 different nationalities.
@@ -83,7 +88,7 @@ data(hitchip1006, package = "miaTime")
 tse <- hitchip1006
 ```
 
-In our analyses, nationality and BMI group will represent the independent (X)
+In our analyses, nationality and BMI group will represent the exposure (X)
 and outcome (Y) variables, respectively. We make the broad assumption that
 nationality reflects differences in the living environment between subjects.
 
@@ -276,9 +281,9 @@ This chapter introduced the concept of mediation and demonstrated a standard
 analysis of the microbiome as mediator at three different levels (global,
 individual and joint contributions). Importantly, the provided method is
 based on the `mediation` package and is limited to univariate comparisons and
-binary conditions for the independent variable [@Tingley2014mediation].
-Therefore, it is recommended to reduce the number of mediators under study by
-means of a knowledge-based strategy to preserve statistical power.
+binary conditions for the exposure variable [@Tingley2014mediation]. Therefore,
+it is recommended to reduce the number of mediators under study by means of a
+knowledge-based strategy to preserve statistical power.
 
 A few methods for multivariate mediation analysis of high-dimensional omic
 data also exist [@Xia2021mediation]. However, no one solution has emerged yet to