muxpack 0.1.0__tar.gz

muxpack-0.1.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.3
+Name: muxpack
+Version: 0.1.0
+Summary: Tools to handle multiplex network data more easily
+Author: Edwin de Jonge, Jan van der Laan
+Author-email: Edwin de Jonge <edwindjonge@gmail.com>, Jan van der Laan <djvanderlaan@gmail.com>
+Requires-Dist: duckdb>=1.4.4
+Requires-Dist: ibis-framework[duckdb]>=12.0.0
+Requires-Dist: networkx>=3.6.1
+Requires-Dist: pandas>=3.0.1
+Requires-Dist: pyarrow>=23.0.1
+Requires-Dist: pyarrow-hotfix>=0.7
+Requires-Dist: scipy>=1.17.1
+Requires-Python: >=3.13
+Project-URL: Homepage, https://codeberg.org/CBS-Networktools/muxpack.py
+Project-URL: Documentation, https://readthedocs.org
+Project-URL: Repository, https://codeberg.org/CBS-Networktools/muxpack.py
+Project-URL: Bug Tracker, https://codeberg.org/CBS-Networktools/muxpack.py/issues
+Description-Content-Type: text/markdown
+
+**Under heavy construction, do not use for serious work!**
+
+## Muxpack
+
+Muxpack is a Python implementation for working with multiplex network files.
+
+## Documentation
+
+Build docs locally using the same dependency path as Read the Docs:
+
+```bash
+uv sync --group docs
+uv run sphinx-build -b html docs docs/_build/html
+```
+
+The generated HTML is available in `docs/_build/html/index.html`.

muxpack-0.1.0/README.md

@@ -0,0 +1,16 @@
+**Under heavy construction, do not use for serious work!**
+
+## Muxpack
+
+Muxpack is a Python implementation for working with multiplex network files.
+
+## Documentation
+
+Build docs locally using the same dependency path as Read the Docs:
+
+```bash
+uv sync --group docs
+uv run sphinx-build -b html docs docs/_build/html
+```
+
+The generated HTML is available in `docs/_build/html/index.html`.

