MaAslin2-Tutorial #5173

renu-pal · 2024-07-16T21:40:59Z

Tutorial draft on Maaslin2. Would love any suggestions or changes on this.

shiltemann · 2024-07-30T09:58:59Z

Hi @renu-pal, thanks for your contribution! I have taken it out of draft mode so that our tests can run and people will know they can review it :)

topics/microbiome/tutorials/multivariable-association/tutorial.md

Co-authored-by: Saskia Hiltemann <[email protected]>

renu-pal · 2024-07-30T10:06:42Z

Hi @renu-pal, thanks for your contribution! I have taken it out of draft mode so that our tests can run and people will know they can review it :)

Sounds great! :)

paulzierep

Looks great! would be nice to extand a bit, show different options and some more output

paulzierep · 2024-08-15T09:48:28Z

topics/microbiome/tutorials/multivariable-association/data-library.yaml

+    - name: 'DOI: 10.5281/zenodo.12614561'
+      description: latest
+      items:
+      - url: https://zenodo.org/api/records/12614561/files/HMP2_metadata.tsv/content


https://zenodo.org/records/12614561/files/HMP2_metadata.tsv should also work

Suggested change

- url: https://zenodo.org/api/records/12614561/files/HMP2_metadata.tsv/content

- url: https://zenodo.org/api/records/12614561/files/HMP2_metadata.tsv

why is it resolved, It's still not correct ... ?

I thought miss Shilteman made the last update about this exactly , I did not notice it was data-library.yaml file you were mentioning. I am extremely sorry for that. I will make the necessary changes.

Here, made the change
63a44c4

topics/microbiome/tutorials/multivariable-association/tutorial.md

paulzierep · 2024-08-15T09:57:48Z

topics/microbiome/tutorials/multivariable-association/tutorial.md

+>
+{: .agenda}
+
+# Get the data


Where does the data come from, what does it contain, was it used in other studies, are there other studies that suggest ideal maaslin2 parameters for this kind of data ?

I couldn't find studies which used both HMP2 data as well as Maaslin2 tool. So instead I mentioned studies which used Maaslin2 tool with the parameters used. If it does not feel right , then please let me know.

Isn't the main maaslin2 paper using HMP data ? https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1009442#sec002

Maybe its enought to add that this was the initial data used to demonstrate maaslin2 ?

sounds better

topics/microbiome/tutorials/multivariable-association/tutorial.md

paulzierep · 2024-08-15T10:19:19Z

Can you look into the linting issues as well ?

bgruening · 2024-09-07T12:22:49Z

@renu-pal do you need any help here?

renu-pal · 2024-09-08T23:07:08Z

@renu-pal do you need any help here?

Definitely @bgruening :) . Can you please go through the tutorial and let me know if you find anything wrong.

bgruening · 2024-09-28T12:16:06Z

topics/microbiome/tutorials/multivariable-association/data-library.yaml

+    - name: 'DOI: 10.5281/zenodo.12614561'
+      description: latest
+      items:
+      - url: https://zenodo.org/api/records/12614561/files/HMP2_metadata.tsv/content


Suggested change

- url: https://zenodo.org/api/records/12614561/files/HMP2_metadata.tsv/content

- url: https://zenodo.org/api/records/12614561/files/HMP2_metadata.tsv

topics/microbiome/tutorials/multivariable-association/data-library.yaml

bgruening · 2024-09-28T12:17:58Z

...-'Determining-multivariable-association-between-various-meta’omic-features-using-MaAslin2.ga

+    "annotation": "",
+    "comments": [],
+    "format-version": "0.1",
+    "name": "Workflow constructed from history 'Determining multivariable association between various meta\u2019omic features using MaAslin2",


Suggested change

"name": "Workflow constructed from history 'Determining multivariable association between various meta\u2019omic features using MaAslin2",

"name": "Determining multivariable association between various meta-omic features using MaAslin2",

This way?

I kept the omitted part just to differentiate a between the title of workflow file and tutorial file. If it doesn't cause any issue then I believe we should not change it. What are your thoughts on this ? @bgruening

I don't see any reason why a workflow should be named 'construceted from history'

