annnet 0.0.1__py3-none-any.whl

annnet/__init__.py

@@ -0,0 +1,89 @@
+# annnet/__init__.py
+"""annnet: single import, full API."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+from typing import Any
+
+# Lazily exposed submodules (imported on first attribute access)
+_lazy_submodules = {
+    # namespaces
+    "adapters": "annnet.adapters",
+    "io": "annnet.io",
+    "core": "annnet.core",
+    "algorithms": "annnet.algorithms",
+    "utils": "annnet.utils",
+    # adapter modules (direct convenience)
+    "graphml": "annnet.adapters.GraphML_adapter",
+    "sif": "annnet.adapters.SIF_adapter",
+    "sbml": "annnet.adapters.sbml_adapter",
+    "parquet": "annnet.adapters.GraphDir_Parquet_adapter",
+    "networkx": "annnet.adapters.networkx_adapter",
+    "igraph": "annnet.adapters.igraph_adapter",
+    "jsonio": "annnet.adapters.json_adapter",
+    "dataframe": "annnet.adapters.dataframe_adapter",
+    # io modules
+    "csvio": "annnet.io.csv",
+    "excelio": "annnet.io.excel",
+    "annnet": "annnet.io.io_annnet",
+}
+
+# Curated top-level symbols (lazy). name -> (module, attribute)
+_lazy_symbols: dict[str, tuple[str, str]] = {
+    # Core
+    "Graph": ("annnet.core.graph", "Graph"),
+    "graph": ("annnet.core.graph", "Graph"),
+    # Stdlib JSON I/O
+    "to_json": ("annnet.adapters.json_adapter", "to_json"),
+    "from_json": ("annnet.adapters.json_adapter", "from_json"),
+    # NetworkX adapter (optional dependency)
+    "to_nx": ("annnet.adapters.networkx_adapter", "to_nx"),
+    "from_nx": ("annnet.adapters.networkx_adapter", "from_nx"),
+    "from_nx_only": ("annnet.adapters.networkx_adapter", "from_nx_only"),
+    # GraphML
+    "to_graphml": ("annnet.adapters.GraphML_adapter", "to_graphml"),
+    "from_graphml": ("annnet.adapters.GraphML_adapter", "from_graphml"),
+    # SIF
+    "to_sif": ("annnet.adapters.SIF_adapter", "to_sif"),
+    "from_sif": ("annnet.adapters.SIF_adapter", "from_sif"),
+    # SBML (common direction)
+    "from_sbml": ("annnet.adapters.sbml_adapter", "from_sbml"),
+    # If you add export later: "to_sbml": ("annnet.adapters.sbml_adapter", "to_sbml"),
+    # Parquet GraphDir
+    "write_parquet_graphdir": (
+        "annnet.adapters.GraphDir_Parquet_adapter",
+        "write_parquet_graphdir",
+    ),
+    "read_parquet_graphdir": (
+        "annnet.adapters.GraphDir_Parquet_adapter",
+        "read_parquet_graphdir",
+    ),
+}
+
+__all__ = sorted(set(list(_lazy_submodules) + list(_lazy_symbols)))
+
+
+def __getattr__(name: str) -> Any:  # PEP 562: lazy attribute resolution
+    if name in _lazy_submodules:
+        return import_module(_lazy_submodules[name])
+    if name in _lazy_symbols:
+        mod, attr = _lazy_symbols[name]
+        return getattr(import_module(mod), attr)
+    raise AttributeError(name)
+
+
+def __dir__() -> list[str]:
+    return sorted(list(globals().keys()) + list(__all__))
+
+
+# Version: prefer internal, then fall back to distribution metadata
+try:
+    from ._version import __version__  # type: ignore
+except Exception:
+    try:
+        __version__ = _pkg_version("annnet")
+    except PackageNotFoundError:
+        __version__ = "0.0.0"

annnet/_metadata.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python
+
+#
+# This file is part of the `annnet` Python module
+#
+# Copyright 2025
+# Heidelberg University Hospital
+#
+# File author(s): Daniele Bottazzi (daniele.bottazzi@mail.polimi.it)
+#
+# Distributed under the MIT license
+# See the file `LICENSE` or read a copy at
+# https://opensource.org/license/mit
+#
+
+"""Package metadata (version, authors, etc)."""
+
+__all__ = ["get_metadata"]
+
+import importlib.metadata
+import os
+import pathlib
+
+import toml
+
+_VERSION = "0.0.1"
+
+
+def get_metadata() -> dict:
+    """Basic package metadata.
+
+    Retrieves package metadata from the current project directory or from
+    the installed package.
+    """
+
+    here = pathlib.Path(__file__).parent
+    pyproj_toml = "pyproject.toml"
+    meta = {}
+
+    for project_dir in (here, here.parent):
+        toml_path = str(project_dir.joinpath(pyproj_toml).absolute())
+
+        if os.path.exists(toml_path):
+            pyproject = toml.load(toml_path)
+
+            meta = {
+                "name": pyproject["tool"]["poetry"]["name"],
+                "version": pyproject["tool"]["poetry"]["version"],
+                "author": pyproject["tool"]["poetry"]["authors"],
+                "license": pyproject["tool"]["poetry"]["license"],
+                "full_metadata": pyproject,
+            }
+
+            break
+
+    if not meta:
+        try:
+            meta = {k.lower(): v for k, v in importlib.metadata.metadata(here.name).items()}
+
+        except importlib.metadata.PackageNotFoundError:
+            pass
+
+    meta["version"] = meta.get("version", None) or _VERSION
+
+    return meta
+
+
+metadata = get_metadata()
+__version__ = metadata.get("version", None)
+__author__ = metadata.get("author", None)
+__license__ = "MIT"

annnet/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

annnet/adapters/GraphDir_Parquet_adapter.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import polars as pl
+
+if TYPE_CHECKING:
+    from ..core.graph import Graph
+
+
+def _strip_nulls(d: dict):
+    # remove keys whose value is None or NaN
+    clean = {}
+    for k, v in list(d.items()):
+        if v is None:
+            continue
+        if isinstance(v, float) and math.isnan(v):
+            continue
+        clean[k] = v
+    return clean
+
+
+def _is_directed_eid(graph, eid):
+    """Best-effort directedness probe; default True."""
+    try:
+        return bool(getattr(graph, "edge_directed", {}).get(eid, True))
+    except Exception:
+        pass
+    try:
+        val = graph.get_edge_attribute(eid, "directed")
+        return bool(val) if val is not None else True
+    except Exception:
+        return True
+
+
+def _coerce_coeff_mapping(val):
+    """Normalize various serialized forms into {vertex: {__value: float}|float}.
+    Accepts dict | list | list-of-dicts | list-of-pairs | JSON string.
+    """
+    if val is None:
+        return {}
+    if isinstance(val, str):
+        try:
+            return _coerce_coeff_mapping(json.loads(val))
+        except Exception:
+            return {}
+    if isinstance(val, dict):
+        return val
+    if isinstance(val, (list, tuple)):
+        out = {}
+        for item in val:
+            if isinstance(item, dict):
+                if "vertex" in item and "__value" in item:
+                    out[item["vertex"]] = {"__value": item["__value"]}
+                else:
+                    for k, v in item.items():
+                        out[k] = v
+            elif isinstance(item, (list, tuple)) and len(item) == 2:
+                k, v = item
+                out[k] = v
+        return out
+    return {}
+
+
+def _endpoint_coeff_map(edge_attrs, private_key, endpoint_set):
+    """Return {vertex: float_coeff} for the given endpoint_set.
+    Reads from edge_attrs[private_key] which may be serialized in multiple shapes.
+    Missing endpoints default to 1.0.
+    """
+    raw_mapping = (edge_attrs or {}).get(private_key, {})
+    mapping = _coerce_coeff_mapping(raw_mapping)
+    endpoints = list(endpoint_set or mapping.keys())
+    out = {}
+    for u in endpoints:
+        val = mapping.get(u, 1.0)
+        if isinstance(val, dict):
+            val = val.get("__value", 1.0)
+        try:
+            out[u] = float(val)
+        except Exception:
+            out[u] = 1.0
+    return out
+
+
+def write_parquet_graphdir(graph: Graph, path):
+    """Write lossless GraphDir:
+      vertices.parquet, edges.parquet, layers.parquet, edge_layers.parquet, manifest.json
+    Wide tables (attrs as columns). Hyperedges stored with 'kind' and head/tail/members lists.
+    """
+    path = Path(path)
+    path.mkdir(parents=True, exist_ok=True)
+
+    # vertices
+    v_rows = []
+    for v in graph.vertices():
+        row = {"vertex_id": v}
+        try:
+            attrs = graph.vertex_attributes.filter(
+                graph.vertex_attributes["vertex_id"] == v
+            ).to_dicts()
+            if attrs:
+                d = dict(attrs[0])
+                d.pop("vertex_id", None)
+                row.update(d)
+        except Exception:
+            pass
+        v_rows.append(row)
+    pl.DataFrame(v_rows).write_parquet(path / "vertices.parquet", compression="zstd")
+
+    # edges
+    e_rows = []
+    for eidx in range(graph.number_of_edges()):
+        eid = graph.idx_to_edge[eidx]
+        S, T = graph.get_edge(eidx)
+        kind = graph.edge_kind.get(eid)
+        row = {
+            "edge_id": eid,
+            "kind": ("hyper" if kind == "hyper" else "binary"),
+            "directed": bool(_is_directed_eid(graph, eid)),
+            "weight": float(getattr(graph, "edge_weights", {}).get(eid, 1.0)),
+        }
+        try:
+            attrs = graph.edge_attributes.filter(graph.edge_attributes["edge_id"] == eid).to_dicts()
+            if attrs:
+                d = dict(attrs[0])
+                d.pop("edge_id", None)
+                row.update(d)
+        except Exception:
+            pass
+
+        if row["kind"] == "binary":
+            members = S | T
+            if len(members) == 1:
+                u = next(iter(members))
+                v = u
+            else:
+                u, v = sorted(members)
+            row.update({"source": u, "target": v})
+        else:
+            head_map = _endpoint_coeff_map(row, "__source_attr", S) or dict.fromkeys(S or [], 1.0)
+            tail_map = _endpoint_coeff_map(row, "__target_attr", T) or dict.fromkeys(T or [], 1.0)
+            row.update(
+                {
+                    "head": list(head_map.keys()),
+                    "tail": list(tail_map.keys()),
+                    "members": list({*head_map.keys(), *tail_map.keys()})
+                    if not row["directed"]
+                    else None,
+                }
+            )
+        e_rows.append(row)
+    pl.DataFrame(e_rows).write_parquet(path / "edges.parquet", compression="zstd")
+
+    # layers
+    L = []
+    try:
+        for lid in graph.list_layers(include_default=True):
+            L.append({"layer_id": lid})
+    except Exception:
+        pass
+    pl.DataFrame(L).write_parquet(path / "layers.parquet", compression="zstd")
+
+    # edge_layers
+    EL = []
+    try:
+        for lid in graph.list_layers(include_default=True):
+            for eid in graph.get_layer_edges(lid):
+                rec = {"layer_id": lid, "edge_id": eid}
+                try:
+                    w = graph.get_edge_layer_attr(lid, eid, "weight", default=None)
+                except Exception:
+                    try:
+                        w = graph.get_edge_layer_attr(lid, eid, "weight")
+                    except Exception:
+                        w = None
+                if w is not None:
+                    rec["weight"] = float(w)
+                EL.append(rec)
+    except Exception:
+        pass
+    pl.DataFrame(EL).write_parquet(path / "edge_layers.parquet", compression="zstd")
+
+    # manifest.json (tiny)
+    manifest = {
+        "format_version": 1,
+        "counts": {"V": len(v_rows), "E": len(e_rows), "layers": len(L)},
+        "schema": {"edges.kind": ["binary", "hyper"]},
+        "provenance": {"package": "annnet"},
+    }
+    (path / "manifest.json").write_text(json.dumps(manifest, indent=2))
+
+
+def read_parquet_graphdir(path) -> Graph:
+    """Read GraphDir (lossless vs write_parquet_graphdir())."""
+    from ..core.graph import Graph
+
+    path = Path(path)
+    V = pl.read_parquet(path / "vertices.parquet")
+    E = pl.read_parquet(path / "edges.parquet")
+    L = (
+        pl.read_parquet(path / "layers.parquet", use_pyarrow=True)
+        if (path / "layers.parquet").exists()
+        else pl.DataFrame([])
+    )
+    EL = (
+        pl.read_parquet(path / "edge_layers.parquet", use_pyarrow=True)
+        if (path / "edge_layers.parquet").exists()
+        else pl.DataFrame([])
+    )
+
+    H = Graph()
+    # vertices
+    for rec in V.to_dicts():
+        vid = rec.pop("vertex_id")
+        H.add_vertex(vid)
+        if rec:
+            H.set_vertex_attrs(vid, **rec)
+
+    # edges
+    for rec in E.to_dicts():
+        eid = rec.pop("edge_id")
+        kind = rec.pop("kind")
+        directed = bool(rec.pop("directed", True))
+        w = float(rec.pop("weight", 1.0))
+
+        if kind == "binary":
+            # take endpoints and drop hyper-only columns if present
+            u = rec.pop("source", None)
+            v = rec.pop("target", None)
+            # these can exist as NULL because the DF is wide
+            rec.pop("head", None)
+            rec.pop("tail", None)
+            rec.pop("members", None)
+
+            if u is None or v is None:
+                # defensive: reconstruct from any leftover endpoint list (rare)
+                # if nothing found, skip cleanly
+                continue
+
+            H.add_edge(u, v, edge_id=eid, edge_directed=directed)
+
+        else:  # hyper
+            head = rec.pop("head", None) or []
+            tail = rec.pop("tail", None) or []
+            members = rec.pop("members", None) or []
+            if directed:
+                H.add_hyperedge(head=list(head), tail=list(tail), edge_id=eid, edge_directed=True)
+            else:
+                if not members:
+                    members = list(set(head) | set(tail))
+                H.add_hyperedge(members=list(members), edge_id=eid, edge_directed=False)
+
+        # weight
+        H.edge_weights[eid] = w
+
+        # drop schema-nulls before attaching attrs (avoids head=None, etc.)
+        rec = _strip_nulls(rec)
+        if rec:
+            H.set_edge_attrs(eid, **rec)
+
+    # layers
+    for rec in L.to_dicts():
+        lid = rec.get("layer_id")
+        try:
+            if lid not in set(H.list_layers(include_default=True)):
+                H.add_layer(lid)
+        except Exception:
+            pass
+
+    # edge_layers
+    for rec in EL.to_dicts():
+        lid = rec.get("layer_id")
+        eid = rec.get("edge_id")
+        if lid is None or eid is None:
+            continue
+        try:
+            H.add_edge_to_layer(lid, eid)
+        except Exception:
+            pass
+        if "weight" in rec:
+            try:
+                H.set_edge_layer_attrs(lid, eid, weight=float(rec["weight"]))
+            except Exception:
+                try:
+                    H.set_edge_layer_attr(lid, eid, "weight", float(rec["weight"]))
+                except Exception:
+                    pass
+
+    return H

annnet/adapters/GraphML_adapter.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+from typing import TYPE_CHECKING
+
+import networkx as nx
+
+if TYPE_CHECKING:
+    from ..core.graph import Graph
+from .networkx_adapter import from_nx, from_nx_only, to_nx
+
+_BOOL = {"true": True, "false": False}
+_NUM_RE = re.compile(r"^[+-]?(?:\d+|\d*\.\d+)(?:[eE][+-]?\d+)?$")
+
+
+def _sanitize_graphml_inplace(G):
+    """Remove values GraphML can't encode and normalize types before write."""
+
+    def clean_dict(d: dict):
+        for k in list(d.keys()):
+            v = d[k]
+            if v is None or (isinstance(v, float) and math.isnan(v)):
+                del d[k]
+                continue
+            if isinstance(v, (str, int, float, bool)):
+                continue
+            try:
+                d[k] = json.dumps(v, ensure_ascii=False)
+            except Exception:
+                d[k] = str(v)
+
+    clean_dict(G.graph)
+    for _, data in G.nodes(data=True):
+        clean_dict(data)
+    for _, _, data in G.edges(data=True):
+        clean_dict(data)
+
+
+def _restore_types_graphml_inplace(G):
+    """Heuristically restore types after read_graphml."""
+
+    def coerce(s):
+        if not isinstance(s, str):
+            return s
+        t = s.strip()
+        low = t.lower()
+        if low in _BOOL:
+            return _BOOL[low]
+        if (t.startswith("{") and t.endswith("}")) or (t.startswith("[") and t.endswith("]")):
+            try:
+                return json.loads(t)
+            except Exception:
+                return t
+        if _NUM_RE.match(t):
+            try:
+                if "." not in t and "e" not in low:
+                    return int(t)
+                return float(t)
+            except Exception:
+                return t
+        return t
+
+    def fix_dict(d: dict):
+        for k in list(d.keys()):
+            d[k] = coerce(d[k])
+
+    fix_dict(G.graph)
+    for _, data in G.nodes(data=True):
+        fix_dict(data)
+    for _, _, data in G.edges(data=True):
+        fix_dict(data)
+
+
+def to_graphml(graph, path, *, directed=True, hyperedge_mode="reify", public_only=False):
+    """Export via NetworkX with reified hyperedges; sanitize attrs for GraphML.
+    Also writes a sidecar manifest for lossless re-import.
+    """
+    G, manifest = to_nx(
+        graph, directed=directed, hyperedge_mode=hyperedge_mode, public_only=public_only
+    )
+    _sanitize_graphml_inplace(G)
+    nx.write_graphml(G, path)
+    # sidecar manifest
+    mpath = str(path) + ".manifest.json"
+    with open(mpath, "w", encoding="utf-8") as f:
+        json.dump(manifest, f, ensure_ascii=False)
+
+
+def from_graphml(path, *, hyperedge="reified"):
+    """Import via NetworkX; if a sidecar manifest is present, use it as SSOT.
+    Otherwise, fall back to from_nx_only with type restoration.
+    """
+    G = nx.read_graphml(path)
+    _restore_types_graphml_inplace(G)
+    mpath = str(path) + ".manifest.json"
+    if os.path.exists(mpath):
+        with open(mpath, encoding="utf-8") as f:
+            manifest = json.load(f)
+        # Rebuild exactly from the manifest (lossless), ignoring GraphML-added noise
+        return from_nx(G, manifest, hyperedge=("reified" if hyperedge == "reified" else "none"))
+    # Fallback (no manifest available)
+    return from_nx_only(G, hyperedge=("reified" if hyperedge == "reified" else "none"))
+
+
+def to_gexf(graph: Graph, path, *, directed=True, hyperedge_mode="reify", public_only=False):
+    G, _m = to_nx(graph, directed=directed, hyperedge_mode=hyperedge_mode, public_only=public_only)
+    nx.write_gexf(G, path)
+
+
+def from_gexf(path, *, hyperedge="reified") -> Graph:
+    G = nx.read_gexf(path)
+    return from_nx_only(G, hyperedge=("reified" if hyperedge == "reified" else "none"))