Description

Here we introduce NetColoc, a tool which evaluates the extent to which two gene sets are related in network space, i.e. the extent to which they are colocalized in a molecular interaction network, and interrogates the underlying biological pathways and processes using multiscale community detection.

This framework may be applied to any number of scenarios in which gene sets have been associated with a phenotype or condition, including rare and common variants within the same disease, genes associated with two comorbid diseases, genetically correlated GWAS phenotypes, GWAS across two different species, or gene expression changes after treatment with two different drugs, to name a few. As of v1.1.0, relevant scores can be included for genes within each gene set.

NetColoc relies on a dual network propagation approach to identify the region of network space which is significantly proximal to both input gene sets, and as such is highly effective for small to medium input gene sets.

Installation

NetColoc is available on PyPI

pip install netcoloc

pip install netcoloc==1.0.0

pip install netcoloc==0.1.6

git clone git@github.com:ucsd-ccbb/NetColoc.git
git checkout -b v0.1.6 tags/v0.1.6

Documentation

For a quick-start on NetColoc’s functionality, please see the example notebooks.

Usage Note: Please follow steps in example notebooks for correct usage of NetColoc. At this time, not all individual functionalities have been tested for independent use.

Dependencies

NetColoc requires the following python packages (automatically installed via pip install netcoloc)

• click >=6.0

• matplotlib

• ndex2

• networkx >=2.0,<3.0

• numpy

• seaborn

• tqdm

• mygene >= 3.2.2

• scipy >= 1.5.3

• statsmodels

• gprofiler-official >= 1.0.0

• ipywidgets

• ipycytoscape

• ipykernel

• obonet

• cdapsutil

License

• Free software: MIT license

Citing NetColoc

Rosenthal, Sara Brin, Sarah N. Wright, Sophie Liu, Christopher Churas, Daisy Chilin-Fuentes, Chi-Hua Chen, Kathleen M. Fisch, Dexter Pratt, Jason F. Kreisberg, and Trey Ideker. “Mapping the common gene networks that underlie related diseases.” Nature protocols (2023): 1-15. https://doi.org/10.1038/s41596-022-00797-1

Other publications utilizing NetColoc:

• Rosenthal, S. B. et al. A convergent molecular network underlying autism and congenital heart disease. Cell Syst. 12, 1094-1107.e6 (2021). 10.1016/j.cels.2021.07.009

• Wright, S. N. et al. Genome-wide association studies of human and rat BMI converge on synapse, epigenome, and hormone signaling networks. Cell Rep. 42, 112873 (2023). 10.1016/j.celrep.2023.112873

• Wright, S. N. et al. Common and rare genetic variants show network convergence for a majority of human traits. EMBO Reports (2026)

Credits

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

1.1.1 (2026-09-09)

• Fixed bug in the utility class Seeds. Now allows passing of non-default columns names for seed gene files.

1.1.0 (2026-09-09)

• Added functionality for quantitative NetColoc, allowing direct analysis of scored gene sets. Including: the class Seeds in netcoloc_utils to manage import and manipulation of scored gene sets, scored_network_propagation in netprop to perform propagation with weighted seeds, calculate_scored_heat_zscores and associated functions in netprop_zscore to calculate associated z-scores using randomized inputs with matched degree-score correlation.

• Added example_notebook/Quantitative_NetColoc_QNetColoc_example.ipynb to demonstrate the usage of quantitative NetColoc

• Updated numpy requirement to numpy>=2.0.0

• Added support for python=3.14

1.0.0 (2026-02-10)

• obonet added as a dependency, replacing DDOT dependency

• cdapsutil added as a dependency

• network_colocalization updated for compatability with pandas>=2.0

• validation updated for compatability with obonet. Added validation.focus_ontology() to replace ddot.Ontology.focus() functionality, and validation.find_related_terms() and validation.get_MP_description() for analyzing Mammalian Phenotype Ontology terms.

• example_notebooks updated for compatibility with pandas>=2.0 and obonet

• validation.load_MGI_mouseKO_data() and validation.load_MPO() updated to allow re-use of previously downloaded files

• Added ability to map genes via the MGI database in validation.load_MGI_mouse_KO_data()

• Added functions to map genes to the ontology and restrict to a subset of genes (validation.map_genes_to_MPO())

• Stabilized network_colocalization to accept pd.Series, pd.DataFrame and np.ndarray inputs

• Added support for overlapping sets of seed genes in network_colocalization.calculate_expected_overlap(), with option to remove the overlapping genes from the analysis, or randomize within the overlapping seed genes.

• Added function network_colocalization.get_p_from_permutation_results() to calculate P-value from Z-test of observed vs permuted results.

• Added function network_colocalization.calculate_mean_z_score_distribution() to analyze mean netcoloc z-scores in addition to the size of the colocalized network.

• requirements_dev.txt updated for python>=3.13

• Expanded unit tests for netcoloc_utils, netprop, netprop_zscore, network_colocalization and validation modules

• Deprecated support for python=3.8. Netcoloc v1.0.0 requires python>=3.9

0.1.7 (2022-06-28)

• Removed unused network_localization.py module

0.1.6 (2022-06-16)

• ipycytoscape added as a dependency

• ipywidgets added as a dependency

• Added network_colocalization.sweep_input_pvals() to sweep p-values and scores

• Added network_colocalization.calculate_network_enrichment() to sweep over z-score thresholds

• netprop.get_individual_heats_matrix() can take a networkx Graph object and internally call netprop.get_normalized_adjancency_matrix(). Documentation updated in both methods to note that the resulting matrices can be saved via numpy.save() and retrieved via numpy.load()

• example_notebooks/ASD_CHD_NetColoc_analysis.ipynb now visualizes hierarchy using ipycytoscape

• example_notebooks/ASD_CHD_NetColoc_analysis.ipynb updated with a note about using numpy.save() and numpy.load() to save and retrieve result from netprop.get_individual_heats_matrix()

0.1.5 (2022-03-09)

• Fixed divide by zero error seen when calculating cosine distance by updating netprop.get_normalized_adjancency_matrix() to properly normalize an adjacency matrix that is asymetric (UD-1863)

0.1.4 (2021-08-31)

• If import of DDOT package fails, only a warning message will be displayed unless user invokes netcoloc.validation.load_MPO() in which case an ImportError is raised

• Fixed bug where z1_threshold parameter was being passed to z2_threshold parameter in netcoloc.network_cololcalization.calcualte_network_overlap method called by netcoloc.network_colocalization.calculate_network_overlap_subgraph method

0.1.3 (2021-08-18)

• Added dependency gprofiler-official to setup.py and requirements.txt because this is used by network_colocalization.py

0.1.2 (2021-08-17)

• Added new validation.py module containing mouse knockout database functionality

0.1.1 (2021-08-06)

• Fixed netcoloc imports in netprop_zcore.py

0.1.0 (2021-03-10)

• First release on PyPI.