Can you please remove the two workflows, starting with Workflow constructed from history ...` and only keep the main one with the correct title ?

b10e57a , 74a3f39, 0e828c1

topics/microbiome/tutorials/multivariable-association/tutorial.md

…rary.yaml Co-authored-by: Björn Grüning <[email protected]>

paulzierep · 2024-09-30T13:39:03Z

topics/microbiome/tutorials/multivariable-association/tutorial.md

+>
+{: .agenda}
+
+# Get the data


Isn't the main maaslin2 paper using HMP data ? https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1009442#sec002

topics/microbiome/tutorials/multivariable-association/tutorial.md

paulzierep · 2024-09-30T13:47:24Z

topics/microbiome/tutorials/multivariable-association/tutorial.md

+- **Sensitivity** measures how well the methods detect true signals, higher values lead to better performance.
+- **False discovery rate (FDR)** measures the proportion of false positives among detected signals (lower FDR is better).
+- MaAsLin2 is the clear standout for both differential abundance detection and multivariable association detection, showing high sensitivity and maintaining a low FDR.
+


Maybe we can add something like:
In this regard, MaAsLin2 can be seen as a Swiss army knife for differential analysis of microbiome data. With some text processing various omics data types could be used as input e.g. from these GTN tutorials:

then check the existing GTN toturial and add those that provide matching data

bla

blumb

paulzierep · 2024-10-01T08:30:56Z

topics/microbiome/tutorials/multivariable-association/data-library.yaml

+  description: Galaxy Training Network Material
+  synopsis: Galaxy Training Network Material. See https://training.galaxyproject.org
+items:
+- name: The new topic


Suggested change

- name: The new topic

- name: The new topic

?

topics/microbiome/tutorials/multivariable-association/tutorial.md

paulzierep · 2024-10-01T08:40:50Z

topics/microbiome/tutorials/multivariable-association/tutorial.md

+| **Phyloseq + DESeq2**| Strong for RNA-seq and transcriptomics; integrates with Phyloseq | Lacks compositionality awareness         | While DESeq2 works for microbiome data, MaAsLin2 offers more suitable options for compositional data and covariate handling. |
+| **Limma-Voom**      | Effective for RNA-seq and microarray data, handles low counts | Not tailored for compositional microbiome data | Limma-Voom is well-suited for gene expression, but MaAsLin2 better accounts for the unique characteristics of microbiome data. |
+
+- ANCOM-BC and MaAsLin2, outperform general-purpose tools like DESeq2 and limma-voom when it comes to microbiome data. This is due to their handling of the compositional nature of microbiome data and the sparsity typical of microbial datasets.[PMID: 36617187](https://pubmed.ncbi.nlm.nih.gov/36617187/)


Can you please exchange all links to studies with citations as shown here:

training-material/topics/microbiome/tutorials/pathogen-detection-from-nanopore-foodborne-data/tutorial.md

Line 89 in 5012353

The currently available studies used Illumina sequencing, generating short reads. Longer read lengths, generated by third-generation sequencing platforms such as Pacific Biosciences (PacBio) and Oxford Nanopore Technologies (ONT), make it **easier and more practical to identify strains with fewer reads**. MinION (from Oxford Nanopore) is a portable, real-time device for ONT sequencing. Several proof-of-principle studies have shown the **utility of ONT long-read sequencing from metagenomic samples for pathogen identification** ({% cite CIUFFREDA20211497 %}).

paulzierep · 2024-10-01T08:42:27Z

topics/microbiome/tutorials/multivariable-association/tutorial.md

+- **Taxonomy (or features) file**: \
+        This file is tab-delimited.\
+        Formatted with features as columns and samples as rows.\
+        The transposition of this format is also okay.\


Is it ? Can our wrapper work with both ?

Thanks for pointing this out @paulzierep . I cross checked and unfortunately our wrapper cannot work with both. I have made the changes accordingly in the tutorial. Sorry for the confusion.

paulzierep · 2024-10-01T08:44:15Z

topics/microbiome/tutorials/multivariable-association/tutorial.md

+
+MaAsLin2 requires the following input files:
+
+- **Taxonomy (or features) file**: \


Suggested change

- **Taxonomy (or features) file**: \

- **Features file**: \

Would like to keep it more generic. Maybe add some examples like: (OTU/ASV abundance table, MAGs abundance matrix, taxonomy table, gene count matrix at the end of the list

paulzierep · 2024-10-01T08:45:14Z

topics/microbiome/tutorials/multivariable-association/tutorial.md

+>
+{: .agenda}
+
+# Get the data


Maybe its enought to add that this was the initial data used to demonstrate maaslin2 ?

paulzierep · 2024-10-01T08:45:28Z

topics/microbiome/tutorials/multivariable-association/tutorial.md

+        Formatted with features as columns and samples as rows.\
+        The transposition of this format is also okay.
+
+The Taxonomy file can contain samples not included in the metadata file (or vice versa). For both cases, those samples not included in both files will be removed from the analysis.


Suggested change

The Taxonomy file can contain samples not included in the metadata file (or vice versa). For both cases, those samples not included in both files will be removed from the analysis.

The feature file can contain samples not included in the metadata file (or vice versa). For both cases, those samples not included in both files will be removed from the analysis.

shiltemann · 2024-10-07T15:30:09Z

topics/microbiome/tutorials/multivariable-association/tutorial.bib

+  author = {GTN community},
+  title = {GTN Training Materials: Collection of tutorials developed and maintained by the worldwide Galaxy community},
+  url = {https://training.galaxyproject.org},
+  urldate = {2021-03-24}


our bibtex parser is failing to parse urldate key. I think we should support this in the future, but perhaps for now you can set the date in a note so that the tests don't fail, e.g.:

note = "[Online; accessed Fri Nov 05 2021]"

Thanks ! Will make the necessary changes :)

paulzierep · 2024-10-14T15:38:03Z

@renu-pal can you check the linting ?

paulzierep

Please do not mark comments as resolved if they are not resolved, or explain otherwise why it's not needed.
Otherwise, minor changes, then we should be good to merge. Thanks !

paulzierep · 2024-10-14T15:59:37Z

topics/microbiome/tutorials/multivariable-association/data-library.yaml

+    - name: 'DOI: 10.5281/zenodo.12614561'
+      description: latest
+      items:
+      - url: https://zenodo.org/api/records/12614561/files/HMP2_metadata.tsv/content


why is it resolved, It's still not correct ... ?

paulzierep · 2024-10-16T12:01:59Z

topics/microbiome/tutorials/multivariable-association/tutorial.md

+>    {: .question}
+>
+{: .hands_on}
+


Suggested change

## Data that can be analysed with MaAsLi2

Can you add some subsections to make it better structured ?

topics/microbiome/tutorials/multivariable-association/tutorial.md

paulzierep · 2024-10-16T12:09:20Z

topics/microbiome/tutorials/multivariable-association/tutorial.md

+
+![sensitivity and false discovery rate (FDR) across different tools](https://journals.plos.org/ploscompbiol/article/figure/image?size=large&id=10.1371/journal.pcbi.1009442.g004 "Source: <a href="https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1009442#pcbi-1009442-g004">sensitivity and false discovery rate (FDR) across different tools</a>"){:width="60%"} 
+
+- The above figure compares various tools for differential abundance detection (Panel A) and multivariable association detection (Panel B) in microbiome studies, based on sensitivity and false discovery rate (FDR).


This and the next 4 sentences do no need to be bullet points.

paulzierep · 2024-10-16T12:15:28Z

topics/microbiome/tutorials/multivariable-association/tutorial.md

+9. **analysis_method** [ Default: "LM" ] [ Options: "LM", "CPLM", "ZICP", "NEGBIN", "ZINB" ]
+- The analysis method to apply.
+- Options: \
+        1. <u>Linear Model (LM)</u>: Determines how changes in metadata are associated with changes in the taxonomy data. 


Suggested change

1. <u>Linear Model (LM)</u>: Determines how changes in metadata are associated with changes in the taxonomy data.

1. <u>Linear Model (LM)</u>: The defaul linear model of MaAsLin2. By default, MaAsLin2 uses linear regression (for continuous metadata) or logistic regression (for binary metadata) as its association method.

All models should do that, but what is the difference between them

paulzierep · 2024-10-16T12:19:09Z

topics/microbiome/tutorials/multivariable-association/tutorial.md

+14.  **plot_scatter**: Generate scatter plots for the significant associations [ Default: TRUE ]
+15.   **cores**: The number of R processes to run in parallel [ Default: 1 ]
+
+# Model types in MaAslin2


Not clear to me what this paragraph means, you already explain the models analysis_method - so its not clear what point 2 and 3 mean, can you choose these options ? Would remove or rephrase.

These are not the option that can be chosen. These are broader categories of models under which the analysis methods explained above fall . For instance CPLM, ZICP etc come under generalized linear model. If user chooses random effect , then model works as linear mixed model.

@paulzierep I can make it more clear in the tutorial if you want. Let me know if the above explaination makes sense to you. I can add this explaination in the analysis method section and remove the following para on these models.

then you should say, that those are models chosen by maaslin depending on the data input and the parameter choice. Otherwise, it's confusing. However, if CPLM, ZICP lead to Generalized Linear Models then this should also be stated. You got the When to Use: part - but users cannot choose anything - so that would confuse me

Understood. I will make the necessary changes. Thanks for the detailed explanation :)

paulzierep · 2024-10-16T12:26:12Z

topics/microbiome/tutorials/multivariable-association/tutorial.md

+In essence, uncovering associations between microbial features and metadata variables through tools like MaAsLin2 not only deepens our understanding of microbiome dynamics but also holds promise for clinical applications, personalized health strategies, and advancing the field of microbiome research.
+
+The results obtained from MaAslin2 can further be visualized using tools like [**phyloseq**](https://training.galaxyproject.org/training-material/by-tool/interactive_tool_phyloseq.html).\
+Tools like phyloseq require that you prepare your data (OTU/ASV table, metadata) in a structured format before visualizing.\


I would add here, that the features need to be subsampled to only include significant features. This can be done with https://usegalaxy.eu/?tool_id=toolshed.g2.bx.psu.edu%2Frepos%2Fiuc%2Fampvis2_subset_taxa%2Fampvis2_subset_taxa%2F2.8.9%2Bgalaxy0&version=latest

paulzierep · 2024-10-16T12:34:30Z

...-'Determining-multivariable-association-between-various-meta’omic-features-using-MaAslin2.ga

+    "annotation": "",
+    "comments": [],
+    "format-version": "0.1",
+    "name": "Workflow constructed from history 'Determining multivariable association between various meta\u2019omic features using MaAslin2",


Can you please remove the two workflows, starting with Workflow constructed from history ...` and only keep the main one with the correct title ?

