NetDecoder Protocol for Building Context-Specific Protein Interaction Networks from Transcriptomic Data Using Information Flow Modeling

Summary

Here, we present a protocol for using NetDecoder, a network modeling tool, to construct context-specific protein interaction networks and build gene utility models (GUMs). Using transcriptomics data, in combination with curated protein-protein interaction (PPI) networks, NetDecoder enables the identification of key targets and subnetworks.

Abstract

Differential expression analysis is a commonly used technique for determining potential therapeutic targets, but it overlooks the complexity of gene networks across biological pathways. Often, highly expressed genes do not necessarily explain the properties of a biological phenotype. NetDecoder, a network biology tool that integrates transcriptomic data with protein-protein interaction (PPI) networks to model context-specific information flow, gene utility, and key edges and differentially utilized gene networks, was developed to address this limitation of differential expression analysis.

This protocol is a beginner-friendly, step-by-step guide to using NetDecoder, with comprehensive guidelines spanning data preprocessing, NetDecoder execution, and analysis of outputs. The workflow includes software configuration, network construction, and flow-based modeling analysis to quantify gene (node) and gene-gene interaction (edge-level) differences between biological conditions. The resulting outputs include key targets and routers, differential flow subnetworks, and edge flow distributions, enabling identification of key regulatory genes and pathways associated with specific biological states. After following the outlined steps, researchers will be able to conduct independent research to uncover phenotypic gene flow across phenotypes using transcriptomic data and curated PPI networks.

Introduction

The selection of genes and associated pathways for therapeutic investigation is often driven by differential expression analyses¹. This analysis method is effective at determining how gene expression differs between two or more conditions. However, genes function within complex, interconnected biological networks, meaning that individual gene expression does not fully capture how genes interact in a network and their gene-gene relationships². Network propagation methods integrate gene expression with interaction networks to identify biologically important genes that might be missed by differential expression alone³. Current approaches do not explicitly quantify the functional importance of genes and how biological information is redistributed within protein-protein interaction (PPI) networks across biological conditions. Therefore, a method for modeling condition-specific network behavior and quantifying changes in information flow across biological systems was needed. To account for how genes interact within a broader biological network, NetDecoder, a network biology platform, was developed to uncover genes with the greatest information flow difference between conditions. NetDecoder uses a process-guided flow algorithm to translate existing knowledge of the human PPI network, in combination with bulk RNA sequencing data, to construct a model of information flow-driven interactions⁴.

Using information flow data for phenotypic networks, a gene utility model (GUM)⁵ can be developed to identify genes with high information flow as having the highest overall gene utility within a network, regardless of their differential expression values. This approach supports more effective target prioritization strategies and identification, providing insights that traditional analysis often misses. Unlike traditional differential expression or correlation-based network methods, NetDecoder quantifies both gene (node-level) and interaction (edge-level) changes in information flow, enabling the identification of functionally important genes, even in the absence of large expression changes^4,5. NetDecoder is widely applicable to bulk RNA sequencing datasets that involve comparative analysis between two biological conditions, enabling the identification of changes in information flow and network organization. Although NetDecoder supports integration of other omics datasets, including proteomics and epigenomics, the present protocol specifically demonstrates the workflow using transcriptomic data. In these applications, users can define source genes based on proteins or epigenetically regulated genes, allowing information flow analysis to be initiated from these molecular features. This flexibility enables the incorporation of multi-omics evidence into network-based analyses and facilitates the discovery of cross-modal regulatory mechanisms underlying phenotypic differences.

Common study designs involve binary comparisons, including but not limited to disease versus healthy conditions, treatment responders vs non-responders, drug treatments, knockdowns or knockouts versus control experiments, and analyses of developmental or cellular state transitions. The goal of this protocol is to illustrate a reproducible framework for applying NetDecoder to uncover genes with altered network influence across biological conditions. This is achieved through easy-to-follow steps for setting up and running NetDecoder, as well as examples to follow along with basic troubleshooting techniques, and methods for result interpretation are also laid out in the protocol.

Protocol

This study used publicly available RNA sequencing datasets and did not directly involve human or animal subjects. Therefore, institutional review board approval and informed consent were not required.

