nf-core/diseasemodulediscovery

Edit

Introduction

This document describes the output produced by the pipeline. Most of the plots are taken from the MultiQC report, which summarises results at the end of the pipeline.

The directories listed below will be created in the results directory after the pipeline has finished. All paths are relative to the top-level results directory.

File naming

Many output files are named based on the combination of seed file, network file, disease module discovery method, and drug prioritization method used:

• <seeds>: The name of the input seed file without the file ending.
• <network>: The name of the input network file without the file ending.
• <amim>: The name of the disease module discovery method (active module identification method (AMIM)).
• <drug_algorithm>:: The name of the drug prioritization algorithm.

Pipeline overview

The pipeline is built using Nextflow and processes data using the following steps:

• Input preparation
  • Prepare network
  • Check seed file
• Disease module inference
  • Only seeds
  • DOMINO
  • DIAMOnD
  • ROBUST
  • ROBUST (bias aware)
  • RWR
  • 1st Neighbors
• Disease module evaluation
  • g:Profiler
  • DIGEST
  • Network topology
  • Overlap
  • Seed permutation
  • Network permutation
• Drug prioritization
  • Drugst.One
• Other
  • Drugst.One export
  • Network visualization
  • Annotation
• Reporting
  • MultiQC - Aggregate report describing results and QC from the whole pipeline
• Pipeline information - Report metrics generated during the workflow execution

Input preparation

Prepare network

The graph-tool library is used to parse the input network(s) into the .gt format, the internal representation used for networks within the pipeline. Additionally, it is used to generate networks in the specific formats required by the various disease module inference methods. This step also gathers summary statistics for the MultiQC report, including the number of nodes and edges, the network diameter, the number of connected components, the size of the largest connected component, the count of self-loops (nodes with edges to themselves), and the number of duplicate edges (multiple edges connecting the same two nodes).

Check seed file

The format of the input seed file(s) is validated, and any seed nodes not present in the corresponding input network are removed. The filtered seed file(s) are then used in subsequent pipeline steps, and a summary of retained and discarded seed nodes is included in the MultiQC report.

Disease module inference

The inferred disease modules are exported in multiple formats, including .gt, .graphml, and node and edge lists in .tsv. If a method returns only a node list rather than a full network, the connecting edges are extracted from the input network. Module nodes are annotated with their seed status (is_seed), their subnetwork participation degree (spd), and a component identifier (component_id) to indicate which connected component they belong to. Additionally, tool-specific node properties are added, which are explained in the sections below.

Only seeds

In addition to the inferred disease modules, the pipeline provides a dummy module inference method that returns only the seed nodes and the edges connecting them in the input network. This serves as a baseline, enabling comparisons between modules containing additional nodes and the core set of seed nodes.

DOMINO

DOMINO starts by partitioning the input network into disjoint slices using Louvain clustering. Slices that are enriched for seed nodes, as determined by a hypergeometric test, are selected for further analysis. The selected slices are refined by solving the Prize Collecting Steiner Tree (PCST) problem, and subsequently subdivided into putative modules containing no more than 10 nodes each. Each resulting module is then tested again for seed enrichment using a hypergeometric test. DOMINO can produce multiple non-overlapping modules for a single input seed set. The pipeline reports all modules in a single output file, with individual modules distinguished by the node property submodule.

DIAMOnD

DIAMOnD iteratively expands the initial set of seed nodes by adding one node at a time. At each step, the algorithm selects the node with the highest connectivity significance to the current seed set, as determined by a hypergeometric test. This process continues until a predefined number of nodes have been incorporated. DIAMOnD itself only returns the nodes added to the module, which is why the pipeline adds the seed nodes to the module at the end. DIAMOnD returns only the nodes added to the module, so the pipeline appends the original seed nodes to the module at the end. Each node is annotated with the order in which it was added (rank) and the corresponding hypergeometric test p-value (p_hyper). Both values are 0 for seed nodes.

ROBUST

ROBUST repeatedly connects seed nodes by solving the Prize Collecting Steiner Tree (PCST) problem. In each iteration, nodes that were included in previous solutions are penalized, lowering their chance of being selected again. The final disease module consists of nodes that appear in a sufficient number of solutions, enhancing robustness. ROBUST annotates module nodes with a connected component ID (connected_components_id), seed status (isSeed), the number of solutions the node participated in (nrOfOccurrences), the fraction of all solutions the node appeared in (significance), and the list of trees the node was part of.

ROBUST (bias aware)

ROBUST (bias aware) follows the same strategy as ROBUST but increases edge costs for nodes that are frequently used as baits in PPI detection experiments. This penalization helps to mitigate study bias present in current PPI networks. The added node annotations are the same as for ROBUST.

RWR

1st Neighbors

1st Neighbors includes all network nodes that are directly connected to at least one seed node.

Disease module evaluation

g:Profiler

g:Profiler is used via the R package gprofiler2 to perform over-representation analysis (ORA), i.e., to find gene sets of pathways in which the module nodes are enriched. For this, the module nodes are used as foreground, and all nodes of the corresponding input network as background.

DIGEST

DIGEST is a tool designed to evaluate the functional coherence of disease modules. It assumes that genes within a module should participate in related biological processes, as indicated by annotations from Gene Ontology (GO) — including Biological Process (GO.BP), Cellular Component (GO.CC), and Molecular Function (GO.MF) — as well as from KEGG pathways.