…s/Workflow-constructed-from-history-'Determining-multivariable-association-between-various-meta’omic-features-using-MaAslin2.ga

…ivariable-association-between-various-meta’omic-features-using-MaAslin2-tests.yml to Determining-multivariable-association-between-various-meta’omic-features-using-MaAslin2-tests.yml

…s/main_workflow.ga

Co-authored-by: paulzierep <[email protected]>

MaAslin2-Tutorial

611817f

github-actions bot added template-and-tools microbiome labels Jul 16, 2024

shiltemann marked this pull request as ready for review July 30, 2024 09:57

shiltemann reviewed Jul 30, 2024

View reviewed changes

topics/microbiome/tutorials/multivariable-association/tutorial.md Outdated Show resolved Hide resolved

shiltemann added new tutorial new contributor(s) labels Jul 30, 2024

Update topics/microbiome/tutorials/multivariable-association/tutorial.md

ebbd4c9

Co-authored-by: Saskia Hiltemann <[email protected]>

shiltemann requested a review from a team August 8, 2024 09:31

shiltemann added 3 commits August 12, 2024 17:33

formatting

fe85d9a

indent comment box to keep numbering in list correct

d04399c

rewrite zenodo links

f2acff0

paulzierep reviewed Aug 15, 2024

View reviewed changes