NOTE: NetDecoder requires the following input files: normalized gene expression across two defined biological conditions; a metadata file describing the biological conditions; a list of source genes for network building and modeling; a protein-protein interaction (PPI) network from the public domain; and an edge-weighted network (EWN) built for each biological condition.

1. Data preparation

1. Retrieve bulk RNA sequencing expression data and metadata
   1. Download RNA sequencing data (matrix of raw gene expression counts and sample names) and corresponding metadata (sample names, conditions, etc.) from a public repository, such as the Gene Expression Omnibus (GEO), or use lab-generated experimental datasets. Typically, this is a matrix in which rows correspond to gene names and columns correspond to sample names.
      NOTE: The example dataset used to demonstrate this protocol was obtained from the National Omics Data Encyclopedia (NODE) repository (BioSino database) under accession OEP001105⁶. Users may substitute their own bulk RNA sequencing datasets.
   2. Generate a sample annotation file (metadata) by including sample names and their groups or associated conditions; for example, “control” and “disease” are common condition types. Confirm that the sample names match between the metadata and expression files.
2. Aggregate expression data and metadata
   1. Ensure that the generated data matrix includes expression counts, gene names, and a metadata file with sample names and conditions. If necessary, use an R package such as org.Hs.eg.db (human) or AnnotationDbi to match different gene identifiers.
   2. Trim out non-essential information from the metadata file using R or a similar programming language.
   3. Combine the information from the expression count files into a single file for easy manipulation.
3. Filter expression data
   1. Pre-process the gene expression data matrix by excluding gene duplicates, null values (NA), low expression (<10 total counts), and/or low variance genes, etc.
4. Data pre-processing
   1. RNA sequencing normalization and differential expression analysis
      NOTE: This step is one (1.4.1) of two (1.4.2) approaches for selecting genes for Edge Weighted Network (EWN) creation and source gene selection (steps 1.5–1.6) when beginning the analysis from bulk RNA sequencing data. As an alternative, Pearson correlation-based template matching may be utilized by skipping ahead to step 1.4.3.
      1. Perform Gene ID conversions at this stage using the R package, AnnotationDbi, in concurrence with individual organism packages. NetDecoder uses gene symbols (i.e., Gene ID) that match the example PPI.
      2. Perform normalization and differential expression analysis between two conditions using the R packages limma, edgeR, DESeq2, or comparable tools.
      3. If using DESeq2, construct a DESeq dataset using the DESeqDataSetFromMatrix() function with a count matrix (genes and samples) and sample metadata (conditions) as input.
      4. Use the DESeq() function with default settings on the object created in step 1.4.1.3 to compute differential expression values.
      5. Save the results in a data matrix with gene identifiers (Gene ID) as row names and key outputs including log2 fold change (log2FC), p-value, and adjusted p-value as columns.
      6. Optionally, filter the results by adjusted p-value (<0.05) and/or log2FC values (for example: |log2FC| > 1) using dplyr or a comparable tool.
      7. Ensure that all processed gene lists and log2 fold change matrices are exported as tab-delimited (.txt or .csv) files for input into NetDecoder.
      8. Perform pairwise comparisons for step 1.4.1 if more than 2 biological conditions are used and obtain pairwise results using the results() function from the DESeq object generated in step 1.4.1.5.
   2. Microarray expression normalization - Optional
      NOTE: If using microarray data, perform this step for data normalization.
      1. Normalize data by opening the NetDecoder normalization script (HuLiLab/NetDecoder_Example/raw_data/NetDecoder_normalize.R), accessible from https://github.com/HuLiLab/NetDecoder_Example/tree/main, in an R-development platform and edit the italicized portion to match the working directory containing cell intensity files (CEL).
         setwd(~/NetDecoder_Example/raw_data/CEL_files)
   3. Template matching - Optional
      NOTE: This is the second optional approach if differential expression analysis (as laid out in steps 1.1–1.4.1 of “Data Preparation”) is not conducted.
      1. For RNA sequencing data not processed through limma, edgeR, and DESeq2, perform normalization externally before applying template matching. For microarray data, use the normalized expression values generated in steps 1.1–1.4.2 directly.
      2. Choose the control condition as the baseline template for gene expression and compare normalized gene expression values from all other conditions of interest.
      3. Calculate Pearson correlation coefficients between each gene's expression profile and the selected template. It is recommended to retain genes exhibiting statistically significant correlations (p < 0.05) and an absolute correlation coefficient above a user-defined threshold (such as |r| > 0.7).
