py3plex 2.0.0__tar.gz → 2.0.1__tar.gz

py3plex-2.0.1/MANIFEST.in

@@ -0,0 +1,5 @@
+include py3plex/algorithms/hedwig/assets/*
+include py3plex/datasets/_data/*
+global-exclude *.py[cod]
+global-exclude __pycache__/*
+prune **/__pycache__

py3plex-2.0.1/PKG-INFO

@@ -0,0 +1,385 @@
+Metadata-Version: 2.4
+Name: py3plex
+Version: 2.0.1
+Summary: A Multilayer network analysis python3 library
+Author-email: Blaž Škrlj <blaz.skrlj@ijs.si>
+License: MIT
+Project-URL: Homepage, https://github.com/SkBlaz/py3plex
+Project-URL: Documentation, https://skblaz.github.io/py3plex/
+Project-URL: Repository, https://github.com/SkBlaz/py3plex
+Project-URL: Bug Tracker, https://github.com/SkBlaz/py3plex/issues
+Keywords: network analysis,multilayer networks,heterogeneous networks,graph visualization,network science
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.19.0
+Requires-Dist: scipy>=1.5.0
+Requires-Dist: networkx>=2.5
+Requires-Dist: tqdm>=4.40.0
+Requires-Dist: matplotlib>=3.3.0
+Requires-Dist: scikit-learn>=0.24.0
+Requires-Dist: bitarray>=2.0.0
+Requires-Dist: seaborn>=0.11.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.1; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-benchmark<5.0,>=4.0; extra == "dev"
+Requires-Dist: pytest-rerunfailures>=12.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: types-six>=1.16.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0; extra == "dev"
+Requires-Dist: crosshair-tool>=0.0.60; extra == "dev"
+Requires-Dist: icontract>=2.6.0; extra == "dev"
+Requires-Dist: z3-solver>=4.12.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+Provides-Extra: tests
+Requires-Dist: pytest>=7.0; extra == "tests"
+Requires-Dist: pytest-timeout>=2.1; extra == "tests"
+Requires-Dist: pytest-cov>=4.0; extra == "tests"
+Requires-Dist: pytest-rerunfailures>=12.0; extra == "tests"
+Requires-Dist: hypothesis>=6.0; extra == "tests"
+Requires-Dist: hypothesis-networkx>=0.2.0; extra == "tests"
+Requires-Dist: networkx>=2.5; extra == "tests"
+Requires-Dist: numpy>=1.19.0; extra == "tests"
+Requires-Dist: scipy>=1.5.0; extra == "tests"
+Requires-Dist: python-louvain>=0.16; extra == "tests"
+Provides-Extra: infomap
+Requires-Dist: infomap>=2.0.0; extra == "infomap"
+Provides-Extra: algos
+Requires-Dist: python-louvain>=0.16; extra == "algos"
+Requires-Dist: cdlib>=0.3.0; extra == "algos"
+Requires-Dist: gensim>=4.0.0; extra == "algos"
+Requires-Dist: rdflib>=6.0.0; extra == "algos"
+Provides-Extra: viz
+Requires-Dist: plotly>=5.0.0; extra == "viz"
+Requires-Dist: python-igraph>=0.10.0; extra == "viz"
+Provides-Extra: workflows
+Requires-Dist: pyyaml>=5.1; extra == "workflows"
+Provides-Extra: arrow
+Requires-Dist: pyarrow>=10.0.0; extra == "arrow"
+Provides-Extra: compat
+Requires-Dist: networkx>=2.5; extra == "compat"
+Requires-Dist: scipy>=1.5.0; extra == "compat"
+Requires-Dist: pandas>=1.2.0; extra == "compat"
+Requires-Dist: pyarrow>=10.0.0; extra == "compat"
+Provides-Extra: igraph
+Requires-Dist: python-igraph>=0.10.0; extra == "igraph"
+Provides-Extra: pyg
+Requires-Dist: torch>=1.10.0; extra == "pyg"
+Requires-Dist: torch-geometric>=2.0.0; extra == "pyg"
+Provides-Extra: dgl-compat
+Requires-Dist: dgl>=0.9.0; extra == "dgl-compat"
+Provides-Extra: mcp
+Requires-Dist: mcp>=0.9.0; python_version >= "3.10" and extra == "mcp"
+Provides-Extra: examples
+Requires-Dist: sympy>=1.9; extra == "examples"
+Provides-Extra: optional
+Requires-Dist: infomap>=2.0.0; extra == "optional"
+Requires-Dist: python-louvain>=0.16; extra == "optional"
+Requires-Dist: cdlib>=0.3.0; extra == "optional"
+Requires-Dist: gensim>=4.0.0; extra == "optional"
+Requires-Dist: rdflib>=6.0.0; extra == "optional"
+Requires-Dist: plotly>=5.0.0; extra == "optional"
+Requires-Dist: python-igraph>=0.10.0; extra == "optional"
+Requires-Dist: pyyaml>=5.1; extra == "optional"
+Requires-Dist: pyarrow>=10.0.0; extra == "optional"
+Requires-Dist: mcp>=0.9.0; python_version >= "3.10" and extra == "optional"
+Requires-Dist: sympy>=1.9; extra == "optional"
+Dynamic: license-file
+
+
+<img src="https://github.com/user-attachments/assets/47e16a25-cd58-41eb-9ccd-b40191758d91" alt="py3plex logo" width="400">
+
+[![Tests](https://github.com/SkBlaz/py3plex/actions/workflows/tests.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/tests.yml)
+[![Examples](https://github.com/SkBlaz/py3plex/actions/workflows/examples.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/examples.yml)
+[![Tutorial](https://github.com/SkBlaz/py3plex/actions/workflows/tutorial-validation.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/tutorial-validation.yml)
+[![Code Quality](https://github.com/SkBlaz/py3plex/actions/workflows/code-quality.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/code-quality.yml)
+[![Benchmarks](https://github.com/SkBlaz/py3plex/actions/workflows/benchmarks.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/benchmarks.yml)
+[![Documentation](https://github.com/SkBlaz/py3plex/actions/workflows/doc-coverage.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/doc-coverage.yml)
+[![Formal Verification](https://github.com/SkBlaz/py3plex/actions/workflows/verify.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/verify.yml)
+[![Fuzzing](https://github.com/SkBlaz/py3plex/actions/workflows/fuzzing.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/fuzzing.yml)
+[![PyPI version](https://img.shields.io/pypi/v/py3plex.svg)](https://pypi.org/project/py3plex/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/py3plex)](https://pypistats.org/packages/py3plex)
+![CLI Tool](https://img.shields.io/badge/CLI%20Tool-Available-brightgreen)
+![Docker](https://img.shields.io/badge/Docker-Available-blue)
+![Lines of Code](https://img.shields.io/badge/lines-211.9K-blue)
+![Test Count](https://img.shields.io/badge/tests-9.3K-blue)
+
+*Multilayer networks* are complex networks with additional information assigned to nodes or edges (or both). This library includes
+some of the state-of-the-art algorithms for decomposition, visualization and analysis of such networks.
+
+**Key Features:**
+* SQL-like DSL for intuitive network queries with smart defaults
+* Multilayer network visualization and analysis
+* Community detection and centrality measures
+* Network decomposition and embeddings
+
+
+```python
+from py3plex.core import datasets
+from py3plex.dsl import Q
+
+# Load a built-in multilayer biological network (~500 nodes, 4 layers)
+network = datasets.fetch_multilayer("human_ppi_gene_disease_drug")
+
+# Find key regulator candidates with integrated community detection and uncertainty quantification
+master_regulators = (
+    Q.communities(                           # Automated community detection
+        mode="pareto",                       # Multi-objective Pareto selection
+        uq=True,                             # Uncertainty quantification enabled
+        uq_n_samples=30,                     # Robustness via 30 perturbed runs
+        uq_method="seed",                    # Vary random seeds for stability
+        seed=42,                             # Reproducibility
+        write_attrs={                        # Attribute names for community info
+            "community_id": "community_id",
+            "community_stability": "community_stability",
+        },
+    )
+    .nodes()                                 # Switch to node-level analysis
+    .node_type("gene")                       # Filter by node type
+    .where(degree__gt=3)                     # Remove peripheral nodes
+    .uq(method="perturbation", n_samples=100, ci=0.95, seed=42)  # Quantify confidence
+    .compute("betweenness_centrality", "pagerank", "degree_centrality")
+    .per_layer()                             # Group by layer
+        .top_k(30, "betweenness_centrality__mean")  # Top 30 per layer by mean
+    .end_grouping()
+    .coverage(mode="at_least", k=2)          # Keep nodes that are hubs in ≥2 layers
+    .mutate(                                 # Create derived influence score
+        score=lambda row: (
+            0.5 * row.get("betweenness_centrality__mean", 0.0) +
+            0.3 * row.get("pagerank__mean", 0.0) +
+            0.2 * row.get("degree_centrality__mean", 0.0)
+        )
+    )
+    .order_by("score", desc=True)
+    .limit(20)                               # Final top 20 candidates
+    .explain(neighbors_top=5)                # Enrich: community ID, top 5 partners, layers
+    .execute(network)
+)
+
+df = master_regulators.to_pandas(expand_uncertainty=True, expand_explanations=True)
+print(df[["id", "layer", "community_id",
+          "betweenness_centrality__mean", "betweenness_centrality_ci95_low",
+          "betweenness_centrality_ci95_high", "score", "top_neighbors"]].head(10))
+```
+
+Uses a strict two-phase flow:
+
+1. **Build query** on `Q...` (`.where()`, `.compute()`, `.order_by()`, `.per_layer()`, `.coverage()`, ...)
+2. **Execute once** with `.execute(network)`
+3. **Handle results** on `QueryResult` (`.to_pandas()`, `.group_summary()`, `.to_json()`, ...)
+
+**Example output:**
+```
+    id  layer  community_id  betweenness_centrality__mean  betweenness_centrality_ci95_low  betweenness_centrality_ci95_high     score  top_neighbors
+0  252      0            42                      0.025961                         0.021820                          0.030102  0.015577  [{'id': '91', 'weight': 2.3}, {'id': '419', 'weight': 1.9}]
+1   91      0            42                      0.024918                         0.020902                          0.028934  0.014951  [{'id': '252', 'weight': 2.3}, {'id': '103', 'weight': 2.1}]
+2  419      0            42                      0.024184                         0.020298                          0.028070  0.014510  [{'id': '252', 'weight': 1.9}, {'id': '91', 'weight': 1.7}]
+3  103      0            42                      0.023450                         0.019596                          0.027304  0.014069  [{'id': '91', 'weight': 2.1}, {'id': '252', 'weight': 1.8}]
+4  375      0            42                      0.022716                         0.018894                          0.026538  0.013628  [{'id': '91', 'weight': 1.8}, {'id': '252', 'weight': 1.6}]
+```
+
+
+**Key features demonstrated:**
+- **Streamlined API**: Community detection integrated directly into the DSL query chain
+- **AutoCommunity**: Multi-objective Pareto-optimal selection across algorithms (Louvain, Leiden, etc.)
+- **Uncertainty Quantification**: Confidence intervals for both community detection and centrality measures
+- **Cross-layer analysis**: `.coverage(mode="at_least", k=2)` keeps only nodes that are hubs in ≥2 layers
+- **Interpretability**: `.explain()` enriches results with community IDs, top interaction partners, and layer presence
+- **Composite scoring**: Weighted combination of multiple centrality measures for robust ranking
+
+### Ecosystem positioning
+
+| Comparator | Focus | py3plex 2.0 relation |
+|---|---|---|
+| **py3plex 2019** | Early py3plex multilayer analysis + visualization | Historical base; 2.0 expands into reproducible DSL/workflow-first analysis. |
+| **pymnet** | Formal multilayer modeling and metrics | Strongest Python formal multilayer peer; py3plex emphasizes workflows, UQ, and reproducibility. |
+| **MultiNetX** | Lightweight NetworkX-style multilayer utilities | Similar graph object tooling; py3plex offers broader end-to-end analysis workflows. |
+| **muxViz** | Visual multilayer analytics (R ecosystem) | Strong visual analytics peer; py3plex emphasizes scriptable Python workflows. |
+| **R `multinet`** | Multiplex social-network mining | Social-network-focused peer; py3plex targets broader heterogeneous multilayer science use cases. |
+| **tnetwork / DyNetx** | Temporal and dynamic graph workflows | Temporal overlap; py3plex adds multilayer semantics, DSL querying, and integrated dynamics. |
+| **Reticula / Raphtory / pathpy** | Temporal-engine and path-centric ecosystems | Strong temporal/path engines; py3plex focuses on multilayer workflow integration and analyst ergonomics. |
+| **NetworkX / igraph / graph-tool** | General-purpose graph analysis stacks | Core graph ecosystem overlap; py3plex adds layer-aware abstractions and reproducible multilayer workflows. |
+| **tidygraph** | Fluent graph-as-table manipulation | Similar analyst grammar style; py3plex adapts it to Python multilayer semantics. |
+| **NDlib** | Diffusion and epidemic simulation | Dynamics overlap; py3plex embeds dynamics inside multilayer, queryable, uncertainty-aware pipelines. |
+| **PyTorch Geometric / DGL** | Graph deep learning frameworks | Adjacent graph-ML layer; py3plex focuses on preparation, querying, and scientific analysis workflows. |
+| **Neo4j / Cypher** | Persistent property-graph querying | Query overlap; py3plex provides in-memory scientific multilayer DSL + metrics + exports. |
+| **py3plex 2.0** | Query-driven reproducible multilayer analysis | Python-native workflow layer: DSL/builder API, layer algebra, UQ, temporal/dynamics, null models, and CLI. |
+
+![Py3plex Visualization Showcase](example_images/py3plex_showcase.png)
+
+## Getting Started
+
+### Installation
+
+We recommend using [uv](https://docs.astral.sh/uv/) for fast, reliable Python environment management:
+
+```bash
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Create and activate virtual environment
+uv venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install py3plex
+uv pip install py3plex
+
+# Or install from source with development dependencies
+uv pip install -e ".[dev]"
+```
+
+Alternatively, use pip:
+```bash
+pip install py3plex
+```
+
+### Optional Features
+
+Install additional features as needed:
+
+```bash
+# MCP server for AI agent integration (requires Python 3.10+)
+pip install py3plex[mcp]
+
+# Community detection algorithms
+pip install py3plex[algos]
+
+# Advanced visualization
+pip install py3plex[viz]
+
+# All optional features
+pip install py3plex[mcp,algos,viz]
+
+# Common optional feature bundle (algorithms + visualization + workflows + arrow + mcp)
+pip install py3plex[optional]
+```
+
+### Contributing (First PR Quick Path)
+
+If this is your first contribution, use this sequence:
+
+```bash
+# 1) Create local dev environment and install package
+make setup
+make dev-install
+
+# 2) Run formatting and checks before opening a PR
+make format
+make lint
+make test
+```
+
+Helpful commands:
+
+```bash
+make help   # List all project commands
+make ci     # Run lint + tests in CI-style order
+```
+
+Safety notes for contributors:
+- Keep changes focused and add tests next to the feature you modify.
+- Do not add new markdown files unless explicitly requested (enforced by `tests/test_link_checker.py` to prevent documentation drift).
+- Prefer running targeted tests first, then broader checks before opening a PR.
+- For docs-only updates, run `make docs-check` before opening a PR.
+
+### MCP Integration (AI Agents)
+
+py3plex provides a Model Context Protocol (MCP) server for integration with AI coding assistants:
+
+**Requirements**: Python 3.10 or higher (due to MCP SDK dependency)
+
+```bash
+# Install with MCP support (Python 3.10+ required)
+pip install py3plex[mcp]
+
+# Start MCP server
+py3plex-mcp
+```
+
+**Configure Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "py3plex": {
+      "command": "py3plex-mcp"
+    }
+  }
+}
+```
+
+The MCP server exposes:
+- **7 tools**: Load networks, run queries (with DSL v2 support), detect communities, export results, and more
+- **3 resources**: Complete documentation, DSL v2 reference, and tool schemas
+- **DSL v2 support**: Modern builder API with type hints (`Q.nodes().where(degree__gt=5).compute('pagerank')`)
+- **Security-first**: Safe file access, automatic output directory, structured errors
+
+See [AGENTS.md](AGENTS.md#mcp-integration-model-context-protocol) for complete MCP documentation including DSL v2 examples.
+
+### Resources
+
+* **Documentation:** [https://skblaz.github.io/py3plex/](https://skblaz.github.io/py3plex/)
+* **Technical Book (PDF):** [Practical Multilayer Network Analysis with Py3plex](docs/py3plex_book.pdf) - Complete handbook (106 pages)
+* **Examples:** [examples/](examples/) - 170+ example scripts demonstrating usage
+
+## License
+
+Py3plex is released under the [MIT License](LICENSE).
+
+**Note on licensing:** Prior to version 1.0, the project was distributed under the BSD-3-Clause license. Starting with version 1.0, the license was changed to MIT to better align with the broader Python scientific ecosystem and simplify contribution and reuse. Both licenses are permissive and OSI-approved.
+
+# Citations
+```
+@Article{Skrlj2019,
+author={Skrlj, Blaz
+and Kralj, Jan
+and Lavrac, Nada},
+title={Py3plex toolkit for visualization and analysis of multilayer networks},
+journal={Applied Network Science},
+year={2019},
+volume={4},
+number={1},
+pages={94},
+abstract={Complex networks are used as means for representing multimodal, real-life systems. With increasing amounts of data that lead to large multilayer networks consisting of different node and edge types, that can also be subject to temporal change, there is an increasing need for versatile visualization and analysis software. This work presents a lightweight Python library, Py3plex, which focuses on the visualization and analysis of multilayer networks. The library implements a set of simple graphical primitives supporting intra- as well as inter-layer visualization. It also supports many common operations on multilayer networks, such as aggregation, slicing, indexing, traversal, and more. The paper also focuses on how node embeddings can be used to speed up contemporary (multilayer) layout computation. The library's functionality is showcased on both real and synthetic networks.},
+issn={2364-8228},
+doi={10.1007/s41109-019-0203-7},
+url={https://doi.org/10.1007/s41109-019-0203-7}
+}
+```
+and
+```
+@InProceedings{10.1007/978-3-030-05411-3_60,
+author="{\v{S}}krlj, Bla{\v{z}}
+and Kralj, Jan
+and Lavra{\v{c}}, Nada",
+editor="Aiello, Luca Maria
+and Cherifi, Chantal
+and Cherifi, Hocine
+and Lambiotte, Renaud
+and Li{\'o}, Pietro
+and Rocha, Luis M.",
+title="Py3plex: A Library for Scalable Multilayer Network Analysis and Visualization",
+booktitle="Complex Networks and Their Applications VII",
+year="2019",
+publisher="Springer International Publishing",
+address="Cham",
+pages="757--768",
+abstract="Real-life systems are commonly represented as networks of interacting entities. While homogeneous networks consist of nodes of a single node type, multilayer networks are characterized by multiple types of nodes or edges, all present in the same system. Analysis and visualization of such networks represent a challenge for real-life complex network applications. The presented Py3plex Python-based library facilitates the exploration and visualization of multilayer networks. The library includes a diagonal projection-based network visualization, developed specifically for large networks with multiple node (and edge) types. The library also includes state-of-the-art methods for network decomposition and statistical analysis. The Py3plex functionality is showcased on real-world multilayer networks from the domains of biology and on synthetic networks.",
+isbn="978-3-030-05411-3"
+}
+```