py3plex 1.1.4__tar.gz → 1.1.5__tar.gz

{py3plex-1.1.4/py3plex.egg-info → py3plex-1.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py3plex
-Version: 1.1.4
+Version: 1.1.5
 Summary: A Multilayer network analysis python3 library
 Author-email: Blaž Škrlj <blaz.skrlj@ijs.si>
 License: MIT
@@ -100,10 +100,11 @@ Dynamic: license-file
 [![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-206.0K-blue)
-![Test Count](https://img.shields.io/badge/tests-8.9K-blue)
+![Lines of Code](https://img.shields.io/badge/lines-209.4K-blue)
+![Test Count](https://img.shields.io/badge/tests-9.0K-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.

{py3plex-1.1.4 → py3plex-1.1.5}/README.md

@@ -10,10 +10,11 @@
 [![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-206.0K-blue)
-![Test Count](https://img.shields.io/badge/tests-8.9K-blue)
+![Lines of Code](https://img.shields.io/badge/lines-209.4K-blue)
+![Test Count](https://img.shields.io/badge/tests-9.0K-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.

{py3plex-1.1.4 → py3plex-1.1.5}/py3plex/__init__.py

@@ -51,8 +51,8 @@ For detailed documentation, see: https://skblaz.github.io/py3plex/
 """
 
 # Version information
-__version__ = "1.1.4"
-__api_version__ = "1.1.4"
+__version__ = "1.1.5"
+__api_version__ = "1.1.5"
 
 from py3plex.core.multinet import multi_layer_network
 from py3plex.core.types import (
@@ -146,6 +146,7 @@ from py3plex.pipeline import (
     ComputeStats,
     FilterNodes,
     SaveNetwork,
+    NodeEmbedding,
 )
 
 # Config-driven workflows
@@ -284,6 +285,7 @@ __all__ = [
     "ComputeStats",
     "FilterNodes",
     "SaveNetwork",
+    "NodeEmbedding",
     # Workflows
     "WorkflowConfig",
     "WorkflowRunner",

{py3plex-1.1.4 → py3plex-1.1.5}/py3plex/cli.py

@@ -3036,8 +3036,7 @@ def cmd_capabilities(args: argparse.Namespace) -> int:
             print(_json.dumps(flat, indent=2))
         else:
             for key, val in flat.items():
-                marker = "✓" if val else "✗"
-                print(f"  {marker}  {key}")
+                print(f"    {key}: {bool(val)}")
         return 0
 
     caps = capabilities()

{py3plex-1.1.4 → py3plex-1.1.5}/py3plex/config.py

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

{py3plex-1.1.4 → py3plex-1.1.5}/py3plex/core/multinet.py

@@ -2,7 +2,11 @@
 
 import itertools
 import os
+import hashlib
+import json
+import pathlib
 from collections import defaultdict
+from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional, Tuple, Union
 import matplotlib.pyplot as plt
 
@@ -2083,6 +2087,250 @@ class multi_layer_network:
 
         yield from self.core_network.nodes(data=data)
 
+    def embed(
+        self,
+        method: str = "node2vec",
+        dimensions: int = 128,
+        walk_length: int = 40,
+        num_walks: int = 10,
+        context_size: int = 10,
+        workers: int = 4,
+        **kwargs: Any,
+    ) -> Any:
+        """Learn node embeddings as a first-class ML primitive.
+
+        Args:
+            method: Embedding backend name.
+            dimensions: Embedding dimensionality.
+            walk_length: Random-walk length for walk-based models.
+            num_walks: Number of walks per node for walk-based models.
+            context_size: Skipgram context window.
+            workers: Number of workers (reserved for backend implementations).
+            **kwargs: Method-specific parameters.
+
+        Returns:
+            EmbeddingResult aligned with ``self.get_nodes()``.
+        """
+        import py3plex
+
+        from py3plex.ml.embedding import (
+            DeepWalkEmbedding,
+            LINEEmbedding,
+            MetaPath2VecEmbedding,
+            MultiplexNode2Vec,
+            NetMFEmbedding,
+            Node2VecEmbedding,
+            SupraAdjacencyEmbedding,
+            LayerRegularizedEmbedding,
+        )
+
+        method_key = str(method).lower()
+        seed = kwargs.pop("seed", None)
+        backend = kwargs.pop("backend", "numpy")
+        window_size = kwargs.pop("window_size", context_size)
+        cache_enabled = bool(kwargs.pop("cache", False))
+        cache_dir = kwargs.pop("cache_dir", None)
+
+        embed_parameters = {
+            "method": method_key,
+            "dimensions": int(dimensions),
+            "walk_length": int(walk_length),
+            "num_walks": int(num_walks),
+            "context_size": int(context_size),
+            "window_size": int(window_size),
+            "workers": int(workers),
+            "seed": seed,
+            "backend": backend,
+            **dict(kwargs),
+        }
+        try:
+            graph_hash = self.fingerprint()
+            if not isinstance(graph_hash, str):
+                graph_hash = json.dumps(graph_hash, sort_keys=True, default=str)
+        except Exception as exc:
+            logger.warning("Failed to compute graph fingerprint for embedding cache: %s", exc)
+            node_snapshot = list(self.get_nodes())
+            layer_labels = sorted(
+                {
+                    str(node[1])
+                    for node in node_snapshot
+                    if isinstance(node, tuple) and len(node) >= 2
+                }
+            )
+            fallback_fp = {
+                "nodes": len(node_snapshot),
+                "edges": len(list(self.get_edges())),
+                "layers": layer_labels,
+            }
+            graph_hash = hashlib.sha256(
+                json.dumps(fallback_fp, sort_keys=True, default=str).encode()
+            ).hexdigest()[:16]
+
+        cache_payload = {
+            "graph_structure_hash": graph_hash,
+            "method": method_key,
+            "parameters": embed_parameters,
+            "version": py3plex.__version__,
+            "network_version": getattr(self, "network_version", None),
+        }
+        cache_hash = hashlib.sha256(
+            json.dumps(cache_payload, sort_keys=True, default=str).encode()
+        ).hexdigest()[:16]
+        cache_path = None
+        fallback_cache_path = None
+        if cache_enabled:
+            cache_root = pathlib.Path(cache_dir) if cache_dir else pathlib.Path.cwd()
+            cache_root.mkdir(parents=True, exist_ok=True)
+            cache_path = cache_root / f"embedding_{cache_hash}.parquet"
+            fallback_cache_path = cache_root / f"embedding_{cache_hash}.npz"
+            existing_cache_path = (
+                cache_path if cache_path.exists() else fallback_cache_path
+            )
+            if existing_cache_path.exists():
+                from py3plex.embeddings.base import EmbeddingResult
+
+                loaded = EmbeddingResult.load(str(existing_cache_path))
+                loaded.meta.update(
+                    {
+                        "method": method_key,
+                        "parameters": embed_parameters,
+                        "graph_hash": graph_hash,
+                        "creation_time": loaded.meta.get(
+                            "creation_time", datetime.now(timezone.utc).isoformat()
+                        ),
+                        "library_version": py3plex.__version__,
+                        "cache_key": cache_hash,
+                        "cache_path": str(existing_cache_path),
+                        "cache_hit": True,
+                    }
+                )
+                if hasattr(self, "embedding"):
+                    self.embedding = loaded
+                else:
+                    setattr(self, "embedding", loaded)
+                return loaded
+
+        if method_key == "node2vec":
+            model = Node2VecEmbedding(
+                dimensions=dimensions,
+                walk_length=walk_length,
+                num_walks=num_walks,
+                p=float(kwargs.pop("p", 1.0)),
+                q=float(kwargs.pop("q", 1.0)),
+                window_size=window_size,
+                negative_samples=int(kwargs.pop("negative_samples", 5)),
+                workers=workers,
+                backend=backend,
+                seed=seed,
+            )
+        elif method_key == "deepwalk":
+            model = DeepWalkEmbedding(
+                dimensions=dimensions,
+                walk_length=walk_length,
+                num_walks=num_walks,
+                window_size=window_size,
+                negative_samples=int(kwargs.pop("negative_samples", 5)),
+                workers=workers,
+                backend=backend,
+                seed=seed,
+            )
+        elif method_key == "netmf":
+            model = NetMFEmbedding(
+                dimensions=dimensions,
+                window=int(kwargs.pop("window", context_size)),
+                negative=float(kwargs.pop("negative", 1.0)),
+                multilayer=str(kwargs.pop("multilayer", "supra")),
+                gamma=float(kwargs.pop("gamma", 1.0)),
+                approx=str(kwargs.pop("approx", "randomized_svd")),
+                seed=seed,
+            )
+        elif method_key == "line":
+            model = LINEEmbedding(
+                dimensions=dimensions,
+                order=int(kwargs.pop("order", 2)),
+                negative_samples=int(kwargs.pop("negative_samples", 5)),
+                lr=float(kwargs.pop("lr", 0.025)),
+                epochs=int(kwargs.pop("epochs", 5)),
+                seed=seed,
+            )
+        elif method_key == "metapath2vec":
+            model = MetaPath2VecEmbedding(
+                metapaths=list(kwargs.pop("metapaths", [])),
+                dimensions=dimensions,
+                walk_length=walk_length,
+                num_walks=num_walks,
+                window_size=window_size,
+                negative_samples=int(kwargs.pop("negative_samples", 5)),
+                epochs=int(kwargs.pop("epochs", 5)),
+                seed=seed,
+            )
+        elif method_key in {"multiplex_node2vec", "multiplex-node2vec"}:
+            model = MultiplexNode2Vec(
+                dimensions=dimensions,
+                walk_length=walk_length,
+                num_walks=num_walks,
+                p=float(kwargs.pop("p", 1.0)),
+                q=float(kwargs.pop("q", 1.0)),
+                window_size=window_size,
+                negative_samples=int(kwargs.pop("negative_samples", 5)),
+                workers=workers,
+                backend=backend,
+                layer_weight=float(kwargs.pop("layer_weight", 1.0)),
+                seed=seed,
+            )
+        elif method_key in {"supra_adjacency", "supra"}:
+            model = SupraAdjacencyEmbedding(
+                dimensions=dimensions,
+                gamma=float(kwargs.pop("gamma", 1.0)),
+                seed=seed,
+            )
+        elif method_key in {"layer_regularized", "layer-regularized"}:
+            model = LayerRegularizedEmbedding(
+                dimensions=dimensions,
+                alpha=float(kwargs.pop("alpha", 0.5)),
+                seed=seed,
+            )
+        else:
+            raise ValueError(
+                f"Unknown embedding method '{method}'. "
+                "Expected one of: node2vec, deepwalk, netmf, line, "
+                "metapath2vec, multiplex_node2vec, supra_adjacency, layer_regularized."
+            )
+
+        embedding = model.fit_transform(self)
+        embedding.meta.update(
+            {
+                "method": method_key,
+                "parameters": embed_parameters,
+                "graph_hash": graph_hash,
+                "creation_time": datetime.now(timezone.utc).isoformat(),
+                "library_version": py3plex.__version__,
+                "cache_key": cache_hash if cache_enabled else None,
+                "cache_path": str(cache_path) if cache_path else None,
+                "cache_hit": False,
+            }
+        )
+        if cache_enabled and cache_path is not None:
+            try:
+                embedding.to_parquet(str(cache_path))
+            except Exception as exc:
+                logger.warning("Failed to write parquet embedding cache %s: %s", cache_path, exc)
+                if fallback_cache_path is not None:
+                    try:
+                        embedding.save(str(fallback_cache_path))
+                        embedding.meta["cache_path"] = str(fallback_cache_path)
+                    except Exception as fallback_exc:
+                        logger.warning(
+                            "Failed to write fallback embedding cache %s: %s",
+                            fallback_cache_path,
+                            fallback_exc,
+                        )
+        if hasattr(self, "embedding"):
+            self.embedding = embedding
+        else:
+            setattr(self, "embedding", embedding)
+        return embedding
+
     def merge_with(self, target_px_object):
         """
         Merge two px objects.

{py3plex-1.1.4 → py3plex-1.1.5}/py3plex/dsl/__init__.py

@@ -106,6 +106,16 @@ from .ast import (
     SemiringClosureStmt,
     SemiringFixedPointStmt,
     SemiringStmt,
+    PredictStmt,
+    LinkPredictionSpec,
+    SplitSpec,
+    NegativeSamplingSpec,
+    ModelSpec,
+    EdgeFeatureSpec,
+    EvalSpec,
+    ReduceStmt,
+    LayerReductionSpec,
+    DistanceSpec,
     # Benchmark AST nodes
     BenchmarkNode,
     BenchmarkAlgorithmSpec,
@@ -141,6 +151,8 @@ from .builder import (
     CounterexampleBuilder,
     # Claim learning builder
     ClaimLearnerBuilder,
+    LinkPredictionBuilder,
+    LayerReductionBuilder,
 )
 
 from .benchmark import (
@@ -190,6 +202,8 @@ from .communities import (
 )
 
 from .result import QueryResult
+from .predictive import PredictionResult
+from .reduction import LayerReductionResult
 
 from .executor import execute_ast
 from .export import export_result, save_to_parquet, load_from_parquet
@@ -209,6 +223,11 @@ from .errors import (
     InvalidJoinKeyError,
     ComputedFieldMisuseError,
     InvalidGroupAggregateError,
+    PredictionTaskError,
+    SplitStrategyError,
+    NegativeSamplingError,
+    ReductionMethodError,
+    LayerReductionError,
 )
 
 # Import UQ resolution and validation
@@ -349,6 +368,16 @@ __all__ = [
     "SemiringClosureStmt",
     "SemiringFixedPointStmt",
     "SemiringStmt",
+    "PredictStmt",
+    "LinkPredictionSpec",
+    "SplitSpec",
+    "NegativeSamplingSpec",
+    "ModelSpec",
+    "EdgeFeatureSpec",
+    "EvalSpec",
+    "ReduceStmt",
+    "LayerReductionSpec",
+    "DistanceSpec",
     # Benchmark AST
     "BenchmarkNode",
     "BenchmarkAlgorithmSpec",
@@ -384,6 +413,8 @@ __all__ = [
     "CounterexampleBuilder",
     # Claim Learning Builder
     "ClaimLearnerBuilder",
+    "LinkPredictionBuilder",
+    "LayerReductionBuilder",
     # Benchmark Builder
     "B",
     "CommunityBenchmarkBuilder",
@@ -419,6 +450,8 @@ __all__ = [
     "compute_community_metric",
     # Result
     "QueryResult",
+    "PredictionResult",
+    "LayerReductionResult",
     "export_result",
     "save_to_parquet",
     "load_from_parquet",
@@ -439,6 +472,11 @@ __all__ = [
     "InvalidJoinKeyError",
     "ComputedFieldMisuseError",
     "InvalidGroupAggregateError",
+    "PredictionTaskError",
+    "SplitStrategyError",
+    "NegativeSamplingError",
+    "ReductionMethodError",
+    "LayerReductionError",
     # UQ Resolution
     "ResolvedUQConfig",
     "UQResolutionError",

{py3plex-1.1.4 → py3plex-1.1.5}/py3plex/dsl/ast.py

@@ -728,6 +728,12 @@ class EmbeddingSpec:
             of layer names, e.g. ``[["author","paper","author"]]``).
         walk_length: Random walk length for MetaPath2Vec.
         num_walks: Number of walks per node for MetaPath2Vec.
+        p: Node2Vec return parameter.
+        q: Node2Vec in-out parameter.
+        window_size: Context window for walk-based embedding training.
+        negative_samples: Negative samples for walk-based embedding training.
+        workers: Worker count for embedding training.
+        order: LINE order (1 or 2).
     """
 
     method: str = "netmf"
@@ -747,6 +753,12 @@ class EmbeddingSpec:
     metapaths: Optional[List[List[str]]] = None
     walk_length: int = 80
     num_walks: int = 10
+    p: float = 1.0
+    q: float = 1.0
+    window_size: int = 10
+    negative_samples: int = 5
+    workers: int = 1
+    order: int = 2
 
 
 @dataclass
@@ -1183,6 +1195,117 @@ class SemiringStmt:
     fixed_point: Optional[SemiringFixedPointStmt] = None
 
 
+# ==============================================================================
+# Predictive Task DSL AST Nodes
+# ==============================================================================
+
+
+@dataclass
+class SplitSpec:
+    """Data split strategy for predictive tasks."""
+
+    strategy: str = "random_holdout"
+    test_frac: float = 0.2
+    seed: Optional[int] = None
+    params: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class NegativeSamplingSpec:
+    """Negative sampling strategy for predictive tasks."""
+
+    strategy: str = "uniform"
+    ratio: float = 1.0
+    seed: Optional[int] = None
+    params: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ModelSpec:
+    """Predictive model specification."""
+
+    name: str
+    params: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class EdgeFeatureSpec:
+    """Edge feature operator for embedding pipelines."""
+
+    kind: str = "hadamard"
+    params: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class EvalSpec:
+    """Evaluation metrics specification."""
+
+    metrics: List[str] = field(default_factory=lambda: ["roc_auc"])
+    params: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class LinkPredictionSpec:
+    """Link prediction workflow specification."""
+
+    layers_expr: Optional[Any] = None  # LayerExpr or LayerSet
+    scope: Dict[str, Any] = field(default_factory=dict)
+    split: SplitSpec = field(default_factory=SplitSpec)
+    negative_sampling: NegativeSamplingSpec = field(default_factory=NegativeSamplingSpec)
+    model: ModelSpec = field(default_factory=lambda: ModelSpec(name="common_neighbors"))
+    edge_features: EdgeFeatureSpec = field(default_factory=EdgeFeatureSpec)
+    classifier: Optional[ModelSpec] = None
+    eval: EvalSpec = field(default_factory=EvalSpec)
+    top_k: Optional[int] = None
+    uq_config: Optional[UQConfig] = None
+    seed: Optional[int] = None
+
+
+@dataclass
+class PredictStmt:
+    """Top-level predictive task statement."""
+
+    task: str = "links"
+    spec: Optional[LinkPredictionSpec] = None
+
+
+# ==============================================================================
+# Layer Reduction DSL AST Nodes
+# ==============================================================================
+
+
+@dataclass
+class DistanceSpec:
+    """Distance/similarity function specification for layer reduction."""
+
+    name: str = "js_divergence"
+    params: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class LayerReductionSpec:
+    """Layer reduction workflow specification."""
+
+    method: str = "hierarchical_js"
+    target_k: int = 1
+    distance: Optional[DistanceSpec] = None
+    criterion: Optional[str] = None
+    min_similarity: Optional[float] = None
+    preserve_interlayer: bool = True
+    aggregate: str = "sum"
+    report_level: str = "full"
+    seed: Optional[int] = None
+    params: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ReduceStmt:
+    """Top-level reduce/simplify statement."""
+
+    target: str = "layers"
+    spec: Optional[LayerReductionSpec] = None
+
+
 # ==============================================================================
 # Benchmark AST Nodes
 # ==============================================================================