netcoloc 1.0.0
Analyze network colocalization of gene sets
License: MIT license
Requires Python: >=3.8
Keywords: netcoloc

===============================
NetColoc
===============================

.. image:: https://img.shields.io/pypi/v/netcoloc.svg
        :target: https://pypi.python.org/pypi/netcoloc

.. image:: https://app.travis-ci.com/ucsd-ccbb/NetColoc.svg?token=nGm2MDyYBLqUCSB4exJZ&branch=main
    :target: https://app.travis-ci.com/ucsd-ccbb/NetColoc

.. image:: https://readthedocs.org/projects/netcoloc/badge/?version=latest
        :target: https://netcoloc.readthedocs.io/en/latest/?badge=latest
        :alt: Documentation Status

.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.6773330.svg
        :target: https://doi.org/10.5281/zenodo.6773330


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.

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 <https://pypi.org/>`__

::

     pip install netcoloc


Version Notes
~~~~~~~~~~~~~

Version 1.0.0 incorporates additional functionality developed for the publication Wright, S. N. et al., "`Genome-wide association studies of human and rat BMI converge on synapse, epigenome, and hormone signaling networks <https://doi.org/10.1016/j.celrep.2023.112873>`__." Cell Reports (2023), as outlined at `<https://github.com/sarah-n-wright/CrossSpeciesBMI>`__.  

Prior version `netcoloc v0.1.6 <https://doi.org/10.5281/zenodo.6654561>`__ was utilized in the *NetColoc* publication: Rosenthal, S. B. et al.,
"`Mapping the common gene networks that underlie related diseases <https://doi.org/10.1038/s41596-022-00797-1>`__." Nature Protocols (2023).
To install this version, please use the following command:

::

     pip install netcoloc==0.1.6

And follow the additional installation instructions at `<https://pypi.org/project/netcoloc/0.1.6/>`__.

The original source code and example notebooks can be acquired from Zenodo: `DOI:6654561 <https://doi.org/10.5281/zenodo.6654561>`__, or from GitHub:

::

        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 <https://github.com/ucsd-ccbb/NetColoc/tree/main/example_notebooks>`__.

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

Dependencies
--------------

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


* `click >=6.0 <https://pypi.org/project/click>`__
* `matplotlib <https://pypi.org/project/matplotlib>`__
* `ndex2 <https://pypi.org/project/ndex2>`__
* `networkx >=2.0,<3.0 <https://pypi.org/project/networkx>`__
* `numpy <https://pypi.org/project/numpy>`__
* `seaborn <https://pypi.org/project/seaborn>`__
* `tqdm <https://pypi.org/project/tqdm>`__
* `mygene >= 3.2.2 <https://pypi.org/project/mygene/>`__
* `scipy >= 1.5.3 <https://pypi.org/project/scipy/>`__
* `statsmodels <https://pypi.org/project/statsmodels/>`__
* `gprofiler-official >= 1.0.0 <https://pypi.org/project/gprofiler-official/>`__
* `ipywidgets <https://pypi.org/project/ipywidgets>`__
* `ipycytoscape <https://ipycytoscape.readthedocs.io/en/latest>`__
* `ipykernel <https://pypi.org/project/ipykernel/>`__
* `obonet <https://pypi.org/project/obonet/>`__
* `cdapsutil <https://pypi.org/project/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 <http://dx.doi.org/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 <http://dx.doi.org/10.1016/j.celrep.2023.112873>`__



Credits
-------

This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.

.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage


=======
History
=======


1.0.0 (2025-07-09)
------------------

* `obonet <https://pypi.org/project/obonet/>`__ added as a dependency, replacing `DDOT <https://github.com/idekerlab/ddot>`__ dependency

* `cdapsutil <https://pypi.org/project/cdapsutil/>`__ added as a dependency

* `network_colocalization` updated for compatability with `pandas>=2.0 <https://pypi.org/project/pandas/>`__

* `validation` updated for compatability with `obonet <https://pypi.org/project/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 <https://pypi.org/project/pandas/>`__ and `obonet <https://pypi.org/project/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


0.1.7 (2022-06-28)
--------------------

* Removed unused `network_localization.py` module


0.1.6 (2022-06-16)
--------------------

* `ipycytoscape <https://ipycytoscape.readthedocs.io/en/latest>`__ added as a dependency

* `ipywidgets <https://ipywidgets.readthedocs.io/en/latest>`__ 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 <https://ipycytoscape.readthedocs.io/en/latest>`__

* `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 <https://pypi.org/project/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.