risk-network 0.0.10__tar.gz → 0.0.12__tar.gz

risk_network-0.0.12/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: risk-network
+Version: 0.0.12
+Summary: A Python package for biological network analysis
+Author-email: Ira Horecka <ira89@icloud.com>
+License: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/riskportal/network
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ipywidgets
+Requires-Dist: leidenalg
+Requires-Dist: markov_clustering
+Requires-Dist: matplotlib
+Requires-Dist: networkx
+Requires-Dist: nltk
+Requires-Dist: numpy
+Requires-Dist: openpyxl
+Requires-Dist: pandas
+Requires-Dist: python-igraph
+Requires-Dist: python-louvain
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+Requires-Dist: statsmodels
+Requires-Dist: threadpoolctl
+Requires-Dist: tqdm
+Dynamic: license-file
+
+# RISK Network
+
+<p align="center">
+  <img src="https://i.imgur.com/8TleEJs.png" width="50%" />
+</p>
+
+<br>
+
+![Python](https://img.shields.io/badge/python-3.8%2B-yellow)
+[![pypiv](https://img.shields.io/pypi/v/risk-network.svg)](https://pypi.python.org/pypi/risk-network)
+![License](https://img.shields.io/badge/license-GPLv3-purple)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.xxxxxxx.svg)](https://doi.org/10.5281/zenodo.xxxxxxx)
+![Downloads](https://img.shields.io/pypi/dm/risk-network)
+![Tests](https://github.com/riskportal/network/actions/workflows/ci.yml/badge.svg)
+
+**RISK** (Regional Inference of Significant Kinships) is a next-generation tool for biological network annotation and visualization. RISK integrates community detection-based clustering, rigorous statistical enrichment analysis, and a modular framework to uncover biologically meaningful relationships and generate high-resolution visualizations. RISK supports diverse data formats and is optimized for large-scale network analysis, making it a valuable resource for researchers in systems biology and beyond.
+
+## Documentation and Tutorial
+
+Full documentation is available at:
+
+- **Docs:** [https://riskportal.github.io/network-tutorial](https://riskportal.github.io/network-tutorial)  
+- **Tutorial Jupyter Notebook Repository:** [https://github.com/riskportal/network-tutorial](https://github.com/riskportal/network-tutorial)
+
+## Installation
+
+RISK is compatible with Python 3.8 or later and runs on all major operating systems. To install the latest version of RISK, run:
+
+```bash
+pip install risk-network --upgrade
+```
+
+## Features
+
+- **Comprehensive Network Analysis**: Analyze biological networks (e.g., protein–protein interaction and genetic interaction networks) as well as non-biological networks.
+- **Advanced Clustering Algorithms**: Supports Louvain, Leiden, Markov Clustering, Greedy Modularity, Label Propagation, Spinglass, and Walktrap for identifying structured network regions.
+- **Flexible Visualization**: Produce customizable, high-resolution network visualizations with kernel density estimate overlays, adjustable node and edge attributes, and export options in SVG, PNG, and PDF formats.
+- **Efficient Data Handling**: Supports multiple input/output formats, including JSON, CSV, TSV, Excel, Cytoscape, and GPickle.
+- **Statistical Analysis**: Assess functional enrichment using hypergeometric, permutation (network-aware), binomial, chi-squared, Poisson, and z-score tests, ensuring statistical adaptability across datasets.
+- **Cross-Domain Applicability**: Suitable for network analysis across biological and non-biological domains, including social and communication networks.
+
+## Example Usage
+
+We applied RISK to a *Saccharomyces cerevisiae* protein–protein interaction network from Michaelis et al. (2023), filtering for proteins with six or more interactions to emphasize core functional relationships. RISK identified compact, statistically enriched clusters corresponding to biological processes such as ribosomal assembly and mitochondrial organization.
+
+[![Figure 1](https://i.imgur.com/lJHJrJr.jpeg)](https://i.imgur.com/lJHJrJr.jpeg)
+
+This figure highlights RISK’s capability to detect both established and novel functional modules within the yeast interactome.
+
+## Citation
+
+If you use RISK in your research, please cite:
+
+**Horecka et al.**, "RISK: a next-generation tool for biological network annotation and visualization", **Bioinformatics**, 2025. DOI: [10.1234/zenodo.xxxxxxx](https://doi.org/10.1234/zenodo.xxxxxxx)
+
+## Software Architecture and Implementation
+
+RISK features a streamlined, modular architecture designed to meet diverse research needs. RISK’s modular design enables users to run individual components—such as clustering, statistical testing, or visualization—independently or in combination, depending on the analysis workflow. It includes dedicated modules for:
+
+- **Data I/O**: Supports JSON, CSV, TSV, Excel, Cytoscape, and GPickle formats.
+- **Clustering**: Supports multiple clustering methods, including Louvain, Leiden, Markov Clustering, Greedy Modularity, Label Propagation, Spinglass, and Walktrap. Provides flexible distance metrics tailored to network structure.
+- **Statistical Analysis**: Provides a suite of tests for overrepresentation analysis of annotations.
+- **Visualization**: Offers customizable, high-resolution output in multiple formats, including SVG, PNG, and PDF.
+- **Configuration Management**: Centralized parameters in risk.params ensure reproducibility and easy tuning for large-scale analyses.
+
+## Performance and Efficiency
+
+Benchmarking results demonstrate that RISK efficiently scales to networks exceeding hundreds of thousands of edges, maintaining low execution times and optimal memory usage across statistical tests.
+
+## Contributing
+
+We welcome contributions from the community:
+
+- [Issues Tracker](https://github.com/riskportal/network/issues)
+- [Source Code](https://github.com/riskportal/network/tree/main/risk)
+
+## Support
+
+If you encounter issues or have suggestions for new features, please use the [Issues Tracker](https://github.com/riskportal/network/issues) on GitHub.
+
+## License
+
+RISK is open source under the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html).

{risk_network-0.0.10 → risk_network-0.0.12}/README.md

@@ -17,7 +17,10 @@
 
 ## Documentation and Tutorial
 
-An interactive Jupyter notebook tutorial can be found [here](https://github.com/riskportal/network-tutorial). We highly recommend new users to consult the documentation and tutorial early on to fully utilize RISK's capabilities.
+Full documentation is available at:
+
+- **Docs:** [https://riskportal.github.io/network-tutorial](https://riskportal.github.io/network-tutorial)  
+- **Tutorial Jupyter Notebook Repository:** [https://github.com/riskportal/network-tutorial](https://github.com/riskportal/network-tutorial)
 
 ## Installation
 
@@ -33,7 +36,7 @@ pip install risk-network --upgrade
 - **Advanced Clustering Algorithms**: Supports Louvain, Leiden, Markov Clustering, Greedy Modularity, Label Propagation, Spinglass, and Walktrap for identifying structured network regions.
 - **Flexible Visualization**: Produce customizable, high-resolution network visualizations with kernel density estimate overlays, adjustable node and edge attributes, and export options in SVG, PNG, and PDF formats.
 - **Efficient Data Handling**: Supports multiple input/output formats, including JSON, CSV, TSV, Excel, Cytoscape, and GPickle.
-- **Statistical Analysis**: Assess functional enrichment using hypergeometric, permutation, binomial, chi-squared, Poisson, and z-score tests, ensuring statistical adaptability across datasets.
+- **Statistical Analysis**: Assess functional enrichment using hypergeometric, permutation (network-aware), binomial, chi-squared, Poisson, and z-score tests, ensuring statistical adaptability across datasets.
 - **Cross-Domain Applicability**: Suitable for network analysis across biological and non-biological domains, including social and communication networks.
 
 ## Example Usage
@@ -52,12 +55,13 @@ If you use RISK in your research, please cite:
 
 ## Software Architecture and Implementation
 
-RISK features a streamlined, modular architecture designed to meet diverse research needs. It includes dedicated modules for:
+RISK features a streamlined, modular architecture designed to meet diverse research needs. RISK’s modular design enables users to run individual components—such as clustering, statistical testing, or visualization—independently or in combination, depending on the analysis workflow. It includes dedicated modules for:
 
 - **Data I/O**: Supports JSON, CSV, TSV, Excel, Cytoscape, and GPickle formats.
 - **Clustering**: Supports multiple clustering methods, including Louvain, Leiden, Markov Clustering, Greedy Modularity, Label Propagation, Spinglass, and Walktrap. Provides flexible distance metrics tailored to network structure.
 - **Statistical Analysis**: Provides a suite of tests for overrepresentation analysis of annotations.
 - **Visualization**: Offers customizable, high-resolution output in multiple formats, including SVG, PNG, and PDF.
+- **Configuration Management**: Centralized parameters in risk.params ensure reproducibility and easy tuning for large-scale analyses.
 
 ## Performance and Efficiency
 
@@ -77,7 +81,3 @@ If you encounter issues or have suggestions for new features, please use the [Is
 ## License
 
 RISK is open source under the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html).
-
----
-
-**Note**: For detailed documentation and to access the interactive tutorial, please visit the links above.

{risk_network-0.0.10 → risk_network-0.0.12}/pyproject.toml

@@ -1,20 +1,19 @@
 [build-system]
-requires = ["setuptools", "wheel", "numpy"]
+requires = ["setuptools", "numpy"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "risk-network"
-dynamic = ["version"]  # Indicates that version is determined dynamically
+dynamic = ["version"]
 description = "A Python package for biological network analysis"
 authors = [
     { name = "Ira Horecka", email = "ira89@icloud.com" },
 ]
 readme = "README.md"
-license = { file = "LICENSE" }
+requires-python = ">=3.8"
 classifiers = [
     "Intended Audience :: Developers",
     "Intended Audience :: Science/Research",
-    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.8",
@@ -31,7 +30,7 @@ dependencies = [
     "markov_clustering",
     "matplotlib",
     "networkx",
-    "nltk==3.8.1",
+    "nltk",
     "numpy",
     "openpyxl",
     "pandas",
@@ -43,4 +42,21 @@ dependencies = [
     "threadpoolctl",
     "tqdm",
 ]
-requires-python = ">=3.8"
+
+[project.license]
+text = "GPL-3.0-or-later"
+
+[project.urls]
+"Homepage" = "https://github.com/riskportal/network"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "risk.__version__" }
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

{risk_network-0.0.10 → risk_network-0.0.12/src}/risk/__init__.py

@@ -7,4 +7,4 @@ RISK: Regional Inference of Significant Kinships
 
 from risk.risk import RISK
 
-__version__ = "0.0.10"
+__version__ = "0.0.12"

risk_network-0.0.12/src/risk/annotation/__init__.py

@@ -0,0 +1,10 @@
+"""
+risk/annotation
+~~~~~~~~~~~~~~~
+"""
+
+from risk.annotation.annotation import (
+    define_top_annotation,
+    get_weighted_description,
+)
+from risk.annotation.io import AnnotationIO

risk_network-0.0.10/risk/annotations/annotations.py → risk_network-0.0.12/src/risk/annotation/annotation.py

@@ -1,88 +1,48 @@
 """
-risk/annotations/annotations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/annotation/annotation
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
-import os
 import re
-import zipfile
 from collections import Counter
 from itertools import compress
 from typing import Any, Dict, List, Set
 
 import networkx as nx
-import nltk
 import numpy as np
 import pandas as pd
-from nltk.corpus import stopwords
-from nltk.stem import WordNetLemmatizer
 from nltk.tokenize import word_tokenize
+from scipy.sparse import coo_matrix
 
+from risk.annotation.nltk_setup import setup_nltk_resources
 from risk.log import logger
-from scipy.sparse import coo_matrix
 
 
-def ensure_nltk_resource(resource: str) -> None:
-    """Ensure the specified NLTK resource is available."""
-    # Define the path to the resource within the NLTK data directory
-    resource_path = f"corpora/{resource}"
-    # Check if the resource is already available.
-    try:
-        nltk.data.find(resource_path)
-        return
-    except LookupError:
-        print(f"Resource '{resource}' not found. Attempting to download...")
-
-    # Download the resource.
-    nltk.download(resource)
-    # Check again after downloading.
-    try:
-        nltk.data.find(resource_path)
-        return
-    except LookupError:
-        print(f"Resource '{resource}' still not found after download. Checking for a ZIP file...")
-
-    # Look for a ZIP file in all known NLTK data directories.
-    for data_path in nltk.data.path:
-        zip_path = os.path.join(data_path, "corpora", f"{resource}.zip")
-        if os.path.isfile(zip_path):
-            print(f"Found ZIP file for '{resource}' at: {zip_path}")
-            target_dir = os.path.join(data_path, "corpora")
-            with zipfile.ZipFile(zip_path, "r") as z:
-                z.extractall(path=target_dir)
-            print(f"Unzipped '{resource}' successfully.")
-            break  # Stop after unzipping the first found ZIP.
-
-    # Final check: Try to check resource one last time. If it fails, rai
-    try:
-        nltk.data.find(resource_path)
-        print(f"Resource '{resource}' is now available.")
-    except LookupError:
-        raise LookupError(f"Resource '{resource}' could not be found, downloaded, or unzipped.")
-
-
-# Ensure the NLTK stopwords and WordNet resources are available
-# punkt is known to have issues with the default download method, so we use a custom function if it fails
-try:
-    ensure_nltk_resource("punkt")
-except LookupError:
-    nltk.download("punkt")
-ensure_nltk_resource("stopwords")
-ensure_nltk_resource("wordnet")
-# Use NLTK's stopwords - load all languages
-STOP_WORDS = set(word for lang in stopwords.fileids() for word in stopwords.words(lang))
-# Initialize the WordNet lemmatizer, which is used for normalizing words
-LEMMATIZER = WordNetLemmatizer()
-
-
-def load_annotations(
-    network: nx.Graph, annotations_input: Dict[str, Any], min_nodes_per_term: int = 2
+def initialize_nltk():
+    """Initialize all required NLTK components."""
+    setup_nltk_resources()
+
+    # After resources are available, initialize the components
+    from nltk.corpus import stopwords
+    from nltk.stem import WordNetLemmatizer
+
+    global STOP_WORDS, LEMMATIZER
+    STOP_WORDS = set(stopwords.words("english"))
+    LEMMATIZER = WordNetLemmatizer()
+
+
+# Initialize NLTK components
+initialize_nltk()
+
+
+def load_annotation(
+    network: nx.Graph, annotation_input: Dict[str, Any], min_nodes_per_term: int = 2
 ) -> Dict[str, Any]:
-    """Convert annotations input to a sparse matrix and reindex based on the network's node labels.
+    """Convert annotation input to a sparse matrix and reindex based on the network's node labels.
 
     Args:
         network (nx.Graph): The network graph.
-        annotations_input (Dict[str, Any]): A dictionary with annotations.
+        annotation_input (Dict[str, Any]): An annotation dictionary.
         min_nodes_per_term (int, optional): The minimum number of network nodes required for each annotation
             term to be included. Defaults to 2.
 
@@ -91,18 +51,18 @@ def load_annotations(
             matrix.
 
     Raises:
-        ValueError: If no annotations are found for the nodes in the network.
-        ValueError: If no annotations have at least min_nodes_per_term nodes in the network.
+        ValueError: If no annotation is found for the nodes in the network.
+        ValueError: If no annotation has at least min_nodes_per_term nodes in the network.
     """
     # Step 1: Map nodes and annotations to indices
     node_label_order = [attr["label"] for _, attr in network.nodes(data=True) if "label" in attr]
     node_to_idx = {node: i for i, node in enumerate(node_label_order)}
-    annotation_to_idx = {annotation: i for i, annotation in enumerate(annotations_input)}
+    annotation_to_idx = {annotation: i for i, annotation in enumerate(annotation_input)}
     # Step 2: Construct a sparse binary matrix directly
     row = []
     col = []
     data = []
-    for annotation, nodes in annotations_input.items():
+    for annotation, nodes in annotation_input.items():
         for node in nodes:
             if node in node_to_idx and annotation in annotation_to_idx:
                 row.append(node_to_idx[node])
@@ -111,40 +71,40 @@ def load_annotations(
 
     # Create a sparse binary matrix
     num_nodes = len(node_to_idx)
-    num_annotations = len(annotation_to_idx)
-    annotations_pivot = coo_matrix((data, (row, col)), shape=(num_nodes, num_annotations)).tocsr()
+    num_annotation = len(annotation_to_idx)
+    annotation_pivot = coo_matrix((data, (row, col)), shape=(num_nodes, num_annotation)).tocsr()
     # Step 3: Filter out annotations with fewer than min_nodes_per_term occurrences
-    valid_annotations = annotations_pivot.sum(axis=0).A1 >= min_nodes_per_term
-    annotations_pivot = annotations_pivot[:, valid_annotations]
+    valid_annotation = annotation_pivot.sum(axis=0).A1 >= min_nodes_per_term
+    annotation_pivot = annotation_pivot[:, valid_annotation]
     # Step 4: Raise errors for empty matrices
-    if annotations_pivot.nnz == 0:
+    if annotation_pivot.nnz == 0:
         raise ValueError("No terms found in the annotation file for the nodes in the network.")
 
-    num_remaining_annotations = annotations_pivot.shape[1]
-    if num_remaining_annotations == 0:
+    num_remaining_annotation = annotation_pivot.shape[1]
+    if num_remaining_annotation == 0:
         raise ValueError(
             f"No annotation terms found with at least {min_nodes_per_term} nodes in the network."
         )
 
     # Step 5: Extract ordered nodes and annotations
     ordered_nodes = tuple(node_label_order)
-    ordered_annotations = tuple(
-        annotation for annotation, is_valid in zip(annotation_to_idx, valid_annotations) if is_valid
+    ordered_annotation = tuple(
+        annotation for annotation, is_valid in zip(annotation_to_idx, valid_annotation) if is_valid
     )
 
     # Log the filtering details
     logger.info(f"Minimum number of nodes per annotation term: {min_nodes_per_term}")
-    logger.info(f"Number of input annotation terms: {num_annotations}")
-    logger.info(f"Number of remaining annotation terms: {num_remaining_annotations}")
+    logger.info(f"Number of input annotation terms: {num_annotation}")
+    logger.info(f"Number of remaining annotation terms: {num_remaining_annotation}")
 
     return {
         "ordered_nodes": ordered_nodes,
-        "ordered_annotations": ordered_annotations,
-        "matrix": annotations_pivot,
+        "ordered_annotation": ordered_annotation,
+        "matrix": annotation_pivot,
     }
 
 
-def define_top_annotations(
+def define_top_annotation(
     network: nx.Graph,
     ordered_annotation_labels: List[str],
     neighborhood_significance_sums: List[int],
@@ -170,7 +130,7 @@ def define_top_annotations(
     # Sum the columns of the significant significance matrix (positive floating point values)
     significant_significance_scores = significant_significance_matrix.sum(axis=0)
     # Create DataFrame to store annotations, their neighborhood significance sums, and significance scores
-    annotations_significance_matrix = pd.DataFrame(
+    annotation_significance_matrix = pd.DataFrame(
         {
             "id": range(len(ordered_annotation_labels)),
             "full_terms": ordered_annotation_labels,
@@ -178,29 +138,29 @@ def define_top_annotations(
             "significant_significance_score": significant_significance_scores,
         }
     )
-    annotations_significance_matrix["significant_annotations"] = False
+    annotation_significance_matrix["significant_annotation"] = False
     # Apply size constraints to identify potential significant annotations
-    annotations_significance_matrix.loc[
+    annotation_significance_matrix.loc[
         (
-            annotations_significance_matrix["significant_neighborhood_significance_sums"]
+            annotation_significance_matrix["significant_neighborhood_significance_sums"]
             >= min_cluster_size
         )
         & (
-            annotations_significance_matrix["significant_neighborhood_significance_sums"]
+            annotation_significance_matrix["significant_neighborhood_significance_sums"]
             <= max_cluster_size
         ),
-        "significant_annotations",
+        "significant_annotation",
     ] = True
     # Initialize columns for connected components analysis
-    annotations_significance_matrix["num_connected_components"] = 0
-    annotations_significance_matrix["size_connected_components"] = None
-    annotations_significance_matrix["size_connected_components"] = annotations_significance_matrix[
+    annotation_significance_matrix["num_connected_components"] = 0
+    annotation_significance_matrix["size_connected_components"] = None
+    annotation_significance_matrix["size_connected_components"] = annotation_significance_matrix[
         "size_connected_components"
     ].astype(object)
-    annotations_significance_matrix["num_large_connected_components"] = 0
+    annotation_significance_matrix["num_large_connected_components"] = 0
 
-    for attribute in annotations_significance_matrix.index.values[
-        annotations_significance_matrix["significant_annotations"]
+    for attribute in annotation_significance_matrix.index.values[
+        annotation_significance_matrix["significant_annotation"]
     ]:
         # Identify significant neighborhoods based on the binary significance matrix
         significant_neighborhoods = list(
@@ -223,24 +183,24 @@ def define_top_annotations(
         num_large_connected_components = len(filtered_size_connected_components)
 
         # Assign the number of connected components
-        annotations_significance_matrix.loc[attribute, "num_connected_components"] = (
+        annotation_significance_matrix.loc[attribute, "num_connected_components"] = (
             num_connected_components
         )
         # Filter out attributes with more than one connected component
-        annotations_significance_matrix.loc[
-            annotations_significance_matrix["num_connected_components"] > 1,
-            "significant_annotations",
+        annotation_significance_matrix.loc[
+            annotation_significance_matrix["num_connected_components"] > 1,
+            "significant_annotation",
         ] = False
         # Assign the number of large connected components
-        annotations_significance_matrix.loc[attribute, "num_large_connected_components"] = (
+        annotation_significance_matrix.loc[attribute, "num_large_connected_components"] = (
             num_large_connected_components
         )
         # Assign the size of connected components, ensuring it is always a list
-        annotations_significance_matrix.at[attribute, "size_connected_components"] = (
+        annotation_significance_matrix.at[attribute, "size_connected_components"] = (
             filtered_size_connected_components.tolist()
         )
 
-    return annotations_significance_matrix
+    return annotation_significance_matrix
 
 
 def get_weighted_description(words_column: pd.Series, scores_column: pd.Series) -> str: