py3plex 1.1.7__tar.gz → 2.0.0__tar.gz

{py3plex-1.1.7/py3plex.egg-info → py3plex-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py3plex
-Version: 1.1.7
+Version: 2.0.0
 Summary: A Multilayer network analysis python3 library
 Author-email: Blaž Škrlj <blaz.skrlj@ijs.si>
 License: MIT
@@ -113,7 +113,7 @@ Dynamic: license-file
 ![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.4K-blue)
-![Test Count](https://img.shields.io/badge/tests-9.1K-blue)
+![Test Count](https://img.shields.io/badge/tests-9.2K-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.
@@ -200,6 +200,30 @@ Use a strict two-phase flow:
 - **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 | Ecosystem | Primary scope | Where it overlaps with py3plex 2.0 | py3plex 2.0 positioning |
+|---|---|---|---|---|
+| **py3plex 2019** | Python | Multilayer network visualization and analysis | Direct historical predecessor: multilayer representation, aggregation, indexing, traversal, visualization, and embedding-assisted layouts | **Historical foundation.** py3plex 2.0 extends the original toolkit from visualization-oriented analysis into a reproducible, query-driven multilayer network science environment. |
+| **pymnet** | Python | General multilayer network representation, metrics, random models, and visualization | Strong overlap on formal multilayer data structures, multilayer metrics, transformations, random models, and visualization | **Closest Python multilayer comparator.** pymnet is strongest as a formal multilayer framework; py3plex 2.0 is strongest as a workflow, DSL, uncertainty, and reproducibility layer. |
+| **MultiNetX** | Python / NetworkX | NetworkX-style multilayer graph manipulation, spectral analysis, and visualization | Overlap on Python-native multilayer graph objects, supra-adjacency/Laplacian workflows, and visualization | **Lightweight Python comparator.** MultiNetX provides compact multilayer graph utilities; py3plex 2.0 provides a broader end-to-end analysis and workflow environment. |
+| **muxViz** | R / desktop ecosystem | Multilayer and multiplex visual analytics | Overlap on multilayer visualization, centrality, community detection, motifs, structural reducibility, and dynamic visualization | **R visual-analytics comparator.** muxViz is strongest for visual exploration; py3plex 2.0 emphasizes Python-native, scriptable, DSL-driven, reproducible analysis. |
+| **R `multinet`** | R | Multiplex and multilayer social-network analysis and mining | Overlap on multilayer representation, import/export, attributes, centrality, community detection, generation, and plotting | **R social-network comparator.** `multinet` is strongest for multiplex social-network analysis; py3plex 2.0 targets broader heterogeneous scientific multilayer workflows in Python. |
+| **tnetwork** | Python | Temporal-network manipulation and dynamic communities | Overlap on temporal slicing, dynamic graphs, and evolving-community analysis | **Temporal-community comparator.** tnetwork focuses on temporal community workflows; py3plex 2.0 embeds temporal analysis inside a broader multilayer DSL/workflow stack. |
+| **DyNetx** | Python / NetworkX | Dynamic graph extension for NetworkX | Overlap on time-varying graph representation, snapshots, interaction streams, and temporal slicing | **Dynamic-NetworkX comparator.** DyNetx handles dynamic graphs; py3plex 2.0 adds multilayer semantics, declarative analysis, integrated dynamics, and reusable workflows. |
+| **Reticula** | Python with C++ core | Fast static and temporal network / hypergraph analysis | Overlap on temporal networks, reachability, randomized models, and dynamical-process analysis | **Performance temporal/hypergraph comparator.** Reticula is stronger for fast temporal and hypergraph analysis; py3plex 2.0 is stronger for multilayer workflow integration and analyst ergonomics. |
+| **Raphtory** | Rust / Python | Temporal graph engine and deployment platform | Overlap on temporal graph views, time-aware querying, reachability, motifs, and deployment-oriented graph analysis | **Modern temporal-engine comparator.** Raphtory is an engine/platform; py3plex 2.0 is a multilayer network-science workflow layer with DSL, uncertainty, dynamics, and reproducible analysis. |
+| **pathpy / pathpyG** | Python / PyTorch ecosystem | Path-centric temporal-network analytics and graph learning | Overlap on temporal analytics, time-respecting paths, temporal centralities, visualization, and graph-learning handoff | **Temporal graph-learning comparator.** pathpy/pathpyG is adjacent; py3plex 2.0 focuses on multilayer network science, layer-aware querying, uncertainty, and reproducible workflows. |
+| **NetworkX** | Python | General graph creation, manipulation, and algorithms | Overlap on core graph algorithms, graph data structures, centrality, communities, and Python graph workflows | **General graph substrate.** NetworkX is the base graph ecosystem; py3plex 2.0 adds multilayer semantics, DSL queries, layer algebra, temporal/dynamics workflows, and structured outputs. |
+| **igraph** | C / R / Python | Efficient general-purpose network analysis | Overlap on centrality, community detection, graph transformations, and scalable graph analysis | **Efficient general-graph comparator.** igraph is the speed/breadth baseline; py3plex 2.0 differentiates through multilayer-specific workflows and reproducible analyst interfaces. |
+| **graph-tool** | Python with C++ core | High-performance graph algorithms and statistical network modeling | Overlap on large-network statistics, community detection, inference, and performance-sensitive graph analysis | **Performance/statistical comparator.** graph-tool is strongest for efficient statistical graph analysis; py3plex 2.0 prioritizes multilayer expressiveness, querying, uncertainty, and workflow integration. |
+| **tidygraph** | R / tidyverse | Tidy, dplyr-style graph manipulation | Overlap on chainable, analyst-friendly node/edge manipulation and graph-as-table workflows | **Analyst-grammar comparator.** tidygraph motivates fluent graph manipulation; py3plex 2.0 adapts this style to Python multilayer networks with DSL, builder APIs, and layer-aware grouping. |
+| **NDlib** | Python | Diffusion and epidemic processes on networks | Overlap on SIS/SIR-style processes, random walks, spreading dynamics, and simulation workflows | **Dynamics comparator.** NDlib specializes in diffusion; py3plex 2.0 embeds dynamics inside multilayer, temporal, queryable, uncertainty-aware workflows. |
+| **PyTorch Geometric** | Python / PyTorch | Graph neural networks and geometric deep learning | Overlap on graph embeddings, graph data preparation, and downstream graph-learning workflows | **Graph-ML comparator.** PyG trains graph neural models; py3plex 2.0 prepares, queries, explains, summarizes, and analyzes multilayer networks. |
+| **DGL** | Python / deep-learning frameworks | Scalable graph deep learning and message passing | Overlap on heterogeneous graph processing, graph learning, and scalable graph ML pipelines | **Scalable graph-ML comparator.** DGL addresses GNN systems engineering; py3plex 2.0 addresses multilayer network science, query abstractions, uncertainty, temporal analysis, and workflows. |
+| **Neo4j / Cypher** | Database systems | Persistent property-graph storage and declarative graph querying | Overlap on declarative graph querying and pattern-style graph access | **Graph-query comparator.** Cypher queries persistent property graphs; py3plex 2.0 provides an in-memory scientific DSL for multilayer network analysis, metrics, uncertainty, and exports. |
+| **py3plex 2.0** | Python | Query-driven, reproducible multilayer network analysis | Integrates capabilities otherwise spread across multilayer libraries, temporal engines, graph libraries, graph-ML frameworks, graph-query systems, and workflow tools | **Current version** py3plex 2.0 is best framed as a Python-native workflow layer for multilayer network science: DSL + builder API, layer algebra, QueryResult exports, uncertainty-first statistics, temporal/dynamics workflows, null models, CLI/config execution, and agent-facing interfaces. |
+
 ![Py3plex Visualization Showcase](example_images/py3plex_showcase.png)
 
 ## Getting Started
@@ -275,6 +299,7 @@ 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-1.1.7 → py3plex-2.0.0}/README.md

@@ -14,7 +14,7 @@
 ![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.4K-blue)
-![Test Count](https://img.shields.io/badge/tests-9.1K-blue)
+![Test Count](https://img.shields.io/badge/tests-9.2K-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.
@@ -101,6 +101,30 @@ Use a strict two-phase flow:
 - **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 | Ecosystem | Primary scope | Where it overlaps with py3plex 2.0 | py3plex 2.0 positioning |
+|---|---|---|---|---|
+| **py3plex 2019** | Python | Multilayer network visualization and analysis | Direct historical predecessor: multilayer representation, aggregation, indexing, traversal, visualization, and embedding-assisted layouts | **Historical foundation.** py3plex 2.0 extends the original toolkit from visualization-oriented analysis into a reproducible, query-driven multilayer network science environment. |
+| **pymnet** | Python | General multilayer network representation, metrics, random models, and visualization | Strong overlap on formal multilayer data structures, multilayer metrics, transformations, random models, and visualization | **Closest Python multilayer comparator.** pymnet is strongest as a formal multilayer framework; py3plex 2.0 is strongest as a workflow, DSL, uncertainty, and reproducibility layer. |
+| **MultiNetX** | Python / NetworkX | NetworkX-style multilayer graph manipulation, spectral analysis, and visualization | Overlap on Python-native multilayer graph objects, supra-adjacency/Laplacian workflows, and visualization | **Lightweight Python comparator.** MultiNetX provides compact multilayer graph utilities; py3plex 2.0 provides a broader end-to-end analysis and workflow environment. |
+| **muxViz** | R / desktop ecosystem | Multilayer and multiplex visual analytics | Overlap on multilayer visualization, centrality, community detection, motifs, structural reducibility, and dynamic visualization | **R visual-analytics comparator.** muxViz is strongest for visual exploration; py3plex 2.0 emphasizes Python-native, scriptable, DSL-driven, reproducible analysis. |
+| **R `multinet`** | R | Multiplex and multilayer social-network analysis and mining | Overlap on multilayer representation, import/export, attributes, centrality, community detection, generation, and plotting | **R social-network comparator.** `multinet` is strongest for multiplex social-network analysis; py3plex 2.0 targets broader heterogeneous scientific multilayer workflows in Python. |
+| **tnetwork** | Python | Temporal-network manipulation and dynamic communities | Overlap on temporal slicing, dynamic graphs, and evolving-community analysis | **Temporal-community comparator.** tnetwork focuses on temporal community workflows; py3plex 2.0 embeds temporal analysis inside a broader multilayer DSL/workflow stack. |
+| **DyNetx** | Python / NetworkX | Dynamic graph extension for NetworkX | Overlap on time-varying graph representation, snapshots, interaction streams, and temporal slicing | **Dynamic-NetworkX comparator.** DyNetx handles dynamic graphs; py3plex 2.0 adds multilayer semantics, declarative analysis, integrated dynamics, and reusable workflows. |
+| **Reticula** | Python with C++ core | Fast static and temporal network / hypergraph analysis | Overlap on temporal networks, reachability, randomized models, and dynamical-process analysis | **Performance temporal/hypergraph comparator.** Reticula is stronger for fast temporal and hypergraph analysis; py3plex 2.0 is stronger for multilayer workflow integration and analyst ergonomics. |
+| **Raphtory** | Rust / Python | Temporal graph engine and deployment platform | Overlap on temporal graph views, time-aware querying, reachability, motifs, and deployment-oriented graph analysis | **Modern temporal-engine comparator.** Raphtory is an engine/platform; py3plex 2.0 is a multilayer network-science workflow layer with DSL, uncertainty, dynamics, and reproducible analysis. |
+| **pathpy / pathpyG** | Python / PyTorch ecosystem | Path-centric temporal-network analytics and graph learning | Overlap on temporal analytics, time-respecting paths, temporal centralities, visualization, and graph-learning handoff | **Temporal graph-learning comparator.** pathpy/pathpyG is adjacent; py3plex 2.0 focuses on multilayer network science, layer-aware querying, uncertainty, and reproducible workflows. |
+| **NetworkX** | Python | General graph creation, manipulation, and algorithms | Overlap on core graph algorithms, graph data structures, centrality, communities, and Python graph workflows | **General graph substrate.** NetworkX is the base graph ecosystem; py3plex 2.0 adds multilayer semantics, DSL queries, layer algebra, temporal/dynamics workflows, and structured outputs. |
+| **igraph** | C / R / Python | Efficient general-purpose network analysis | Overlap on centrality, community detection, graph transformations, and scalable graph analysis | **Efficient general-graph comparator.** igraph is the speed/breadth baseline; py3plex 2.0 differentiates through multilayer-specific workflows and reproducible analyst interfaces. |
+| **graph-tool** | Python with C++ core | High-performance graph algorithms and statistical network modeling | Overlap on large-network statistics, community detection, inference, and performance-sensitive graph analysis | **Performance/statistical comparator.** graph-tool is strongest for efficient statistical graph analysis; py3plex 2.0 prioritizes multilayer expressiveness, querying, uncertainty, and workflow integration. |
+| **tidygraph** | R / tidyverse | Tidy, dplyr-style graph manipulation | Overlap on chainable, analyst-friendly node/edge manipulation and graph-as-table workflows | **Analyst-grammar comparator.** tidygraph motivates fluent graph manipulation; py3plex 2.0 adapts this style to Python multilayer networks with DSL, builder APIs, and layer-aware grouping. |
+| **NDlib** | Python | Diffusion and epidemic processes on networks | Overlap on SIS/SIR-style processes, random walks, spreading dynamics, and simulation workflows | **Dynamics comparator.** NDlib specializes in diffusion; py3plex 2.0 embeds dynamics inside multilayer, temporal, queryable, uncertainty-aware workflows. |
+| **PyTorch Geometric** | Python / PyTorch | Graph neural networks and geometric deep learning | Overlap on graph embeddings, graph data preparation, and downstream graph-learning workflows | **Graph-ML comparator.** PyG trains graph neural models; py3plex 2.0 prepares, queries, explains, summarizes, and analyzes multilayer networks. |
+| **DGL** | Python / deep-learning frameworks | Scalable graph deep learning and message passing | Overlap on heterogeneous graph processing, graph learning, and scalable graph ML pipelines | **Scalable graph-ML comparator.** DGL addresses GNN systems engineering; py3plex 2.0 addresses multilayer network science, query abstractions, uncertainty, temporal analysis, and workflows. |
+| **Neo4j / Cypher** | Database systems | Persistent property-graph storage and declarative graph querying | Overlap on declarative graph querying and pattern-style graph access | **Graph-query comparator.** Cypher queries persistent property graphs; py3plex 2.0 provides an in-memory scientific DSL for multilayer network analysis, metrics, uncertainty, and exports. |
+| **py3plex 2.0** | Python | Query-driven, reproducible multilayer network analysis | Integrates capabilities otherwise spread across multilayer libraries, temporal engines, graph libraries, graph-ML frameworks, graph-query systems, and workflow tools | **Current version** py3plex 2.0 is best framed as a Python-native workflow layer for multilayer network science: DSL + builder API, layer algebra, QueryResult exports, uncertainty-first statistics, temporal/dynamics workflows, null models, CLI/config execution, and agent-facing interfaces. |
+
 ![Py3plex Visualization Showcase](example_images/py3plex_showcase.png)
 
 ## Getting Started
@@ -176,6 +200,7 @@ 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-1.1.7 → py3plex-2.0.0}/py3plex/__init__.py

@@ -51,8 +51,8 @@ For detailed documentation, see: https://skblaz.github.io/py3plex/
 """
 
 # Version information
-__version__ = "1.1.7"
-__api_version__ = "1.1.7"
+__version__ = "2.0.0"
+__api_version__ = "2.0.0"
 
 from py3plex.core.multinet import multi_layer_network
 from py3plex.core.types import (

{py3plex-1.1.7 → py3plex-2.0.0}/py3plex/algorithms/community_detection/autocommunity_executor.py

@@ -1221,7 +1221,7 @@ def execute_autocommunity_sh(
         import importlib.metadata
         py3plex_version = importlib.metadata.version('py3plex')
     except Exception:
-        py3plex_version = '1.1.2'  # Fallback for development installs
+        from py3plex import __version__ as py3plex_version
     
     provenance = {
         'engine': 'autocommunity_successive_halving',

{py3plex-1.1.7 → py3plex-2.0.0}/py3plex/config.py

@@ -218,8 +218,8 @@ WARN_DEPRECATED: bool = True
 # Library Metadata
 # ─────────────────────────────────────────────────────────────────────────────
 
-__api_version__ = "1.1.7"
-__version__ = "1.1.7"
+__api_version__ = "2.0.0"
+__version__ = "2.0.0"
 
 # ─────────────────────────────────────────────────────────────────────────────
 # Helper Functions

{py3plex-1.1.7 → py3plex-2.0.0}/py3plex/dsl/ast.py

@@ -293,6 +293,11 @@ class ComputeItem:
     random_state: Optional[int] = None
     approx: Optional["ApproximationSpec"] = None
     kind: Optional[str] = None
+    # Tracks whether compute() explicitly received uncertainty=...
+    # None: omitted (query-level UQ may apply)
+    # True: explicitly enabled
+    # False: explicitly disabled (query-level UQ opt-out for this metric)
+    uncertainty_explicit: Optional[bool] = None
 
     @property
     def result_name(self) -> str:

{py3plex-1.1.7 → py3plex-2.0.0}/py3plex/dsl/builder.py

@@ -917,6 +917,7 @@ class QueryBuilder:
                         random_state=random_state,
                         approx=measure_approx_spec,
                         kind=kind,
+                        uncertainty_explicit=uncertainty,
                     )
                 )
         elif alias and len(measures) == 1:
@@ -947,6 +948,7 @@ class QueryBuilder:
                     random_state=random_state,
                     approx=measure_approx_spec,
                     kind=kind,
+                    uncertainty_explicit=uncertainty,
                 )
             )
         else:
@@ -977,6 +979,7 @@ class QueryBuilder:
                         random_state=random_state,
                         approx=measure_approx_spec,
                         kind=kind,
+                        uncertainty_explicit=uncertainty,
                     )
                 )
 

{py3plex-1.1.7 → py3plex-2.0.0}/py3plex/dsl/uq_resolution.py

@@ -290,13 +290,14 @@ def resolve_uq_config(
         compute_item.n_null is not None,
     ])
     
-    if compute_item.uncertainty is False and not has_metric_uq_params:
-        # uncertainty=False is the default, so we only skip UQ when there is
-        # also no query-level UQ config.  If the caller set .uq(...) at the
-        # query level, that should still propagate down to this metric.
-        if query_uq_config is None or query_uq_config.method is None:
-            return None
-        # else: fall through so query-level UQ takes effect
+    # Tri-state semantics:
+    # - uncertainty_explicit is None: not provided, query-level UQ may apply
+    # - uncertainty_explicit is True: explicit enable
+    # - uncertainty_explicit is False: explicit disable for this metric unless
+    #   metric-level UQ params are also provided.
+    if compute_item.uncertainty_explicit is False and not has_metric_uq_params:
+        # Explicit opt-out from query-level .uq(...), unlike the default None case.
+        return None
     
     # Check if UQ is explicitly enabled at metric or query level
     uq_enabled = (

{py3plex-1.1.7 → py3plex-2.0.0}/py3plex/utils.py

@@ -407,48 +407,6 @@ def get_multilayer_dataset_path(relative_path: str) -> str:
     return get_data_path(f"multilayer_datasets/{relative_path}")
 
 
-def get_background_knowledge_path(filename: str) -> str:
-    """
-    Get the absolute path to a background knowledge file or directory.
-
-    Convenience wrapper around get_data_path() specifically for background knowledge files.
-
-    Args:
-        filename: Name or relative path of the background knowledge file.
-                 Use empty string or '.' to get the background_knowledge directory itself.
-
-    Returns:
-        str: Absolute path to the background knowledge file or directory
-
-    Examples:
-        >>> from py3plex.utils import get_background_knowledge_path
-        >>> path = get_background_knowledge_path("bk.n3")
-        >>> dir_path = get_background_knowledge_path(".")
-    """
-    # If the filename already includes "background_knowledge/", use it as-is
-    if filename.startswith("background_knowledge/"):
-        return get_data_path(filename)
-    # If empty string or '.', return the directory itself
-    if not filename or filename == '.':
-        return get_data_path("background_knowledge")
-    # Otherwise, prepend "background_knowledge/"
-    return get_data_path(f"background_knowledge/{filename}")
-
-
-def get_background_knowledge_dir() -> str:
-    """
-    Get the absolute path to the background knowledge directory.
-
-    Returns:
-        str: Absolute path to the background_knowledge directory
-
-    Examples:
-        >>> from py3plex.utils import get_background_knowledge_dir
-        >>> dir_path = get_background_knowledge_dir()
-    """
-    return get_data_path("background_knowledge")
-
-
 def get_layer_names(network) -> list:
     """
     Extract layer names from a multilayer network.

{py3plex-1.1.7 → py3plex-2.0.0/py3plex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py3plex
-Version: 1.1.7
+Version: 2.0.0
 Summary: A Multilayer network analysis python3 library
 Author-email: Blaž Škrlj <blaz.skrlj@ijs.si>
 License: MIT
@@ -113,7 +113,7 @@ Dynamic: license-file
 ![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.4K-blue)
-![Test Count](https://img.shields.io/badge/tests-9.1K-blue)
+![Test Count](https://img.shields.io/badge/tests-9.2K-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.
@@ -200,6 +200,30 @@ Use a strict two-phase flow:
 - **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 | Ecosystem | Primary scope | Where it overlaps with py3plex 2.0 | py3plex 2.0 positioning |
+|---|---|---|---|---|
+| **py3plex 2019** | Python | Multilayer network visualization and analysis | Direct historical predecessor: multilayer representation, aggregation, indexing, traversal, visualization, and embedding-assisted layouts | **Historical foundation.** py3plex 2.0 extends the original toolkit from visualization-oriented analysis into a reproducible, query-driven multilayer network science environment. |
+| **pymnet** | Python | General multilayer network representation, metrics, random models, and visualization | Strong overlap on formal multilayer data structures, multilayer metrics, transformations, random models, and visualization | **Closest Python multilayer comparator.** pymnet is strongest as a formal multilayer framework; py3plex 2.0 is strongest as a workflow, DSL, uncertainty, and reproducibility layer. |
+| **MultiNetX** | Python / NetworkX | NetworkX-style multilayer graph manipulation, spectral analysis, and visualization | Overlap on Python-native multilayer graph objects, supra-adjacency/Laplacian workflows, and visualization | **Lightweight Python comparator.** MultiNetX provides compact multilayer graph utilities; py3plex 2.0 provides a broader end-to-end analysis and workflow environment. |
+| **muxViz** | R / desktop ecosystem | Multilayer and multiplex visual analytics | Overlap on multilayer visualization, centrality, community detection, motifs, structural reducibility, and dynamic visualization | **R visual-analytics comparator.** muxViz is strongest for visual exploration; py3plex 2.0 emphasizes Python-native, scriptable, DSL-driven, reproducible analysis. |
+| **R `multinet`** | R | Multiplex and multilayer social-network analysis and mining | Overlap on multilayer representation, import/export, attributes, centrality, community detection, generation, and plotting | **R social-network comparator.** `multinet` is strongest for multiplex social-network analysis; py3plex 2.0 targets broader heterogeneous scientific multilayer workflows in Python. |
+| **tnetwork** | Python | Temporal-network manipulation and dynamic communities | Overlap on temporal slicing, dynamic graphs, and evolving-community analysis | **Temporal-community comparator.** tnetwork focuses on temporal community workflows; py3plex 2.0 embeds temporal analysis inside a broader multilayer DSL/workflow stack. |
+| **DyNetx** | Python / NetworkX | Dynamic graph extension for NetworkX | Overlap on time-varying graph representation, snapshots, interaction streams, and temporal slicing | **Dynamic-NetworkX comparator.** DyNetx handles dynamic graphs; py3plex 2.0 adds multilayer semantics, declarative analysis, integrated dynamics, and reusable workflows. |
+| **Reticula** | Python with C++ core | Fast static and temporal network / hypergraph analysis | Overlap on temporal networks, reachability, randomized models, and dynamical-process analysis | **Performance temporal/hypergraph comparator.** Reticula is stronger for fast temporal and hypergraph analysis; py3plex 2.0 is stronger for multilayer workflow integration and analyst ergonomics. |
+| **Raphtory** | Rust / Python | Temporal graph engine and deployment platform | Overlap on temporal graph views, time-aware querying, reachability, motifs, and deployment-oriented graph analysis | **Modern temporal-engine comparator.** Raphtory is an engine/platform; py3plex 2.0 is a multilayer network-science workflow layer with DSL, uncertainty, dynamics, and reproducible analysis. |
+| **pathpy / pathpyG** | Python / PyTorch ecosystem | Path-centric temporal-network analytics and graph learning | Overlap on temporal analytics, time-respecting paths, temporal centralities, visualization, and graph-learning handoff | **Temporal graph-learning comparator.** pathpy/pathpyG is adjacent; py3plex 2.0 focuses on multilayer network science, layer-aware querying, uncertainty, and reproducible workflows. |
+| **NetworkX** | Python | General graph creation, manipulation, and algorithms | Overlap on core graph algorithms, graph data structures, centrality, communities, and Python graph workflows | **General graph substrate.** NetworkX is the base graph ecosystem; py3plex 2.0 adds multilayer semantics, DSL queries, layer algebra, temporal/dynamics workflows, and structured outputs. |
+| **igraph** | C / R / Python | Efficient general-purpose network analysis | Overlap on centrality, community detection, graph transformations, and scalable graph analysis | **Efficient general-graph comparator.** igraph is the speed/breadth baseline; py3plex 2.0 differentiates through multilayer-specific workflows and reproducible analyst interfaces. |
+| **graph-tool** | Python with C++ core | High-performance graph algorithms and statistical network modeling | Overlap on large-network statistics, community detection, inference, and performance-sensitive graph analysis | **Performance/statistical comparator.** graph-tool is strongest for efficient statistical graph analysis; py3plex 2.0 prioritizes multilayer expressiveness, querying, uncertainty, and workflow integration. |
+| **tidygraph** | R / tidyverse | Tidy, dplyr-style graph manipulation | Overlap on chainable, analyst-friendly node/edge manipulation and graph-as-table workflows | **Analyst-grammar comparator.** tidygraph motivates fluent graph manipulation; py3plex 2.0 adapts this style to Python multilayer networks with DSL, builder APIs, and layer-aware grouping. |
+| **NDlib** | Python | Diffusion and epidemic processes on networks | Overlap on SIS/SIR-style processes, random walks, spreading dynamics, and simulation workflows | **Dynamics comparator.** NDlib specializes in diffusion; py3plex 2.0 embeds dynamics inside multilayer, temporal, queryable, uncertainty-aware workflows. |
+| **PyTorch Geometric** | Python / PyTorch | Graph neural networks and geometric deep learning | Overlap on graph embeddings, graph data preparation, and downstream graph-learning workflows | **Graph-ML comparator.** PyG trains graph neural models; py3plex 2.0 prepares, queries, explains, summarizes, and analyzes multilayer networks. |
+| **DGL** | Python / deep-learning frameworks | Scalable graph deep learning and message passing | Overlap on heterogeneous graph processing, graph learning, and scalable graph ML pipelines | **Scalable graph-ML comparator.** DGL addresses GNN systems engineering; py3plex 2.0 addresses multilayer network science, query abstractions, uncertainty, temporal analysis, and workflows. |
+| **Neo4j / Cypher** | Database systems | Persistent property-graph storage and declarative graph querying | Overlap on declarative graph querying and pattern-style graph access | **Graph-query comparator.** Cypher queries persistent property graphs; py3plex 2.0 provides an in-memory scientific DSL for multilayer network analysis, metrics, uncertainty, and exports. |
+| **py3plex 2.0** | Python | Query-driven, reproducible multilayer network analysis | Integrates capabilities otherwise spread across multilayer libraries, temporal engines, graph libraries, graph-ML frameworks, graph-query systems, and workflow tools | **Current version** py3plex 2.0 is best framed as a Python-native workflow layer for multilayer network science: DSL + builder API, layer algebra, QueryResult exports, uncertainty-first statistics, temporal/dynamics workflows, null models, CLI/config execution, and agent-facing interfaces. |
+
 ![Py3plex Visualization Showcase](example_images/py3plex_showcase.png)
 
 ## Getting Started
@@ -275,6 +299,7 @@ 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-1.1.7 → py3plex-2.0.0}/py3plex.egg-info/SOURCES.txt

@@ -741,6 +741,7 @@ tests/test_meta_analysis.py
 tests/test_meta_flow_report.py
 tests/test_metamorphic.py
 tests/test_metapath2vec.py
+tests/test_ml_embedding_evaluation.py
 tests/test_ml_embedding_primitives.py
 tests/test_monoplex_nx_wrapper.py
 tests/test_mpc.py

{py3plex-1.1.7 → py3plex-2.0.0}/py3plex_mcp/__init__.py

@@ -7,10 +7,10 @@ Usage:
     pip install py3plex[mcp]
     py3plex-mcp
 
-Version: 1.1.7
+Version: 2.0.0
 """
 
-__version__ = "1.1.7"
+__version__ = "2.0.0"
 
 __all__ = [
     "__version__",

{py3plex-1.1.7 → py3plex-2.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "py3plex"
-version = "1.1.7"
+version = "2.0.0"
 description = "A Multilayer network analysis python3 library"
 readme = "README.md"
 requires-python = ">=3.8"

{py3plex-1.1.7 → py3plex-2.0.0}/tests/test_book_conf.py

@@ -38,7 +38,7 @@ def test_conf_exposes_expected_metadata(conf_module):
     module, expected_path = conf_module
 
     assert module.project == "Practical Multilayer Network Analysis with Py3plex"
-    assert module.version == module.release == "1.1.7"
+    assert module.version == module.release == "2.0.0"
     assert module.language == "en"
     assert module.master_doc == "index"
     assert module.templates_path == ["_templates"]

{py3plex-1.1.7 → py3plex-2.0.0}/tests/test_book_manuscript_integrity.py

@@ -11,7 +11,7 @@ def _read(path: str) -> str:
 
 def test_front_matter_uses_canonical_version():
     text = _read("front_matter.rst")
-    assert "version 1.1.7 (2026)" in text
+    assert "version 2.0.0 (2026)" in text
     assert "version 1.0 (2025)" not in text
 
 

{py3plex-1.1.7 → py3plex-2.0.0}/tests/test_data_files_presence.py

@@ -15,10 +15,10 @@ import pytest
     "relative_path",
     [
         "datasets/community.dat",
+        "datasets/bk.n3",
         "datasets/cora.mat",
         "multilayer_datasets/aarhusCS/CS-Aarhus_multiplex.edges",
         "multilayer_datasets/MLKing/MLKing2013_multiplex.edges",
-        "background_knowledge/bk.n3",
         "example_images/communities.png",
     ],
 )

{py3plex-1.1.7 → py3plex-2.0.0}/tests/test_example_CBSSD.py

@@ -15,7 +15,6 @@ def load_example_with_fakes(monkeypatch):
     """Load the CBSSD example with lightweight fakes to observe side effects."""
     record = []
     dataset_calls = []
-    data_calls = []
     context = {}
     fake_partition = {"P12345": 1, "Q8ABC1": 2}
 
@@ -54,16 +53,6 @@ def load_example_with_fakes(monkeypatch):
         record.append(("get_dataset_path", name, path))
         return path
 
-    def get_data_path(name):
-        path = f"/data/{name}"
-        data_calls.append((name, path))
-        record.append(("get_data_path", name, path))
-        return path
-
-    def get_background_knowledge_dir():
-        record.append(("get_background_knowledge_dir",))
-        return "/bkdir"
-
     def louvain_communities(network):
         record.append(("louvain_communities", network))
         return fake_partition
@@ -106,8 +95,6 @@ def load_example_with_fakes(monkeypatch):
 
     utils_mod = types.ModuleType("py3plex.utils")
     utils_mod.get_dataset_path = get_dataset_path
-    utils_mod.get_data_path = get_data_path
-    utils_mod.get_background_knowledge_dir = get_background_knowledge_dir
 
     algorithms_mod.hedwig = hedwig_mod
     algorithms_mod.community_detection = community_detection_mod
@@ -135,7 +122,6 @@ def load_example_with_fakes(monkeypatch):
         "module": module,
         "record": record,
         "dataset_calls": dataset_calls,
-        "data_calls": data_calls,
         "context": context,
         "fake_network": fake_network,
         "fake_partition": fake_partition,
@@ -146,7 +132,6 @@ def test_cbssd_example_triggers_pipeline(monkeypatch, capsys):
     result = load_example_with_fakes(monkeypatch)
     record = result["record"]
     dataset_calls = result["dataset_calls"]
-    data_calls = result["data_calls"]
     fake_network = result["fake_network"]
     fake_partition = result["fake_partition"]
     out = capsys.readouterr().out
@@ -161,6 +146,7 @@ def test_cbssd_example_triggers_pipeline(monkeypatch, capsys):
         "intact02.gpickle",
         "example_partition_inputs.n3",
         "goa_human.gaf.gz",
+        "bk.n3",
         "go.obo.gz",
         "goa_human.gaf.gz",
         "example_partition_inputs.n3",
@@ -179,18 +165,17 @@ def test_cbssd_example_triggers_pipeline(monkeypatch, capsys):
     rdf = result["context"]["rdf"]
     assert rdf.serialized == [("/datasets/example_partition_inputs.n3", "n3")]
 
-    # background knowledge and OBO conversion use derived paths
-    assert data_calls == [("background_knowledge/bk.n3", "/data/background_knowledge/bk.n3")]
+    # background knowledge and OBO conversion use derived dataset paths
     obo_call = next(entry for entry in record if entry[0] == "obo2n3")
     assert obo_call[1:] == (
         "/datasets/go.obo.gz",
-        "/data/background_knowledge/bk.n3",
+        "/datasets/bk.n3",
         "/datasets/goa_human.gaf.gz",
     )
 
     # rule learning parameters are propagated intact
     run_params = result["context"]["run_params"]
-    assert run_params["bk_dir"] == "/bkdir"
+    assert run_params["bk_dir"] == "/datasets"
     assert run_params["data"] == "/datasets/example_partition_inputs.n3"
     assert run_params["format"] == "n3"
     assert run_params["beam"] == 300

py3plex-2.0.0/tests/test_ml_embedding_evaluation.py

@@ -0,0 +1,159 @@
+"""Focused tests for embedding evaluation helpers."""
+
+from __future__ import annotations
+
+from unittest.mock import Mock
+
+import numpy as np
+import pytest
+
+from py3plex.embeddings.base import EmbeddingResult
+from py3plex.ml.embedding import evaluation
+
+
+def _embedding() -> EmbeddingResult:
+    matrix = np.array(
+        [
+            [1.0, 0.0, 0.5],
+            [0.9, 0.1, 0.4],
+            [0.0, 1.0, 0.2],
+            [0.1, 0.9, 0.3],
+            [0.8, 0.2, 0.1],
+            [0.2, 0.8, 0.6],
+        ],
+        dtype=np.float32,
+    )
+    return EmbeddingResult(
+        matrix=matrix, item_ids=["a", "b", "c", "d", "e", "f"], method="test"
+    )
+
+
+def test_edge_operator_hadamard_average_l1_l2():
+    u = np.array([1.0, 2.0], dtype=np.float32)
+    v = np.array([3.0, 4.0], dtype=np.float32)
+
+    np.testing.assert_allclose(evaluation.edge_operator(u, v, "hadamard"), np.array([3.0, 8.0]))
+    np.testing.assert_allclose(evaluation.edge_operator(u, v, "average"), np.array([2.0, 3.0]))
+    np.testing.assert_allclose(
+        evaluation.edge_operator(u, v, "weighted_l1"), np.array([2.0, 2.0])
+    )
+    np.testing.assert_allclose(
+        evaluation.edge_operator(u, v, "weighted_l2"), np.array([4.0, 4.0])
+    )
+
+
+def test_edge_operator_cosine_output():
+    u = np.array([1.0, 2.0], dtype=np.float32)
+    v = np.array([3.0, 4.0], dtype=np.float32)
+    cosine = evaluation.edge_operator(u, v, "cosine")
+    assert cosine.shape == (1,)
+    assert np.isfinite(cosine[0])
+
+
+def test_edge_operator_invalid_operator():
+    u = np.array([1.0, 2.0], dtype=np.float32)
+    v = np.array([3.0, 4.0], dtype=np.float32)
+    with pytest.raises(ValueError, match="Unknown edge operator"):
+        evaluation.edge_operator(u, v, "invalid")
+
+
+def test_build_edge_features_handles_empty_input_and_cosine_shape():
+    emb = _embedding()
+
+    empty_hadamard = evaluation.build_edge_features(emb, [], operator="hadamard")
+    assert empty_hadamard.shape == (0, emb.dim)
+
+    empty_cosine = evaluation.build_edge_features(emb, [], operator="cosine")
+    assert empty_cosine.shape == (0, 1)
+
+
+def test_evaluate_link_prediction_embeddings_success_and_error():
+    emb = _embedding()
+    positive_edges = [("a", "b"), ("a", "d"), ("c", "d"), ("b", "d"), ("e", "f")]
+    negative_edges = [("a", "c"), ("b", "c"), ("a", "e"), ("b", "f"), ("c", "e")]
+
+    metrics = evaluation.evaluate_link_prediction_embeddings(
+        emb,
+        positive_edges,
+        negative_edges,
+        operator="average",
+        random_state=42,
+    )
+    assert set(metrics) == {"roc_auc", "average_precision"}
+    assert 0.0 <= metrics["roc_auc"] <= 1.0
+    assert 0.0 <= metrics["average_precision"] <= 1.0
+
+    with pytest.raises(ValueError, match="Both positive and negative edges"):
+        evaluation.evaluate_link_prediction_embeddings(
+            emb,
+            positive_edges,
+            [],
+            operator="hadamard",
+            random_state=42,
+        )
+
+
+def test_evaluate_link_prediction_helper():
+    auc = evaluation.evaluate_link_prediction([0, 0, 1, 1], [0.1, 0.2, 0.8, 0.9])
+    assert auc == pytest.approx(1.0)
+
+
+def test_evaluate_node_classification_helper():
+    X = np.array(
+        [
+            [1.0, 0.0],
+            [0.9, 0.1],
+            [0.1, 0.9],
+            [0.0, 1.0],
+            [1.0, 0.1],
+            [0.1, 1.0],
+        ],
+        dtype=np.float32,
+    )
+    y = [0, 0, 1, 1, 0, 1]
+
+    macro_f1 = evaluation.evaluate_node_classification(X, y, test_size=0.33, random_state=7)
+    assert 0.0 <= macro_f1 <= 1.0
+
+
+def test_evaluate_clustering_helper():
+    clustering = evaluation.evaluate_clustering([0, 0, 1, 1], [0, 0, 1, 1])
+    assert clustering["NMI"] == pytest.approx(1.0)
+    assert clustering["ARI"] == pytest.approx(1.0)
+
+
+def test_evaluate_node_classification_report_fallback_branch(monkeypatch):
+    X_train = np.array([[1.0, 0.0], [0.0, 1.0], [0.8, 0.2], [0.2, 0.8]], dtype=np.float32)
+    X_test = np.array([[0.9, 0.1], [0.1, 0.9]], dtype=np.float32)
+    y_train = np.array([0, 1, 0, 1])
+    y_test = np.array([0, 1])
+
+    split_mock = Mock(
+        side_effect=[
+            ValueError("forced split failure"),
+            (X_train, X_test, y_train, y_test),
+        ]
+    )
+    monkeypatch.setattr(evaluation, "train_test_split", split_mock)
+
+    report = evaluation.evaluate_node_classification_report(
+        np.zeros((6, 2), dtype=np.float32),
+        [0, 1, 0, 1, 0, 1],
+        random_state=0,
+    )
+
+    assert split_mock.call_count == 2
+    assert set(report) == {"accuracy", "micro_f1", "macro_f1"}
+    assert 0.0 <= report["accuracy"] <= 1.0
+
+
+def test_evaluate_node_classification_report_raises_when_fallback_also_fails(monkeypatch):
+    split_mock = Mock(side_effect=ValueError("split failed"))
+    monkeypatch.setattr(evaluation, "train_test_split", split_mock)
+
+    with pytest.raises(ValueError, match="split failed"):
+        evaluation.evaluate_node_classification_report(
+            np.zeros((6, 2), dtype=np.float32),
+            [0, 1, 0, 1, 0, 1],
+            random_state=0,
+        )