5. Selection of source genes
   NOTE: The input for this step consists of the normalized gene expression matrix developed in steps 1.1–1.4.
   1. Choose a set of significant genes to be used as source genes. For differential expression-based workflows, choose adjusted p-value and log2FC thresholds (such as adj p-value < 0.05 and |log2FC| > 2). For template-matching workflows, select source genes from the significantly correlated genes identified in step 1.4.3.3 using the chosen correlation and significance thresholds. Thresholds should be chosen to yield approximately 300–1,000 genes for downstream network construction.
      NOTE: Source genes are where the information flow starts and propagates through the network.
6. Build an edge weighted network (EWN) for each phenotype
   NOTE: The following inputs are required for this step: the normalized gene expression matrix developed in steps 1.1–1.4; a protein-protein interaction (PPI) network formatted as an edge list (geneA-geneB pairs); a sample annotation file (metadata) specifying biological condition labels for each sample. The PPI network is shared as an R object and was constructed based on the iRefIndex protein database. The version used in this protocol includes all direct interactions, but self-loops and multiple edges were excluded. The PPI network contains 15,608 proteins and 180,044 interactions. For additional details, see the NetDecoder-Methods section⁴.
   1. Open the NetDecoder Edge Weighted Network (EWN) script (HuLiLab/NetDecoder_Example/input/NetDecoder_Create_EWN.R, accessible from https:/github.com/HuLiLab/NetDecoder_Example/tree/main)⁴, in an R-development platform.
   2. Edit the portions of the script, indicated by comments (and italicized below), to set user-specific paths and input files for EWN development.
      path<~/NetDecoder_Example/input/
      This is the path to the working directory
      expQuery <- get(load("expBreastCancer_15Set2014.R"))
      This is an example of a normalized expression matrix Rdata object
      stQuery < read.csv(“stBreastCancer.csv")
      This is the sample metadata
   3. Filter the expression matrix to retain only genes present in the PPI network.
   4. For each condition, subset samples by phenotype and compute pairwise gene-gene correlations across all edges defined in the PPI network using Pearson correlation. Calculate the correlations using the processed, normalized expression matrix generated in step 1.4.
   5. For each gene pair, calculate the correlation coefficient, absolute correlation, and associated p-value.
   6. Remove incomplete cases (e.g., NA values).
   7. Export one edge-weighted network per condition as a tab-delimited file (no header) with the following columns: proteinA, proteinB, abs_cor, cor, and pvalue.
   8. Execute the R script to create co-expression networks for all relevant conditions.

2. Installing and Configuring NetDecoder

1. Download NetDecoder
   1. Access the NetDecoder software at (https://netdecoder.hulilab.org/#ver), choosing R or Java.
2. Install required software
   1. Install Oracle JDK and R for working/analysis environments.
   2. Install required R packages as listed in the NetDecoder documentation, using Bioconductor (https://netdecoder.hulilab.org/#ver)⁴.
3. Download dependencies
   1. Download the necessary dependencies for NetDecoder, which include gene ontology data (accessible from https://geneontology.org/docs/download-ontology/), as well as the gene association reference guide (accessible from https://www.ebi.ac.uk/GOA/human_release).
4. Set up the working directory
   1. Move all downloaded files (expression data, generated co-expression networks for each condition, gene ontology data, and association reference guide) into one folder, which will be the NetDecoder working directory.
5. Add the necessary folder
   1. Download the NetDecoder folder (https://netdecoder.hulilab.org/wp-content/uploads/2025/07/NetDecoder_Example.zip) to the NetDecoder working directory.
   2. Unzip the NetDecoder folder.

3. Running NetDecoder

1. Open the analysis bash script
   1. Open a terminal running GNU Bash and navigate to the NetDecoder working directory.
   2. Run the command nano NetDecoder_Analysis.sh to open the bash script.
2. Modify the scripts
   NOTE: Most of the code is already written. In this step, the required parameters are specified in the script at the indicated locations.
   1. Make a short name:
      Edit the italicized portion to be the conditions being compared: myshortname=’Your_shortname_here’
   2. Set software paths:
      Edit the following three path definitions to the correct paths by editing the italicized portions:
      JAVA=“/your/path/here”
      export R=“/your/path/here”
      alias R=“/your/path/here”
   3. Set working directory:
      Edit the italicized portion to be the working directory where all files will be accessed from: INPUT_DIR=“/your/path/here”
   4. Set NetDecoder library:
      Edit the italicized portion to be the path to the NetDecoder library installed in step 2.4 from the zip file: LIB_DIR=“/your/path/here/netdecoder_lib”
   5. Set gene ontology and association paths:
      Edit the following italicized portions of the two directories to the locations of the preferred gene ontology/association files.
      SYMBOL=$LIB_DIR/gene_association_file
      GO=$INPUT_DIR/gene_ontology_file
   6. Set input arguments:
      Update the italicized portions of the following five lines according to the data, as per the commented instructions found in the reference NetDecoder script.
      geneList=$INPUT_DIR/gene_file
      state_trt=Treated Condition
      state_ref=Reference Condition
      PPI_trt=$INPUT_DIR/treated_co_expression_network_file
      PPI_ref=$INPUT_DIR/reference_co_expression_network_file
   7. Set the proper stage:
      Uncomment (by removing the # symbol) the desired stage of execution, and re-comment it once the stage is completed. Stage one is gen_net_trt, followed by gen_net_ref, then the analysis stage, and finally the collect stage.
      Set the desired stage to execute, beginning with stage one.
      #STAGE=“gen_net_trt”
      #STAGE=“gen_net_ref”
      #STAGE=“analysis”
      #STAGE=“collect”
   8. Navigate to the main Bash terminal:
      Press Ctrl+X, then Y, to save and exit the bash script.
3. Execute NetDecoder
   NOTE: If it runs successfully, logging messages appear in the terminal.
   1. Navigate to the terminal and run ./NetDecoder_Analysis.sh.
   2. Execute the stages in the order listed in step 3.2.7 until all four have been completed individually.
4. Retrieve results
   1. Navigate to the output files and graphical summaries.

Results

As shown in Figure 1, NetDecoder operates through a structured workflow consisting of data processing, network configuration, and flow-based analysis, with outputs organized into distinct directories corresponding to each stage of the pipeline. This modular structure enables systematic validation of outputs, ensuring that results can be traced back to each computational step and supporting overall reproducibility.

Successful execution of NetDecoder (

Discussion

This protocol outlines the implementation of NetDecoder, a network-biology framework that integrates gene expression data with protein-protein interaction (PPI) networks to model condition-specific information flow and prioritize genes based on their functional influence within biological systems. The successful application of this method depends on several critical steps, careful methodological choices, and proper interpretation of outputs.

The initial stages of the protocol include retrievin...

Materials

List of materials used in this article

Name	Company	Catalog Number	Comments
AnnotationDbi	Bioconductor	version 1.68.0	Annotation and gene mapping
Bioconductor	Bioconductor	version 3.19	Framework for transcriptomic data analysis and package ecosystem supporting DESeq2, edgeR, limma, AnnotationDbi, and organism databases, etc.
Cytoscape	The Cytoscape Consoritum	version 3.10.4	Network visualization and analysis
DESeq2	Bioconductor	version 1.46.0	Differential expression analysis (with negative binomial modeling)
dplyr	Posit Software, PBC formerly RStudio, PBC	version 1.1.4	Data manipulation and transformation
edgeR	Bioconductor	version 4.4.2	Count-based differential expression analysis
ggplot2	Posit Software, PBC formerly RStudio, PBC	version 4.0.0	Data visualization and plotting
GNU Bash	GNU Project	System default	Bash, Execution of NetDecoder pipeline scripts
igraph	igraph Development Team	version 2.1.4	Network construction and graph analysis
Limma	Bioconductor	version 3.62.2	Linear modeling for gene expression analysis
NetDecoder	Hu Li Laboratory, Mayo Clinic	(2024 Hu Li Lab)	Construction of context-specific protein interaction networks via information flow modeling
org.Hs.eg.db	Bioconductor	version 3.20.0	Human gene annotation database
Oracle JDK	Oracle Corporation	≥ version 1.8	Runtime environment for NetDecoder execution
pheatmap	Raivo Kolde	version 1.0.13	Visualization of expression and correlation structure
R	The R Foundation	version 4.4.2	Core environment for transcriptomic and network analysis