DIGEST is executed in two modes:

• Reference-free mode (subnetwork) – evaluates the functional coherence among all genes in the module.
• Reference-based mode (subnetwork-set) – compares the coherence of the original seed genes with the genes added during module expansion.

Both modes use Jaccard similarity to measure functional overlap and generate 1,000 random modules from the input network(s) to perform permutation-based significance testing. The resulting empirical p-values are summarized in the MultiQC report.

Network topology

The graph-tool library is used to compute summary statistics describing the topology of the disease modules. These include the number of nodes and edges, the count of the included seed nodes, the diameter, the number of connected components, the size of the largest component, the number of isolated nodes (nodes without edges), and the maximum shortest-path distance from any added node to its nearest seed node. These statistics are summarized in the General Statistics section of the MultiQC report.

Overlap

The pipeline calculates pairwise overlaps between the node sets of all modules to assess similarities between different seed sets, networks, or methods. For each pair of modules, it reports both the number of shared nodes between their node sets (A ∩ B) and their Jaccard similarity (|A ∩ B| / |A ∪ B|). To specifically assess similarities among the added nodes, the same measures are also computed on the sets A \ S and B \ S, where S denotes the set of seed nodes. The overlaps are visualized as heatmaps in the MultiQC report.

Seed permutation

If provided with the --run_seed_permutation parameter, the pipeline runs a leave-one-out analysis to check how robust a module discovery method is against small changes in the seed set and to calculate a rediscovery rate. Starting with the original seed set, the pipeline creates new versions of the set by leaving out one seed at a time. For each of these perturbed seed sets, a new disease module is inferred using the same method.

Robustness

Each perturbed module is compared to the original module to see how similar they are, using the Jaccard index (|A ∩ B| / |A ∪ B|) of the node sets. The higher the Jaccard similarities, the more robust the module is to small input perturbations.

The corresponding distribution, as well as its mean value, is part of the MultiQC report.

Rediscovery rate

This procedure also allows calculation of a seed rediscovery rate — the likelihood that a left-out seed is added back into the resulting module. This metric reflects how well the method can recover disease-associated genes or proteins that were not provided in the input. On the other hand, if the rediscovery rate is consistently low across different methods, it may indicate that the left-out seed has weak or uncertain relevance.

Because larger modules are more likely to include an omitted seed by chance, the normalized rediscovery rate is adjusted for module size, i.e., divided by the number of nodes in the original module. This makes the rediscovery measure fairer and easier to compare across different modules.

Both normalized and raw rediscovery rates are summarized in the General Statistics section of the MultiQC report.

Network permutation

Use the --run_network_permutation option to repeatedly rewire the edges of the input network while preserving each node’s degree. The pipeline then reruns the module identification methods on these permuted networks.

The network rewiring is performed using the graph-tool function random_rewire with "constrained-configuration" as model and 100 full sweeps over all edges.

If the resulting modules are similar to those from the original network (indicated through a high Jaccard index), this indicates that the methods rely mainly on node degree rather than on the specific edge connections.

The corresponding distribution, as well as its mean value, is part of the MultiQC report.

Drug prioritization

Drugst.One

The Drugst.One Python package identifies potential drug candidates targeting nodes in the disease modules. To prioritize these compounds, different algorithms are available:

• Degree centrality – ranks compounds by the number of module nodes they target.
• Harmonic centrality – considers the average shortest path from each compound to all module nodes.
• TrustRank – uses network propagation to rank compounds based on their relevance within the network.

More details on these algorithms are available in the supplementary material of the Drugst.One publication.

Other

Drugst.One export

The MultiQC report lists export links for each disease module to visualize and manipulate them directly through the Drugst.One web interface.

Network visualization

Visual network representations of the inferred modules — both with and without assigned drugs — are generated using the graph-tool package and are available in PNG, SVG, and PDF formats. Additionally, interactive HTML visualizations are produced using the pyvis package. Coloring distinguishes seed nodes from the added module nodes.

Annotation

The disease modules are annotated with supplementary biological information queried from NeDRex database. The annotated modules are saved using BioPax, short for Biological Pathway Exchange. BioPax is a standard language and format for representing biological pathway knowledge. The format of the files is validated using the BioPax Validator.

The resulting files have the following structure:

Entities

• Proteins with UnificationXref and ProteinReference
• Genes with UnificationXref
• SmallMolecules as drugs with UnificationXref and SmallMoleculeReference

Relationships

• Protein encoded by gene as RelationshipXref
• Gene associated with disorder as RelationshipXref
• Drug targets protein as RelationshipXref
• Drug has side effects as RelationshipXref
• Protein is in a cellular component as RelationshipXref

Interactions

• Protein interactions as MolecularInteraction

Reporting

MultiQC

MultiQC is a visualization tool that generates a single HTML report summarising all samples in your project. Most of the pipeline QC results are visualised in the report and further statistics are available in the report data directory.

Results generated by MultiQC collate pipeline QC from supported tools e.g. FastQC. The pipeline has special steps which also allow the software versions to be reported in the MultiQC output for future traceability. For more information about how to use MultiQC reports, see http://multiqc.info.

Pipeline information

Nextflow provides excellent functionality for generating various reports relevant to the running and execution of the pipeline. This will allow you to troubleshoot errors with the running of the pipeline, and also provide you with other information such as launch commands, run times and resource usage.