renu-pal added 2 commits August 22, 2024 10:13

added tags and a test

c761680

origin of input data, studies involving maaslin2 and summary of methods

1ed7bd7

renu-pal and others added 3 commits September 24, 2024 15:15

comparing maaslin2 with other tools in galaxy

8b7a006

a bunch of edits

7b184cd

Update tutorial.md

415272c

bgruening previously approved these changes Sep 28, 2024

View reviewed changes

Update topics/microbiome/tutorials/multivariable-association/data-lib…

546b191

…rary.yaml Co-authored-by: Björn Grüning <[email protected]>

renu-pal dismissed bgruening’s stale review via 546b191 September 29, 2024 13:36

renu-pal and others added 2 commits September 29, 2024 17:08

Update topics/microbiome/tutorials/multivariable-association/data-lib…

12b3f04

…rary.yaml Co-authored-by: Björn Grüning <[email protected]>

remaining updates and lint issue

5bd7914

paulzierep reviewed Oct 1, 2024

View reviewed changes

citations, types of table and few corrections

fd99f28

renu-pal force-pushed the maaslin2_tutorial branch from ff35d6a to fd99f28 Compare October 7, 2024 13:29

shiltemann reviewed Oct 7, 2024

View reviewed changes

renu-pal added 2 commits October 8, 2024 05:21

