POC for immunedeconv module

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- [[#390](https://github.com/nf-core/differentialabundance/pull/390)] - Added `IMMUNEDECONV` module. ([@nschcolnicov](https://github.com/nschcolnicov), review by [@TODO](https://github.com/TODO)).
 - [[#358](https://github.com/nf-core/differentialabundance/pull/358)] - Added software version check in nf-tests and gene biotype column check in `.Rmd` ([@atrigila](https://github.com/atrigila), review by [@pinin4fjords](https://github.com/pinin4fjords))
 - [[#354](https://github.com/nf-core/differentialabundance/pull/354)] - Warning message within the R Markdown report to control when genes don't have annotation data ([@alanmmobbs93](https://github.com/alanmmobbs93)). Review by [@WackerO](https://github.com/WackerO) and [@pinin4fjords](https://github.com/pinin4fjords).
 - [[#345](https://github.com/nf-core/differentialabundance/pull/345)] - Plot differentially expressed genes by gene biotype ([@atrigila](https://github.com/atrigila), review by [@grst](https://github.com/grst))

README.md

@@ -34,8 +34,9 @@ On release, automated continuous integration tests run the pipeline on a full-si
 3. Run differential analysis over all contrasts specified.
 4. Optionally run a differential gene set analysis.
 5. Generate exploratory and differential analysis plots for interpretation.
-6. Optionally build and (if specified) deploy a Shiny app for fully interactive mining of results.
-7. Build an HTML report based on R markdown, with interactive plots (where possible) and tables.
+6. Run immunedeconv to estimate immune cell fractions using established deconvolution methods.
+7. Optionally build and (if specified) deploy a Shiny app for fully interactive mining of results.
+8. Build an HTML report based on R markdown, with interactive plots (where possible) and tables.
 
 ## Usage
 
@@ -137,6 +138,10 @@ We thank the many members of the nf-core community who assisted with this pipeli
 - [@mahesh-panchal](https://github.com/mahesh-panchal),
 - [@mashehu](https://github.com/mashehu),
 - [@apeltzer](https://github.com/apeltzer)
+- [@grst](https://github.com/grst)
+- [@atrigila](https://github.com/atrigila)
+- [@alanmmobbs93](https://github.com/alanmmobbs93)
+- [@nschcolnicov](https://github.com/nschcolnicov)
 
 ## Contributions and Support
 

conf/modules.config

@@ -307,6 +307,22 @@ process {
         ]
     }
 
+    withName: IMMUNEDECONV {
+        ext.prefix = { "${meta.id}" }
+        publishDir = [
+            [
+                path: { "${params.outdir}/tables/immunedeconv" },
+                mode: params.publish_dir_mode,
+                pattern: '*.deconvolution_results.tsv'
+            ],
+            [
+                path: { "${params.outdir}/plots/immunedeconv" },
+                mode: params.publish_dir_mode,
+                pattern: '*.png'
+            ]
+        ]
+    }
+
     withName: GSEA_GSEA {
         ext.prefix = { "${meta.id}.${gene_sets.baseName}." }
         publishDir = [

conf/test.config

@@ -38,6 +38,11 @@ params {
     // Test dataset is too small for the nsub default value
     deseq2_vst_nsub                   = 500
 
+    // IMMUNEDECONV
+    immunedeconv_run      = true
+    immunedeconv_method   = "mmcp_counter"
+    immunedeconv_function = "deconvolute_mouse"
+
     // Activate GSEA
     gsea_run = true
     gene_sets_files = 'https://raw.githubusercontent.com/nf-core/test-datasets/modules/data/genomics/mus_musculus/gene_set_analysis/mh.all.v2022.1.Mm.symbols.gmt'

docs/output.md

@@ -36,6 +36,8 @@ Stand-alone graphical outputs are placed in this directory. They may be useful i
     - `[coloring variable]/png/mad_correlation.png`: Outlier prediction plots using median absolute deviation (MAD)
   - `differential/`: Directory containing standalone plots from differential analysis. Plots are stored in directories named for the associated contrast.
     - `[contrast]/png/volcano.png`: Volcano plots of -log(10) p value agains log(2) fold changes
+  - `immunedeconv/`: Directory containing graphical outputs of immunedeconv results
+    - `${prefix}.plot1_stacked_bar_chart.png`
   - `gsea/`: Directory containing graphical outputs from GSEA (where enabled). Plots are stored in directories named for the associated contrast.
     - `[contrast]/png/[gsea_plot_type].png`
   - `gprofiler2/`: Directory containing graphical outputs from gprofiler2 (where enabled). Plots are stored in directories named for the associated contrast.
@@ -69,6 +71,8 @@ Most plots are included in the HTML report (see above), but are also included in
   - `differential/`: Directory containing tables of differential statistics reported by differential modules such as DESeq2
     - `[contrast_name].[deseq2|limma].results.tsv`: Results of DESeq2 differential analyis (RNA-seq) OR Limma differential analysis (Affymetrix arrays, GEO studies, Maxquant proteomics studies)
     - `[contrast_name].[deseq2|limma].results_filtered.tsv`: Results of DESeq2 differential analyis (RNA-seq) OR Limma differential analysis (Affymetrix arrays, GEO studies, Maxquant proteomics studies); filtered for differentially abundant entries
+  - `immunedeconv/`: Directory containing table of immunedeconv results
+    - `${prefix}.deconvolution_results.tsv`: TSV output that contains estimated proportions of immune cell types for each sample
   - `gsea/`: Directory containing tables of differential gene set analyis from GSEA (where enabled)
     - `[contrast]/[contrast].gsea_report_for_[condition].tsv`: A GSEA report table for each side of each contrast
   - `gprofiler2/`: Directory containing tables of differential gene set analyis from gprofiler2 (where enabled)

docs/usage.md

@@ -273,6 +273,24 @@ With this configuration in place deployment should happen automatically every ti
 
 There is also a [Shiny server application](https://posit.co/download/shiny-server/), which you can install on your own infrastruture and use to host applications yourself.
 
+## Immunedeconv
+
+[Immunedeconv](https://omnideconv.org/immunedeconv/index.html) is a computational tool designed to estimate the proportions of immune cell types in bulk transcriptomic data. It leverages established deconvolution algorithms, such as CIBERSORT, EPIC, and xCell, to provide insights into the immune landscape of a given dataset.
+
+This tool is turned off by default, to turn it on set the parameter `--immunedeconv_run` to true. Also make sure that the parameters `--immunedeconv_method` and `--immunedeconv_function` are populated with the desired method and function to run this tool. Default values for these two are quantiseq and deconvolute, respectively. If you want to see the full list of available methods and functions, refer to the tool's [official guide]("https://omnideconv.org/immunedeconv/articles/immunedeconv.html").
+
+For a better understanding on how these parameters affect the module's execution, this is how the parameters are used in the tool:
+
+```bash
+result <- immunedeconv::${function}(gene_expression_matrix, method = '$method')
+```
+
+The default parameters will produce a line that looks like this:
+
+```bash
+result <- immunedeconv::deconvolute(gene_expression_matrix, method = 'quantiseq')
+```
+
 ## Gene set enrichment analysis
 
 Currently, two tools can be used to do gene set enrichment analysis.