maaslin2 --> maaslin3

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: OMA
 Title: Orchestrating Microbiome Analysis with Bioconductor
-Version: 0.98.32
-Date: 2024-11-26
+Version: 0.98.33
+Date: 2025-02-05
 Authors@R:
     c(
   person(given = "Tuomas", family = "Borman", role = c("aut", "cre"), email = "[email protected]", comment = c(ORCID = "0000-0002-8563-8884")),
@@ -102,6 +102,7 @@ Suggests:
     WGCNA,
     xgboost
 Remotes:
+    github::biobakery/maaslin3,
     github::microbiome/mia,
     github::microbiome/miaViz,
     github::microbiome/miaTime,

inst/assets/bibliography.bib

@@ -55,7 +55,7 @@ @Article{Martino2019
   volume =	 4,
   issue =	 1,
   doi =		 {},
-  year =	 2019 
+  year =	 2019
 }
 
 @Article{Gloor2017,
@@ -1279,7 +1279,7 @@ @Article{Calgaro2020
     journal = {Genome Biology},
     url = {https://doi.org/10.1186/s13059-020-02104-1}
 }
-  
+
 @Article{Calgaro2022,
     title = {benchdamic: benchmarking of differential abundance
 methods for microbiome data},
@@ -2192,13 +2192,13 @@ @article{Rajaram2010
 }
 
 @misc{pelto2024,
-      title={Elementary methods provide more replicable results in microbial differential abundance analysis}, 
+      title={Elementary methods provide more replicable results in microbial differential abundance analysis},
       author={Juho Pelto and Kari Auranen and Janne Kujala and Leo Lahti},
       year={2024},
       eprint={2404.02691},
       archivePrefix={arXiv},
       primaryClass={stat.AP},
-      url={https://arxiv.org/abs/2404.02691}, 
+      url={https://arxiv.org/abs/2404.02691},
 }
 
 @article{Rahman2023,
@@ -2321,3 +2321,12 @@ @article{mangiola2023
     eprint = {https://www.pnas.org/doi/pdf/10.1073/pnas.2203828120},
     }
 
+@article{Nickols2024,
+  title = {MaAsLin 3: Refining and extending generalized multivariable linear models for meta-omic association discovery},
+  url = {http://dx.doi.org/10.1101/2024.12.13.628459},
+  DOI = {10.1101/2024.12.13.628459},
+  publisher = {Cold Spring Harbor Laboratory},
+  author = {Nickols,  William A. and Kuntz,  Thomas and Shen,  Jiaxian and Maharjan,  Sagun and Mallick,  Himel and Franzosa,  Eric A. and Thompson,  Kelsey N. and Nearing,  Jacob T. and Huttenhower,  Curtis},
+  year = {2024},
+  month = dec
+}

inst/pages/differential_abundance.qmd

@@ -316,49 +316,61 @@ ancombc2_out$res |>
   kable()
 ```
 
-### MaAsLin2
+### MaAsLin3
 
-Let us next illustrate MaAsLin2 [@Mallick2020]. This method is based on
+Let us next illustrate MaAsLin3 [@Nickols2024]. This method is based on
 generalized linear models and flexible for different study designs
 and covariate structures. For details, check their
-[Biobakery tutorial](https://github.com/biobakery/biobakery/wiki/maaslin2).
+[Biobakery tutorial](https://github.com/biobakery/biobakery/wiki/MaAsLin3).
+
+```{r}
+#| label: run_maaslin3
+#| results: hide
 
-```{r run-maaslin2, warning=FALSE, results="hide"}
 # Load package
-library(Maaslin2)
+library(maaslin3)
 
-# maaslin expects features as columns and samples as rows
-# for both the abundance table as well as metadata
+# MaAsLin3 takes tse as input data
 
 # We can specify different GLMs/normalizations/transforms.
-# specifying a ref is especially important if you have more than 2 levels
-maaslin2_out <- Maaslin2(
-    input_data = as.data.frame(t(assay(tse))),
-    input_metadata = as.data.frame(colData(tse)),
-    output = "DAA example",
-    transform = "AST",
-    fixed_effects = "patient_status",
-    # you can also fit MLM by specifying random effects
-    # random_effects = c(...),
-    reference = "patient_status,Control",
+maaslin3_out <- maaslin3(
+    input_data = tse,
+    output = "DAA_example",
+    formula = "~ patient_status",
     normalization = "TSS",
-    standardize = FALSE,
-    # filtering was previously performed
-    min_prevalence = 0)
+    transform = "LOG",
+    verbosity = "ERROR"
+    )
 ```
 
 Which genera are identified as differentially abundant?
-(leave out "head" to see all).
-
-```{r, maaslin2-res}
-maaslin2_out$results |>
-  filter(qval < 0.05) |>
+Maaslin3 tests differential abundance and differential prevalence. We choose the
+differential abundance results. You can see that the results includes two
+adjusted p-values: individual and joint. "Individual" is q-value for
+differential abundance while "joint" combines both differential abundance
+and differential prevalence results for the association.
+
+```{r}
+#| label: maaslin3_results
+
+maaslin3_out <- maaslin3_out[["fit_data_abundance"]][["results"]]
+maaslin3_out |>
+  filter(qval_joint <= 0.05) |>
   kable()
 ```
 
-This will create a folder that is called like in the output specified
+This will create a folder that is called in the output specified
 above. It contains also figures to visualize difference between
-significant taxa.
+significant taxa. The following figure summarizes the DAA results generated by
+MaAsLin3. As can be seen,
+`r paste0(maaslin3_out[maaslin3_out[["qval_joint"]]<= 0.05, "feature"], collapse = " and ")`
+are diffential abundant between the study groups.
+
+```{r}
+#| label: maaslin3_summary
+
+knitr::include_graphics("DAA_example/figures/summary_plot.png")
+```
 
 ### PhILR