Update urldate to note

76dbe06

Update

ebbdefd

renu-pal added 2 commits October 14, 2024 17:57

lint issue

d729aa9

minor lint issue

c6eae2a

paulzierep reviewed Oct 16, 2024

View reviewed changes

renu-pal and others added 10 commits October 16, 2024 17:20

change in zenodo path

63a44c4

Delete topics/microbiome/tutorials/multivariable-association/workflow…

b10e57a

…s/Workflow-constructed-from-history-'Determining-multivariable-association-between-various-meta’omic-features-using-MaAslin2.ga

Update and rename Workflow-constructed-from-history-'Determining-mult…

74a3f39

…ivariable-association-between-various-meta’omic-features-using-MaAslin2-tests.yml to Determining-multivariable-association-between-various-meta’omic-features-using-MaAslin2-tests.yml

Delete topics/microbiome/tutorials/multivariable-association/workflow…

0e828c1

…s/main_workflow.ga

Update topics/microbiome/tutorials/multivariable-association/tutorial.md

30d373a

Co-authored-by: paulzierep <[email protected]>

Update topics/microbiome/tutorials/multivariable-association/tutorial.md

0fa5562

Co-authored-by: paulzierep <[email protected]>

Update topics/microbiome/tutorials/multivariable-association/tutorial.md

76283dc

Co-authored-by: paulzierep <[email protected]>

Update topics/microbiome/tutorials/multivariable-association/tutorial.md

22fc038

Co-authored-by: paulzierep <[email protected]>

Update topics/microbiome/tutorials/multivariable-association/tutorial.md

bcc9c78

Co-authored-by: paulzierep <[email protected]>

models,ampvis,subsection updates

65c2a15

	- url: https://zenodo.org/api/records/12614561/files/HMP2_metadata.tsv/content
	- url: https://zenodo.org/api/records/12614561/files/HMP2_metadata.tsv

	"name": "Workflow constructed from history 'Determining multivariable association between various meta\u2019omic features using MaAslin2",
	"name": "Determining multivariable association between various meta-omic features using MaAslin2",


		MaAsLin2 requires the following input files:

		- Taxonomy (or features) file: \

	The Taxonomy file can contain samples not included in the metadata file (or vice versa). For both cases, those samples not included in both files will be removed from the analysis.
	The feature file can contain samples not included in the metadata file (or vice versa). For both cases, those samples not included in both files will be removed from the analysis.


		![sensitivity and false discovery rate (FDR) across different tools](https://journals.plos.org/ploscompbiol/article/figure/image?size=large&id=10.1371/journal.pcbi.1009442.g004 "Source: <a href="https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1009442#pcbi-1009442-g004">sensitivity and false discovery rate (FDR) across different tools</a>"){:width="60%"}

		- The above figure compares various tools for differential abundance detection (Panel A) and multivariable association detection (Panel B) in microbiome studies, based on sensitivity and false discovery rate (FDR).

	1. <u>Linear Model (LM)</u>: Determines how changes in metadata are associated with changes in the taxonomy data.
	1. <u>Linear Model (LM)</u>: The defaul linear model of MaAsLin2. By default, MaAsLin2 uses linear regression (for continuous metadata) or logistic regression (for binary metadata) as its association method.

MaAslin2-Tutorial #5173

Are you sure you want to change the base?

MaAslin2-Tutorial #5173

Conversation

renu-pal commented Jul 16, 2024 • edited Loading

shiltemann commented Jul 30, 2024

renu-pal commented Jul 30, 2024

paulzierep left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paulzierep commented Aug 15, 2024

bgruening commented Sep 7, 2024

renu-pal commented Sep 8, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shiltemann Oct 7, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paulzierep commented Oct 14, 2024

paulzierep left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

renu-pal commented Jul 16, 2024 •

edited

Loading

shiltemann Oct 7, 2024 •

edited

Loading