Merge pull request #510 from antoniasaracco/decoupler_2

Add Decoupler

Author: antoniasaracco

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+-[[#510]](https://github.com/nf-core/differentialabundance/pull/510) - Add decoupler module to differential functional enrichment subworkflow. ([@antoniasaracco](https://github.com/antoniasaracco), review by [@pinin4fjords](https://github.com/pinin4fjords) and [@grst](https://github.com/grst)).
+
 - [[#473](https://github.com/nf-core/differentialabundance/pull/473)] - Allow formula-based contrasts in DESEQ2. ([@atrigila](https://github.com/atrigila), review by [@pinin4fjords](https://github.com/pinin4fjords) and [@grst](https://github.com/grst)).
 - [[#443](https://github.com/nf-core/differentialabundance/pull/443)] - Add toolsheet-related implementations. ([@suzannejin](https://github.com/suzannejin), review by [@pinin4fjords](https://github.com/pinin4fjords), [@mirpedrol](https://github.com/mirpedrol) and [@JoseEspinosa](https://github.com/JoseEspinosa))
 - [[#450](https://github.com/nf-core/differentialabundance/pull/441)] - Allow usage of strings for makeContrasts in DREAM. ([@atrigila](https://github.com/atrigila), review by [@pinin4fjords](https://github.com/pinin4fjords), [@suzannejin](https://github.com/suzannejin) and [@grst](https://github.com/grst)).

conf/modules.config

@@ -464,6 +464,34 @@ process {
         ].join(' ').trim() }
     }
 
+    withName: DECOUPLER_DECOUPLER {
+        ext.prefix = {
+            def method = meta.params.differential_method ?: meta.differential_method ?: "unknown"
+            def prefix = "${method}_${meta.id}"
+            return prefix
+        }
+        ext.args = {
+            def features_id = meta.params?.features_id_col ?: 'gene_id'
+            def features_symbol = meta.params?.features_name_col ?: 'gene_name'
+            def min_n = meta.params?.decoupler_min_n ?: 5
+            def methods = meta.params?.decoupler_methods ?: 'mlm'
+
+            "--min_n ${min_n} --transpose TRUE --ensembl_ids TRUE --methods ${methods} --features_id_col ${features_id} --features_symbol_col ${features_symbol} --column ${params.differential_fc_column}"
+        }
+        publishDir = [
+            [
+                path: { "${params.outdir}/tables/decoupler" },
+                mode: params.publish_dir_mode,
+                pattern: '*.tsv'
+            ],
+            [
+                path: { "${params.outdir}/plots/decoupler" },
+                mode: params.publish_dir_mode,
+                pattern: '*_estimate_decoupler_plot.png'
+            ]
+        ]
+    }
+
     // ==================================================================================
     // plotting and reports
     // ==================================================================================

conf/test.config

@@ -55,4 +55,8 @@ params {
 
     // Other
     round_digits = 3
+
+    // DECOUPLER
+    decoupler_network     = 'https://github.com/nf-core/test-datasets/raw/differentialabundance/modules_testdata/progeny/mouse_network.tsv'
+
 }

conf/test_rnaseq_dream.config

@@ -55,4 +55,7 @@ params {
 
     // Other
     round_digits = 3
+
+    // DECOUPLER
+    decoupler_network     = 'https://github.com/nf-core/test-datasets/raw/differentialabundance/modules_testdata/progeny/mouse_network.tsv'
 }

conf/test_rnaseq_limma.config

@@ -61,4 +61,7 @@ params {
 
     // Other
     round_digits = 3
+
+    // DECOUPLER
+    decoupler_network     = 'https://github.com/nf-core/test-datasets/raw/differentialabundance/modules_testdata/progeny/mouse_network.tsv'
 }

docs/output.md

@@ -49,8 +49,8 @@ Stand-alone graphical outputs are placed in this directory. They may be useful i
     - `[contrast]/[norm_function].normalized_mean_variance_relationship.png`: Plots of log intensity vs mean log intensity after normalization of each contrast level.
     - `[contrast]/[norm_function].normalized_distributions.png`: A plot of sample distributions after normalization.
     - `[contrast]/raw_distributions.png`: A plot of sample distributions without normalization.
-
-</details>
+  - `decoupler/`: Directory containing plots of decoupler results - `[differential_method]_[contrast_name]_[decoupler_method]_estimate_decoupler_plot.png`: contains the plot for the estimated activity scores for each regulator (rows) across all samples (columns).
+  </details>
 
 Most plots are included in the HTML report (see above), but are also included in static files in this folder to facilitate use in external reporting.
 
@@ -78,6 +78,9 @@ Most plots are included in the HTML report (see above), but are also included in
   - `gprofiler2/`: Directory containing tables of differential gene set analyis from gprofiler2 (where enabled)
     - `[contrast]/[contrast].gprofiler2.all_enriched_pathways.tsv`: A gprofiler2 report table for all enrichment results
     - `[contrast]/[contrast].gprofiler2.[source].sub_enriched_pathways.tsv`: A gprofiler2 report table of enriched pathways from one specific source/database, e.g. REAC
+  - `decoupler/`: Directory containing tables of decoupler results
+    - `[differential_method]_[contrast_name]_[decoupler_method]_estimate_decoupler.tsv`: contains the estimated activity scores for each regulator (rows) across all samples (columns).
+    - `[differential_method]_[contrast_name]_[decoupler_method]_pvals_decoupler.tsv`: contains the associated p-values for those activity scores, when the method supports statistical significance estimation.
   - `proteus/`: If `--study_type maxquant`: Directory containing abundance values produced by the proteus module which is used for processing MaxQuant input. Files are prefixed with the associated contrast and chosen normalization function (if any).
     - `[contrast]/[norm_function].normalized_proteingroups_tab.tsv`: Abundance table after normalization.
     - `[contrast]/raw_proteingroups_tab.tsv`: Abundance table without normalization.

docs/usage.md

@@ -410,6 +410,53 @@ By default the analysis will be run with a background list of genes that passed
 
 Check the [pipeline webpage](https://nf-co.re/differentialabundance/parameters#gprofiler2) for a full listing of the relevant parameters.
 
+### Decoupler
+
+[Decoupler](https://decoupler-py.readthedocs.io/en/latest/index.html) `decoupler.decouple` is a Python function that infers biological regulator activities—such as transcription factor or pathway activity—from omics data using multiple statistical enrichment methods. It takes as input a gene expression matrix and a prior knowledge network linking regulators to target genes, and applies one or more methods (e.g., ULM, MLM, wsum) to estimate regulator activity scores across samples. The function supports optional consensus scoring and outputs method-specific activity estimates and p-values, making it a versatile tool for activity inference in both bulk and single-cell datasets. If you want to see the full list of available methods and functions, refer to the functions's [official guide]("https://decoupler-py.readthedocs.io/en/latest/generated/decoupler.decouple.html#decoupler.decouple").
+
+This tool is turned off by default, to turn it on set the parameter `functional_method` to `decoupler`.
+
+#### Input Files
+
+Decoupler needs a matrix (mat) of molecular readouts (gene expression, logFC, p-values, etc.) and a network (net) that relates target features (genes, proteins, etc.) to “source” biological entities (pathways, transcription factors, molecular processes, etc.).
+
+- The matrix will be taken from the results of the differential expression analysis performed by DESeq2, limma, propr, or variancePartition.
+
+- The network file must be provided explicitly via the '--decoupler_network' parameter. This file should be in long format and contain at least the source and target columns, with optional weight and sign columns describing the strength and direction of each interaction.
+
+#### Parameters
+
+The Decoupler module includes a min_n parameter to fine-tune its behavior.
+
+- `--decoupler_min_n`: This parameter controls the minimum number of targets a regulator (source) must have in the network to be included in the analysis. Any regulator with fewer than min_n targets will be removed from the network before activity inference is performed.
+
+By default, `--decoupler_min_n` is set to 5, meaning all sources with at least one target will be evaluated. You can increase this value to filter out poorly supported regulators and reduce noise.
+
+Example: setting `--decoupler_min_n 5` will ensure that only regulators with at least 5 target genes are considered.
+
+- `--decoupler_methods`: This parameter lets you specify which statistical methods decoupler will use to estimate regulator activities. Decoupler supports multiple methods, each using a different algorithm or statistical approach. You can specify one or more methods by passing them as a comma-separated list.
+
+Example: `--decoupler_methods` mlm,ulsm
+
+##### Network Sources
+
+You can obtain regulatory networks from well-established databases and tools. Common examples include:
+
+- DoRothEA – transcription factor-target interactions (TFs) [DoRothEA](https://www.bioconductor.org/packages/release/data/experiment/html/dorothea.html)
+
+- CollecTRI – curated transcriptional regulatory interactions (TFs) [CollectTRI] (https://github.com/saezlab/CollecTRI)
+
+- PROGENy – pathway-responsive gene signatures (pathways) [PROGENy] (https://saezlab.github.io/progeny/)
+
+If you want to see the full list of available methods and functions, refer to the functions's [official guide] (https://decoupler-py.readthedocs.io/en/latest/notebooks/benchmark.html#Multiple-networks).
+
+**Note**: Then resources mentioned above are provided only for human or mouse datasets. Please ensure your organism is compatible before enabling this module or provide a custom, species-specific dataset.
+
+```bash
+--functional_method decoupler \
+--decoupler_network network.tsv
+```
+
 ## Running the pipeline
 
 The typical command for running the pipeline is as follows:

modules.json

@@ -40,6 +40,11 @@
                         "git_sha": "100b1dc1ece11cf8d4fec100314d616a66a60875",
                         "installed_by": ["differential_functional_enrichment"]
                     },
+                    "decoupler/decoupler": {
+                        "branch": "master",
+                        "git_sha": "202bddf7ffabd0d53e4c0ecc6b1ab526020a9744",
+                        "installed_by": ["differential_functional_enrichment"]
+                    },
                     "deseq2/differential": {
                         "branch": "master",
                         "git_sha": "2e24bf8b6b045e1cf56a2907306b008113a686d0",
@@ -141,7 +146,7 @@
                     },
                     "differential_functional_enrichment": {
                         "branch": "master",
-                        "git_sha": "4006954b7bfbbc61c7d5fb009319ed536d2ffca4",
+                        "git_sha": "202bddf7ffabd0d53e4c0ecc6b1ab526020a9744",
                         "installed_by": ["subworkflows"]
                     },
                     "utils_nextflow_pipeline": {