muxpack-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "muxpack"
+version = "0.1.0"
+description = "Tools to handle multiplex network data more easily"
+readme = "README.md"
+authors = [
+    { name = "Edwin de Jonge", email = "edwindjonge@gmail.com" },
+    { name = "Jan van der Laan", email = "djvanderlaan@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "duckdb>=1.4.4",
+    "ibis-framework[duckdb]>=12.0.0",
+    "networkx>=3.6.1",
+    "pandas>=3.0.1",
+    "pyarrow>=23.0.1",
+    "pyarrow-hotfix>=0.7",
+    "scipy>=1.17.1",
+]
+
+[project.urls]
+Homepage = "https://codeberg.org/CBS-Networktools/muxpack.py"
+Documentation = "https://readthedocs.org"
+Repository = "https://codeberg.org/CBS-Networktools/muxpack.py"
+"Bug Tracker" = "https://codeberg.org/CBS-Networktools/muxpack.py/issues"
+
+[project.scripts]
+muxpack = "muxpack:main"
+
+[build-system]
+requires = ["uv_build>=0.10.6,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "ruff>=0.15.4",
+]
+docs = [
+    "sphinx>=9.1.0",
+    "sphinx-rtd-theme>=3.0.0",
+]
+
+[tool.ruff.lint]
+extend-select = ["B"]

muxpack-0.1.0/src/muxpack/__init__.py

@@ -0,0 +1,17 @@
+from .check import check_edges, check_vertices
+from .io import load_network, save_network
+from .multiplexseries import MultiplexSeries
+from .multiplex import Multiplex
+from .to_csr_matrix import to_csr_matrix
+from .bipartite import Bipartite
+
+__all__ = [
+    "check_edges",
+    "check_vertices",
+    "load_network",
+    "Multiplex",
+    "MultiplexSeries",
+    "save_network",
+    "to_csr_matrix",
+    "Bipartite",
+]

muxpack-0.1.0/src/muxpack/bipartite.py

@@ -0,0 +1,99 @@
+from pathlib import Path
+from ibis import Table
+from . import io
+
+
+class Bipartite:
+    """
+    Lazy Bipartite storage
+    - sort on role_src, role_dst
+    """
+
+    edges: Table
+    role_src: str
+    role_dst: str
+    relationtype: str
+
+    def __init__(
+        self,
+        edges: Table,
+        role_src: str = "src",
+        role_dst: str = "dst",
+        relationtype: str = "relationtype",
+    ):
+        """
+        Initialize a bipartite graph with the given edges table and role labels.
+
+        Args:
+            - edges: table containing the bipartite edges.
+            - role_src: column name for the source role.
+            - role_dst: column name for the destination role.
+            - relationtype: column name for the relation type.
+        """
+        self.edges = edges
+        self.role_src = role_src
+        self.role_dst = role_dst
+        self.relationtype = relationtype
+
+    def project_to_src(self) -> Table:
+        """
+        Project the bipartite graph onto the source role, producing a unipartite edge table.
+        Two source nodes are connected if they share a common destination node.
+
+        Returns:
+            - Table with columns ``src``, ``dst``, and ``relationtype``.
+        """
+        E = self.edges
+        # TODO this is a explicit choice: relationtypes could be more complex, ie when two different role_src have
+        # an other relation with the same role_dst. Simplifying that right now
+        E_src = E.select(
+            src=self.role_src, p=self.role_dst, relationtype=self.relationtype
+        )
+        E_dst = E.select(dst=self.role_src, p=self.role_dst)
+
+        E = E_src.inner_join(E_dst, E_src.p == E_dst.p)
+        E = E.filter(E.src != E.dst)
+        E = E.select(["src", "dst", "relationtype"])
+        return E
+
+    def project_to_dst(self) -> Table:
+        """
+        Project the bipartite graph onto the destination role, producing a unipartite edge table.
+        Two destination nodes are connected if they share a common source node.
+
+        Returns:
+            - Table with columns ``src``, ``dst``, and ``relationtype``.
+        """
+        E = self.edges
+        # TODO this is a explicit choice: relationtypes could be more complex, ie when two different role_src have
+        # an other relation with the same role_dst. Simplifying that right now
+        # should we sort on role_src and role_dst or the other way around? For projection it does not matter, but for storage it does. We sort on role_src and role_dst for efficient projection, but that means that the projection to dst is less efficient. Maybe we should sort on role_dst and role_src instead?
+        E_src = E.select(
+            src=self.role_dst, p=self.role_src, relationtype=self.relationtype
+        )
+        E_dst = E.select(dst=self.role_dst, p=self.role_src)
+
+        E = E_src.inner_join(E_dst, E_src.p == E_dst.p)
+        E = E.filter(E.src != E.dst)
+        E = E.select(["src", "dst", "relationtype"])
+        return E
+
+    def save(self, dir: Path | str) -> None:
+        """
+        Save the bipartite graph to disk.
+        Edges are saved as a Parquet file and metadata (``role_src``, ``role_dst``,
+        ``relationtype``) as a JSON file. The ``edges`` property is updated to point
+        at the saved file.
+
+        Args:
+            - dir: path to the directory where the BiPartite graph will be saved.
+        """
+        io.save_bipartite(
+            edges=self.edges,
+            role_src=self.role_src,
+            role_dst=self.role_dst,
+            relationtype=self.relationtype,
+            dir=dir,
+        )
+        bp = io.read_bipartite(dir=dir)
+        self.edges = bp.edges

muxpack-0.1.0/src/muxpack/check.py

@@ -0,0 +1,97 @@
+from ibis.expr.types import Table
+from ibis import dtype
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def check_edges(edges: Table, check_period=True) -> bool:
+    """
+    Check that the edges table has the required columns and types.
+
+    Args:
+        - edges: the edges table to check.
+        - check_period: whether to require a ``period`` column.
+
+    Returns:
+        - ``True`` if the edges table is valid, ``False`` otherwise.
+    """
+
+    # the column types can be int32 or int64, but they must be integers, and the layer column must be a string
+    expect_types = {
+        "src": "integer",
+        "dst": "integer",
+        "period": "integer",
+        "layer": "string",
+        "relationtype": "integer",
+    }
+
+    if not check_period:
+        expect_types.pop("period", None)
+
+    if check_column_type(edges, expect_types):
+        return True
+
+    return False
+
+
+def check_vertices(vertices: Table, check_period=True) -> bool:
+    """
+    Check that the vertices table has the required columns and types.
+
+    Args:
+        - vertices: the vertices table to check.
+        - check_period: whether to require a ``period`` column.
+
+    Returns:
+        - ``True`` if the vertices table is valid, ``False`` otherwise.
+    """
+    required_columns = {"id", "period"} if check_period else {"id"}
+
+    if not required_columns.issubset(set(vertices.columns)):
+        logger.warning(f"Missing columns: {required_columns - set(vertices.columns)}")
+        return False
+
+    expect_types = {"id": "integer"}
+
+    if check_period:
+        expect_types["period"] = "integer"
+
+    if not check_column_type(vertices, expect_types):
+        return False
+
+    return True
+
+
+def check_column_type(t: Table, expected_types: dict[str, str]) -> bool:
+    """
+    Check that the columns in a table have the expected types.
+
+    Args:
+        - t: the table to check.
+        - expected_types: dictionary mapping column names to expected type strings
+          (e.g., ``"integer"``, ``"string"``).
+
+    Returns:
+        - ``True`` if all specified columns exist and have the expected types, ``False`` otherwise.
+    """
+    for column, expected_type in expected_types.items():
+        col = t[column]
+        if col is None:
+            logger.warning(f"Column '{column}' is missing.")
+            return False
+        coltype = col.type()
+        if expected_type == "integer" and coltype.is_integer():
+            continue
+        if expected_type == "string" and coltype.is_string():
+            continue
+        # most specific check, if the expected type is exactly the same as the column type, then it's valid
+        if dtype(expected_type) == coltype:
+            continue
+
+        logger.warning(
+            f"Incorrect type for column '{column}': '{coltype}', expected {expected_type}"
+        )
+        return False
+    return True

muxpack-0.1.0/src/muxpack/io.py

@@ -0,0 +1,271 @@
+import ibis
+
+from muxpack.bipartite import Bipartite
+from .multiplexseries import MultiplexSeries
+from pathlib import Path
+import os
+import logging
+from typing import Tuple
+
+logger = logging.getLogger(__name__)
+
+
+def load_network(dir: Path) -> MultiplexSeries:
+    """
+    Load a multiplex network from a directory containing Parquet files.
+
+    The expected directory structure is::
+
+        dir/
+            <period>/
+                edges/
+                    <layer>/
+                        *.parquet
+                vertices.parquet
+
+    Args:
+        - dir: path to the root directory containing the Parquet files.
+
+    Returns:
+        - MultiplexSeries loaded from the directory.
+    """
+    logger.info("Loading data from {dir}...")
+    con = ibis.duckdb.connect()
+
+    logger.info("Loading edges...")
+    edges = con.read_parquet(f"{dir}/*/edges/**/*.parquet", table_name="edges")
+
+    logger.info("Loading vertices")
+    try:
+        vertices = ibis.read_parquet(f"{dir}/*/vertices.parquet", table_name="vertices")
+    except Exception as e:
+        logger.info(f"No vertices found: {e}")
+        vertices = None
+
+    try:
+        relationtypes = ibis.read_parquet(f"{dir}/*/relationtypes.csv")
+    except Exception as e:
+        logger.info(f"No relationtypes found: {e}")
+        relationtypes = None
+
+    m = MultiplexSeries(edges=edges, vertices=vertices, relationtypes=relationtypes)
+    return m
+
+
+def save_network(
+    edges: ibis.Table,
+    vertices: ibis.Table,
+    dir: Path | str,
+    existing_data_behavior="delete_matching",
+    **kwargs,
+) -> Tuple[ibis.Table, ibis.Table]:
+    """
+    Save edges and vertices to disk following the muxpack directory structure.
+    The directory and all sub-directories are created if they do not exist.
+    Edges and vertices are not validated for consistency.
+
+    Args:
+        - edges: edge table to save.
+        - vertices: vertex table to save.
+        - dir: root path where the network will be saved.
+        - existing_data_behavior: passed through to ``pyarrow.dataset.write_dataset``.
+        - **kwargs: additional keyword arguments forwarded to ``pyarrow.dataset.write_dataset``.
+
+    Returns:
+        - Tuple of ``(edges, vertices)`` table objects pointing to the saved files.
+    """
+    E = edges
+    V = vertices
+    dir = Path(dir)
+
+    logger.info(f"Saving network to {dir}...")
+
+    # We do a manual partitioning to have maximum control.
+    # alternative and potentially more efficient would be partitioning using
+    # duckdb, however, that would pose some problems:
+    # - Hive naming convention does not follow the muxpack specification
+    # - Hive partitioning removes columns that are partitioned.
+    periods = E[["period"]].distinct().to_pandas().period
+
+    for period in periods:
+        period_dir = dir / f"{period}"
+        os.makedirs(period_dir, exist_ok=True)
+
+        # writing vertices
+        vertices_file = period_dir / "vertices.parquet"
+        V_period = V.filter(V.period == period)
+        V_period.to_parquet(vertices_file)
+
+        # writing edges
+        edges_dir = period_dir / "edges"
+        os.makedirs(edges_dir, exist_ok=True)
+        E_period = E.filter(E.period == period)
+        layers = E_period[["layer"]].distinct().to_pandas().layer
+        logger.info(f"layers: {layers}")
+        for layer in layers:
+            layer_dir = edges_dir / f"{layer}"
+            # TODO further partition?
+            os.makedirs(layer_dir, exist_ok=True)
+            E_period_layer = E_period.filter(E_period.layer == layer).order_by(
+                ["src", "relationtype", "dst"]
+            )
+            E_period_layer.to_parquet_dir(
+                layer_dir, existing_data_behavior=existing_data_behavior, **kwargs
+            )
+            logger.info(f"\t\tSaved layer {layer}")
+        logger.info(f"\tFinished saving period {period}")
+    logger.info(f"Finished saving network to {dir}.")
+
+    con = ibis.duckdb.connect()
+    edges = con.read_parquet(f"{dir}/*/edges/**/*.parquet", table_name="edges")
+    vertices = con.read_parquet(f"{dir}/*/vertices.parquet", table_name="vertices")
+    return edges, vertices
+
+
+def save_multiplex(
+    edges: ibis.Table,
+    vertices: ibis.Table,
+    dir: Path | str,
+    period: int | None,
+    existing_data_behavior="delete_matching",
+    **kwargs,
+) -> Tuple[ibis.Table, ibis.Table]:
+    """
+    Save a single-period multiplex to disk following the muxpack directory structure.
+    The directory and all sub-directories are created if they do not exist.
+    Edges and vertices are not validated for consistency.
+
+    Args:
+        - edges: edge table to save.
+        - vertices: vertex table to save.
+        - period: the period for this multiplex, or ``None`` to skip period filtering.
+        - dir: root path where the multiplex will be saved.
+        - existing_data_behavior: passed through to ``pyarrow.dataset.write_dataset``.
+        - **kwargs: additional keyword arguments forwarded to ``pyarrow.dataset.write_dataset``.
+
+    Returns:
+        - Tuple of ``(edges, vertices)`` table objects pointing to the saved files.
+    """
+    E = edges
+    V = vertices
+    dir = Path(dir)
+
+    logger.info(f"Saving multiplex to {dir}...")
+
+    # We do a manual partitioning to have maximum control.
+    # alternative and potentially more efficient would be partitioning using
+    # duckdb, however, that would pose some problems:
+    # - Hive naming convention does not follow the muxpack specification
+    # - Hive partitioning removes columns that are partitioned.
+    os.makedirs(dir, exist_ok=True)
+
+    # writing vertices
+    vertices_file = dir / "vertices.parquet"
+    if period is not None:
+        # test if period column is there, if not add it to
+        V = V.filter(V.period == period)
+    V.to_parquet(vertices_file)
+
+    # writing edges
+    edges_dir = dir / "edges"
+
+    os.makedirs(edges_dir, exist_ok=True)
+    E_period = E.filter(E.period == period)
+    layers = E_period[["layer"]].distinct().to_pandas().layer
+    logger.info(f"layers: {layers}")
+    for layer in layers:
+        layer_dir = edges_dir / f"{layer}"
+        # TODO further partition?
+        os.makedirs(layer_dir, exist_ok=True)
+        E_period_layer = E_period.filter(E_period.layer == layer).order_by(
+            ["src", "relationtype", "dst"]
+        )
+        E_period_layer.to_parquet_dir(
+            layer_dir, existing_data_behavior=existing_data_behavior, **kwargs
+        )
+        logger.info(f"\t\tSaved layer {layer}")
+    logger.info("\tFinished saving")
+
+    con = ibis.duckdb.connect()
+    edges = con.read_parquet(f"{dir}/edges/**/*.parquet", table_name="edges")
+    vertices = con.read_parquet(f"{dir}/vertices.parquet", table_name="vertices")
+    return edges, vertices
+
+
+def save_multiplexseries(
+    edges: ibis.Table, vertices: ibis.Table, dir: Path | str
+) -> None:
+    """
+    Save a multiplex series to disk by writing each period as a separate sub-directory.
+
+    Args:
+        - edges: edge table with a ``period`` column.
+        - vertices: vertex table with a ``period`` column.
+        - dir: root path where the multiplex series will be saved.
+    """
+    dir = Path(dir)
+    periods = (
+        edges.select("period").distinct().to_pyarrow().column("period").to_pylist()
+    )
+    for period in periods:
+        E = edges.filter(edges.period == period)
+        V = vertices.filter(vertices.period == period)
+        save_multiplex(edges=E, vertices=V, dir=dir / period)
+
+
+def save_bipartite(
+    edges: ibis.Table, role_src: str, role_dst: str, relationtype: str, dir: Path | str
+) -> None:
+    """
+    Save a bipartite graph to disk as a Parquet file plus a JSON metadata file.
+
+    Args:
+        - edges: edge table to save.
+        - role_src: column name used for the source role.
+        - role_dst: column name used for the destination role.
+        - relationtype: column name used for the relation type.
+        - dir: path to the directory where the files will be saved.
+    """
+    dir = Path(dir)
+    os.makedirs(dir, exist_ok=True)
+    edges.to_parquet(dir / "edges.parquet")
+    json_content = {
+        "role_src": role_src,
+        "role_dst": role_dst,
+        "relationtype": relationtype,
+    }
+    with open(dir / "metadata.json", "w") as f:
+        import json
+
+        json.dump(json_content, f)
+
+
+def read_bipartite(dir: Path | str) -> Bipartite:
+    """
+    Load a bipartite graph from disk.
+
+    Args:
+        - dir: path to the directory containing ``edges.parquet`` and ``metadata.json``.
+
+    Returns:
+        - BiPartite object with edges and metadata loaded from disk.
+    """
+    dir = Path(dir)
+    edges = ibis.read_parquet(dir / "edges.parquet")
+    with open(dir / "metadata.json", "r") as f:
+        import json
+
+        metadata = json.load(f)
+    role_src = metadata["role_src"]
+    role_dst = metadata["role_dst"]
+    relationtype = metadata["relationtype"]
+    return BiPartite(
+        edges=edges, role_src=role_src, role_dst=role_dst, relationtype=relationtype
+    )
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    m = load_network("data")
+
+    save_network(edges=m.edges, vertices=m.vertices, dir="data2")

muxpack-0.1.0/src/muxpack/multiplex.py

@@ -0,0 +1,141 @@
+import ibis
+
+from .check import check_edges, check_vertices
+from pathlib import Path
+from . import io
+import logging
+from scipy.sparse import csr_matrix
+import networkx as nx
+
+logger = logging.getLogger(__name__)
+
+
+class Multiplex:
+    """
+    A multiplex is a graph with multiple layers.
+    Each layer represents a different type of relationship between the same set of vertices, during one period.
+    For example, in a social network, one layer could represent friendships, while
+    another layer could represent professional connections.
+    For multiple periods, use MultiplexSeries.
+    """
+
+    #: The edges of the multiplex. This is a table with columns "src", "dst", "layer" and "relationtype".
+    edges: ibis.Table
+
+    #: The vertices of the multiplex. This is a table with a column "id" and optional additional columns.
+    vertices: ibis.Table
+
+    period: int | None
+
+    def __init__(
+        self, edges: ibis.Table, vertices: ibis.Table = None, period: int | None = None
+    ) -> None:
+        """
+        Initialize a multiplex with the given edges and vertices tables.
+
+        Args:
+            - edges: table with columns ``src``, ``dst``, ``layer``, and ``relationtype``.
+            - vertices: table with column ``id`` and optional additional columns.
+            - period: the period this multiplex belongs to, or ``None`` if not applicable.
+
+        Raises:
+            - ValueError: if the edges table does not satisfy the required schema.
+            - ValueError: if the vertices table does not satisfy the required schema.
+        """
+        if not check_edges(edges, check_period=False):
+            raise ValueError("Invalid edges table")
+
+        if vertices is not None and not check_vertices(vertices, check_period=False):
+            raise ValueError("Invalid vertices table")
+
+        self.period = period
+        self.edges = edges
+        # TODO derive vertices from edges if not provided
+        self.vertices = vertices
+
+    def layers(self) -> list[str]:
+        """
+        Get the list of layers present in the multiplex.
+
+        Returns:
+            - List of layer names.
+        """
+        layers = self.edges[["layer"]].distinct().to_pandas().layer.tolist()
+        return layers
+
+    def update_vertices(self) -> None:
+        """
+        Update the vertices table by deriving it from the edges table.
+        This is useful when the vertices table was not provided at initialization.
+        ``self.vertices`` is updated in place.
+        """
+        src = self.edges.select(id="src").distinct()
+        dst = self.edges.select(id="dst").distinct()
+
+        V = src.union(dst, distinct=True).to_pyarrow()
+        self.vertices = ibis.memtable(V)
+
+    def to_csr_matrix(self) -> csr_matrix[bool]:
+        """
+        Transform the multiplex into a sparse matrix, collapsing all layers into one.
+        To keep layers separate, use ``to_csr_matrices`` instead.
+
+        Returns:
+            - Sparse boolean matrix of shape ``(n_vertices, n_vertices)``.
+        """
+        from .to_csr_matrix import to_row_col_idx, idx_to_csr_matrix
+
+        idx = to_row_col_idx(self.edges, self.vertices)
+        M = idx_to_csr_matrix(idx, self.vertices)
+        return M
+
+    def to_csr_matrices(self) -> dict[str, csr_matrix]:
+        """
+        Transform the multiplex into a dictionary of sparse matrices, one per layer.
+
+        Returns:
+            - Dictionary mapping layer name to a sparse boolean matrix of shape ``(n_vertices, n_vertices)``.
+        """
+        from .to_csr_matrix import to_row_col_idx, idx_to_csr_matrix
+
+        layers = self.layers()
+        matrices = {}
+        for layer in layers:
+            idx = to_row_col_idx(
+                self.edges.filter(self.edges.layer == layer), self.vertices
+            )
+            M = idx_to_csr_matrix(idx, self.vertices)
+            matrices[layer] = M
+        return matrices
+
+    def to_networkx(self) -> nx.MultiDiGraph:
+        """
+        Convert the multiplex to a NetworkX MultiDiGraph.
+
+        Returns:
+            - NetworkX MultiDiGraph built from the CSR matrix representation of the edges.
+        """
+        from .networkx import to_MultiDiGraph
+
+        return to_MultiDiGraph(self.edges, self.vertices)
+
+    def save(self, dir: Path | str, **kw_args) -> None:
+        """
+        Save the multiplex to disk.
+        The directory is created if it does not exist; existing files are overwritten.
+        Saving also evaluates the lazy ``edges`` and ``vertices`` expressions and
+        updates them to point at the saved files, which can improve subsequent performance.
+
+        Args:
+            - dir: path to the directory where the Multiplex will be saved.
+            - **kw_args: additional keyword arguments forwarded to ``io.save_multiplex``.
+        """
+        edges = self.edges
+        vertices = self.vertices
+        if vertices is None:
+            self.update_vertices()
+            vertices = self.vertices
+        period = self.period
+        edges, vertices = io.save_multiplex(edges, vertices, period, dir=dir, **kw_args)
+        self.edges = edges
+        self.vertices = vertices

muxpack-0.1.0/src/muxpack/multiplexseries.py

@@ -0,0 +1,273 @@
+import ibis
+
+from .check import check_edges, check_vertices
+from pathlib import Path
+from . import io
+from .multiplex import Multiplex
+import logging
+from typing import Tuple
+
+logger = logging.getLogger(__name__)
+
+
+class MultiplexSeries:
+    """
+    A multiplexseries is a series of Multiplex graphs with multiple layers, spanning multiple periods.
+    """
+
+    #: The edges of the multiplex. This is a table with columns "src", "dst", "period", "layer" and "relationtype".
+    edges: ibis.Table
+
+    #: The vertices of the multiplex. This is a table with a column "id","period" and optional additional columns.
+    vertices: ibis.Table | None
+
+    #
+    vertex_ids: ibis.Table
+
+    relationtypes: ibis.Table | None
+
+    def __init__(
+        self,
+        edges: ibis.Table,
+        vertices: ibis.Table = None,
+        relationtypes: ibis.Table = None,
+    ) -> None:
+        """
+        Initialize a multiplex series with the given edges and vertices tables.
+
+        Args:
+            - edges: table with columns ``src``, ``dst``, ``period``, ``layer``, and ``relationtype``.
+            - vertices: table with column ``id``, ``period``, and optional additional columns.
+              Must have a ``period`` column because the edges table has one.
+            - relationtypes: table with columns ``relationtype``, ``layer``, ``label``,
+              and optional additional columns.
+
+        Raises:
+            - ValueError: if the edges table does not satisfy the required schema.
+            - ValueError: if the vertices table does not satisfy the required schema.
+        """
+        if not check_edges(edges):
+            raise ValueError("Invalid edges table")
+
+        if vertices is not None and not check_vertices(vertices):
+            raise ValueError("Invalid vertices table")
+
+        self.edges = edges
+        # TODO derive vertices from edges if not provided
+        self.vertices = vertices
+        self.relationtypes = relationtypes
+
+        if not vertices is None:
+            logger.info("Vertices table provided, using it as is.")
+            self.vertex_ids = vertices[["id"]].distinct()
+
+    def periods(self) -> list[int]:
+        """
+        Get the list of periods present in the multiplex series.
+
+        Returns:
+            - Sorted list of period values.
+        """
+        periods = (
+            self.edges.select(self.edges.period)
+            .distinct()
+            .order_by("period")
+            .to_pyarrow()
+            .column("period")
+            .to_pylist()
+        )
+        # periods = self.edges[["period"]].distinct().to_pandas().period.tolist()
+        return periods
+
+    def layers(self) -> list[str]:
+        """
+        Get the list of layers present in the multiplex series.
+
+        Returns:
+            - Sorted list of layer names.
+        """
+        layers = (
+            self.edges.select(self.edges.layer)
+            .distinct()
+            .order_by("layer")
+            .to_pyarrow()
+            .column("layer")
+            .to_pylist()
+        )
+        return layers
+
+    def update_vertices(self) -> None:
+        """
+        Update the vertices table by deriving it from the edges table.
+        This is useful when the vertices table was not provided at initialization.
+        Both ``self.vertices`` and ``self.vertex_ids`` are updated in place.
+        """
+        src = self.edges.select(id="src", period="period").distinct()
+        dst = self.edges.select(id="dst", period="period").distinct()
+
+        V = src.union(dst, distinct=True)
+        V_all = V.select(V.id)
+        self.vertices = ibis.memtable(V.to_pyarrow())
+        self.vertex_ids = ibis.memtable(V_all.to_pyarrow())
+
+    def update_relationtypes(self) -> None:
+        """
+        Update the relationtypes table by deriving it from the edges table.
+        This is useful when the relationtypes table was not provided at initialization.
+        A ``label`` column is constructed as ``"<layer>_<relationtype>"``.
+        ``self.relationtypes`` is updated in place.
+        """
+        relationtypes = (
+            self.edges.select(self.edges.relationtype, self.edges.layer)
+            .distinct()
+            .order_by("layer", "relationtype")
+            .to_pandas()
+            .assign(
+                label=lambda df: (
+                    df["layer"].astype(str) + "_" + df["relationtype"].astype(str)
+                )
+            )
+        )
+        logger.debug(
+            f"Updated relationtypes table with {len(relationtypes)} unique relationtypes."
+        )
+        self.relationtypes = ibis.memtable(relationtypes)
+
+    def get_multiplex(self, period: int) -> Multiplex:
+        """
+        Return the multiplex for a specific period.
+
+        Args:
+            - period: the period to retrieve.
+
+        Returns:
+            - Multiplex object containing only the edges and vertices for the given period.
+        """
+        E_y = self.edges.filter(self.edges.period == period)
+        if self.vertices is not None:
+            V_y = self.vertices.filter(self.vertices.period == period)
+        else:
+            V_y = None
+        return Multiplex(edges=E_y, vertices=V_y, period=period)
+
+    def multiplexes(self) -> list[Tuple[int, Multiplex]]:
+        """
+        Return all multiplexes in the series, one per period.
+
+        Returns:
+            - List of ``(period, Multiplex)`` tuples, ordered by period.
+        """
+        periods = self.periods()
+        return [(period, self.get_multiplex(period)) for period in periods]
+
+    def add_filter(
+        self,
+        periods: list[int] = None,
+        layers: list[str] = None,
+        relationtypes: list[int] = None,
+        src: list[int] = None,
+        dst: list[int] = None,
+    ) -> None:
+        """
+        Apply a filter to the multiplex series in place.
+        Filtering is lazy: the filter is only executed when saving or converting
+        to another format. Passing ``None`` or an empty list for any argument
+        means no filtering is applied for that dimension.
+
+        For advanced filtering, modify the ``edges`` property directly using
+        ibis expressions.
+
+        Args:
+            - periods: list of periods to keep.
+            - layers: list of layer names to keep.
+            - relationtypes: list of relationtype values to keep.
+            - src: list of source vertex ids (ego) to keep.
+            - dst: list of destination vertex ids (non-ego) to keep.
+        """
+        E = self.edges
+
+        flt: list[ibis.BooleanValue] = []
+
+        if periods is not None and len(periods) > 0:
+            flt.append(E.period.isin(periods))
+
+        if layers is not None and len(layers) > 0:
+            flt.append(E.layer.isin(layers))
+
+        if relationtypes is not None and len(relationtypes) > 0:
+            flt.append(E.relationtype.isin(relationtypes))
+
+        if src is not None and len(src) > 0:
+            vid = ibis.memtable({"id": src})
+            # we use semi join because we expect the vertex list to be large
+            E = E.semi_join(vid, E.src == vid.id)
+
+        if dst is not None and len(dst) > 0:
+            vid = ibis.memtable({"id": dst})
+            # we use semi join because we expect the vertex list to be large
+            E = E.semi_join(vid, E.dst == vid.id)
+
+        logger.debug("Filter: f{flt}")
+        if len(flt):
+            E = E.filter(flt)
+
+        self.edges = E
+
+    def __copy__(self) -> "MultiplexSeries":
+        """
+        Return a shallow copy of this MultiplexSeries.
+
+        Returns:
+            - A new MultiplexSeries sharing the same ``edges`` and ``vertices`` tables.
+        """
+        return MultiplexSeries(self.edges, self.vertices)
+
+    def collapse(self) -> Multiplex:
+        """
+        Collapse the multiplex series into a single Multiplex by discarding period
+        information. Duplicate edges across periods are removed. This is useful
+        for analyses that do not require temporal information.
+
+        Returns:
+            - Multiplex containing all distinct edges across all periods, with ``period=None``.
+        """
+        E = self.edges.select(["src", "dst", "layer", "relationtype"]).distinct()
+        if self.vertices is not None:
+            V = self.vertices.select("id").distinct()
+        else:
+            V = None
+        return Multiplex(edges=E, vertices=V, period=None)
+
+    def collapse_to(self, dir: Path | str) -> None:
+        """
+        Collapse the multiplex series and save the result to disk.
+        This is a convenience method equivalent to calling ``collapse()`` followed
+        by ``Multiplex.save()``.
+
+        Args:
+            - dir: path to the directory where the collapsed Multiplex will be saved.
+        """
+        m = self.collapse()
+        return m.save(dir=dir)
+
+    def save(self, dir: Path | str, **kw_args) -> None:
+        """
+        Save the multiplex series to disk.
+        The directory is created if it does not exist; existing files are overwritten.
+        Saving also evaluates the lazy ``edges`` and ``vertices`` expressions and
+        updates them to point at the saved files, which can improve subsequent
+        performance.
+
+        Args:
+            - dir: path to the directory where the MultiplexSeries will be saved.
+            - **kw_args: additional keyword arguments forwarded to ``io.save_network``.
+        """
+        edges = self.edges
+        vertices = self.vertices
+        if vertices is None:
+            mp = MultiplexSeries(edges=self.edges)
+            mp.update_vertices()
+            vertices = mp.vertices
+        E, V = io.save_network(edges, vertices, dir=dir, **kw_args)
+        self.edges = E
+        self.vertices = V

muxpack-0.1.0/src/muxpack/networkx.py

@@ -0,0 +1,20 @@
+import networkx as nx
+import ibis
+from .to_csr_matrix import to_csr_matrix
+
+
+def to_MultiDiGraph(edges: ibis.Table, vertices: ibis.Table) -> nx.MultiDiGraph:
+    """
+    Convert an edge list and vertex table to a NetworkX MultiDiGraph.
+
+    Args:
+        - edges: table with ``src`` and ``dst`` columns.
+        - vertices: table with an ``id`` column.
+
+    Returns:
+        - NetworkX MultiDiGraph built from the CSR matrix representation of the edges.
+    """
+    # problem: this generates
+    csr = to_csr_matrix(edges, vertices)
+    mdg = nx.MultiDiGraph(csr)
+    return mdg

muxpack-0.1.0/src/muxpack/to_csr_matrix.py

@@ -0,0 +1,132 @@
+from ibis import row_number, Table
+import ibis
+from scipy.sparse import csr_matrix
+from muxpack.multiplex import Multiplex
+from typing import Tuple, Generator
+
+import logging
+
+logger = logging.getLogger(__name__)
+# from collections.abc import Generator
+
+
+def to_row_col_idx(edges: Table, vertices: Table) -> Table:
+    """
+    Turn an edge list into a row/column index table based on the given vertices table.
+
+    Args:
+        - edges: table with ``src`` and ``dst`` columns.
+        - vertices: table with an ``id`` column; edges not referencing a vertex in this
+          table are filtered out.
+
+    Returns:
+        - Table with columns ``data``, ``row``, and ``col`` containing the boolean edge
+          indicator and the row/column indices corresponding to vertex positions in
+          ``vertices``. Can be passed directly to ``idx_to_csr_matrix``.
+    """
+    v = vertices.select("id").mutate(idx=row_number())
+    row = v.select(src="id", row="idx")
+    col = v.select(dst="id", col="idx")
+
+    # may sum the number of columns
+    idx_edges = (
+        edges[["src", "dst"]]
+        .distinct()
+        .inner_join(row, "src")
+        .inner_join(col, "dst")
+        .mutate(data=True)
+        .select("data", "row", "col")
+    )
+    logger.debug(
+        f"Created row-col index table with {idx_edges.count().execute()} edges."
+    )
+    return idx_edges
+
+
+def idx_to_csr_matrix(idx: Table, vertices: Table) -> csr_matrix:
+    """
+    Convert a row-column index table to a CSR sparse matrix.
+
+    Args:
+        - idx: table with columns ``data``, ``row``, and ``col``, as produced by
+          ``to_row_col_idx``.
+        - vertices: table with an ``id`` column; its row count determines the matrix size.
+
+    Returns:
+        - Square CSR sparse matrix of shape ``(n_vertices, n_vertices)``.
+    """
+    # TODO maybe to_parquet()?
+    coo = idx.execute()
+    logger.debug(f"COO matrix data: {coo}")
+
+    n = vertices.count().execute()
+    logger.debug(f"Number of vertices: {n}")
+    M = csr_matrix((coo["data"], (coo["row"], coo["col"])), shape=(n, n))
+    return M
+
+
+def to_csr_matrix(edges: Table, vertices: Table | None) -> csr_matrix:
+    """
+    Transform an edge list into a sparse matrix (csr_matrix).
+
+    Args:
+        - edges: table with ``src`` and ``dst`` columns.
+        - vertices: table with an ``id`` column; edges are filtered to vertices present
+          in this table. Pass ``None`` to derive vertices from the edges table.
+
+    Returns:
+        - Square CSR sparse matrix of shape ``(n_vertices, n_vertices)``.
+    """
+    # vertices may contain multiple periods
+    if vertices is not None:
+        vertices = vertices[["id"]].distinct()
+    edges_row_col = to_row_col_idx(edges, vertices=vertices)
+    M = idx_to_csr_matrix(edges_row_col, vertices=vertices)
+    return M
+
+
+def to_period_csr_matrix(
+    edges: Table, vertices: Table | None, periods: list[int] = []
+) -> Generator[Tuple[csr_matrix, int]]:
+    """
+    Generate a sparse matrix for each period.
+
+    Args:
+        - edges: table with columns ``src``, ``dst``, and ``period``.
+        - vertices: table with columns ``id`` and ``period``, or ``None`` to derive
+          vertices from the edges table for each period.
+        - periods: list of periods to generate matrices for. If empty, all periods
+          present in ``edges`` are used.
+
+    Returns:
+        - Generator of ``(csr_matrix, period)`` tuples, one per period.
+    """
+    if len(periods) == 0:
+        periods = edges[["period"]].distinct().to_pandas().period.tolist()
+    for period in periods:
+        E_y = edges.filter(edges.period == period)
+        if vertices is not None:
+            V_y = vertices.filter(vertices.period == period)
+        else:
+            V_y = None
+
+        yield to_csr_matrix(E_y, V_y), period
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.DEBUG)
+    import pandas as pd
+
+    edges = pd.DataFrame({"src": [100, 100], "dst": [300, 200]})
+    vertices = pd.DataFrame({"id": [100, 200, 300]})
+
+    E = ibis.memtable(edges)
+    V = ibis.memtable(vertices)
+
+    V1 = V.filter(V.id < 250)
+    idx = to_row_col_idx(E, V1)
+    M1 = idx_to_csr_matrix(idx, V1)
+    print(f"M1 = {M1}")
+
+    M = to_csr_matrix(E, V)
+    print(M)